▪ Overall Grouped

Rates Overall Grouped API returns rates overall data for the specified {Location} grouped by the field defined by the group_type query parameter.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/rates/overall/grouped

Path Parameters

Name	Description	Type	Examples
*{billing_plan}	Billing plan to be applied to the call.	string	ondemand
*{account_id}	Provided identifier of the account.	string
`/sample`	Filter data for POIs that are included in the sample (subset of POIs that statistically replicates the population of the corresponding location).	string

/sample optional path parameter

Inserting optional path parameter /sample in the following position:

/v4/{billing_plan}/account/{account_id}/locations/rates/sample/…

will filter data for POIs that are included in the sample (subset of POIs that statistically replicates the population of the corresponding location).

Header Parameters

Name	Description	Type	Examples
*x-api-key	Provided API key `{x_api_key}` that allows authentication.	string
*Authorization	Provided token `{jwt_bearer}` that allows authorization.	string	Bearer `{jwt_bearer}`

Query Parameters

Name	Description	Type	Examples	Default
*{Location}	Location identifier.	Geospatial	Area GeometryID Circle
*from	Start date of timeframe.	date	2020-01-01
*to	End date of timeframe.	date	2020-12-31
*group_type	Field for which perform grouping.	string	poi_industry poi_category poi_class
ⓝ percentile	Request percentile expressed in the range (0, 1). Median value 0.5 will always be implicitly requested.	decimal		0.5
ⓝ poi_class	Filter POIs with `"category": "hotel"` by stars rating in the range [1,5].	int	4
ⓝ poi_industry	Filter by POI Industry.	string	Dictionary
ⓝ poi_category	Filter by POI Category.	string	Dictionary
ⓝ facility	Filter offers by included facility.	string	breakfast lunch dinner
guests	Filter offers by number of allowed guests.	int	1	2 (only when `group_type` is not equal to `guests`)
refundable	Filter offers that can be refunded.	boolean	true false
scan_last_day	Filter data according to a less recent offers detection in the range [1,10] (from most recent to oldest offers detection day).	int	5	1 (only when `group_type` is not equal to `scan_last_day`)
page	Requested page number for paginated results.	int		1
page_size	Requested page size for paginated results in the range [1, 100].	int		25

Supported values for group_type

poi_industry
poi_category
poi_class
guests
scan_last_day

Supported values for facility

breakfast
lunch
dinner

Example

curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/rates/overall/grouped?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&group_type=poi_class' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Example /sample

curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/rates/sample/overall/grouped?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&group_type=poi_class' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Rates Overall Grouped data has been successfully returned.

Body

LocationRatesGroupedOverall

Field	Description	Type
*results	Paginated list of rates overall data grouped by `group_type` requested field.	array[LocationRatesGroupedOverallElement]
paging	Response pagination.	Paging

LocationRatesGroupedOverallElement

Field	Description	Type
*group	Field value within the requested grouping by field.	string
average	Average accommodation offers price in Euros.	decimal
*percentiles	Accommodation offers percentiles values expressed in Euros.	array[Percentile]
*poi	Count of POIs with accommodation offers within the group.	PartitionCount

Percentile

Field	Description	Type	Examples
*request	Requested percentile expressed in the range (0, 1), e.g. 0.5 (the median).	decimal	0.5
*response	Resulting value of the `request` percentile.	decimal	73.00

PartitionCount

Field	Description	Type
partition	Count incidence percentage of the group's elements over total elements.	int
count	Total elements of the group.	int

Paging

Field	Description	Type
last	A relative URI to the last page.	string
first	A relative URI to the first page.	string
prev	A relative URI to the previous page.	string
next	A relative URI to the next page.	string
current	A relative URI to the current page.	string
pages	A set of relative URIs calculated around the current page.	Page
elements	All indexes shown on the current page.	array[int]
total	The number of all elements that API can retrieve.	int
size	The selected page size.	int

Page

Field	Description	Type
number	Number of the page.	int
uri	URI of the page.	string

Example

{
    "results": [
        {
            "group": "1",
            "average": 76.56,
            "percentiles": [
                {
                    "request": 0.5,
                    "response": 62.373135
                }
            ],
            "poi": {
                "partition": 3.91,
                "count": 25
            }
        },
        {
            "group": "2",
            "average": 116.94,
            "percentiles": [
                {
                    "request": 0.5,
                    "response": 78.117676
                }
            ],
            "poi": {
                "partition": 10.17,
                "count": 65
            }
        },
        {
            "group": "3",
            "average": 114.9,
            "percentiles": [
                {
                    "request": 0.5,
                    "response": 86.35156
                }
            ],
            "poi": {
                "partition": 42.25,
                "count": 270
            }
        },
        {
            "group": "4",
            "average": 185.51,
            "percentiles": [
                {
                    "request": 0.5,
                    "response": 151.28252
                }
            ],
            "poi": {
                "partition": 38.65,
                "count": 247
            }
        },
        {
            "group": "5",
            "average": 795.13,
            "percentiles": [
                {
                    "request": 0.5,
                    "response": 516.3026
                }
            ],
            "poi": {
                "partition": 5.01,
                "count": 32
            }
        }
    ],
    "paging": {
        "last": "/rates/overall/grouped?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-07-01",
        "first": "/rates/overall/grouped?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-07-01",
        "prev": null,
        "next": null,
        "current": "/rates/overall/grouped?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-07-01",
        "pages": [
            {
                "number": 1,
                "uri": "/rates/overall/grouped?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-07-01"
            }
        ],
        "total": 5,
        "size": 25,
        "elements": [
            1,
            2,
            3,
            4,
            5
        ]
    }
}