▪ Overall Series

Rates Overall Series API returns a time-based rates overall data series for the specified {Location}, grouped by a time period.

Request

Endpoint

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

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
*period	Time unit of the series.	string	day week month
ⓝ 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
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

Supported values for period

day
week
month

Supported values for facility

breakfast
lunch
dinner

Example

curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/rates/overall/series?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&period=month' \
-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/series?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&period=month' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

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

Body

LocationRatesSeriesOverall

Field	Description	Type
series	Rates overall data series for the requested timeframe and period.	array[LocationRatesSeriesOverallElement]

LocationRatesSeriesOverallElement

Field	Description	Type
*period	Date representing the requested period, corresponding to the first day of the period. `day`: the day itself. `week`: first day of the corresponding week. `month`: first day of the corresponding month.	date
*value	Rates overall data of corresponding `period`.	LocationRatesOverall

LocationRatesOverall

Field	Description	Type	Examples
*poi	Count of POIs with accommodation offers within the group.	PartitionCount
average	Average accommodation offers price in Euros.	decimal	88.44
*percentiles	Accommodation offers percentiles values expressed in Euros.	array[Percentile]

PartitionCount

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

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

Value of $.series[*].value.poi.partition

For non-grouped API calls, this value will always be 100.0: since no grouping is taking place, the total is considered as one whole group.

Example

{
    "series": [
        {
            "period": "2021-01-01",
            "value": {
                "poi": {
                    "partition": 100.0,
                    "count": 421
                },
                "average": 207.81,
                "percentiles": [
                    {
                        "request": 0.5,
                        "response": 115.470055
                    }
                ]
            }
        },
        {
            "period": "2021-02-01",
            "value": {
                "poi": {
                    "partition": 100.0,
                    "count": 1390
                },
                "average": 186.39,
                "percentiles": [
                    {
                        "request": 0.5,
                        "response": 99.43664
                    }
                ]
            }
        }
    ]
}