▪ Overall Series Grouped
Rates Overall Series Grouped API returns a time-based rates overall data series for the specified {Location}, grouped by time unit (period) and another additional field (group_type).
Request
Endpoint
GET
/v4/{billing_plan}/account/{account_id}/locations/rates/overall/series/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 | AreaGeometryIDCircle | |
| *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 | dayweekmonth | |
| *group_type | Field for which perform grouping. | string | poi_industrypoi_categorypoi_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 | breakfastlunchdinner | |
| 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 | truefalse | |
| 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 period
- day
- week
- month
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/series/grouped?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&period=month&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/series/grouped?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&period=month&group_type=poi_class' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \
Response
Status
| Status | Description |
|---|---|
| 200 | Rates Overall Series Grouped data has been successfully returned. |
Body
LocationRatesGroupedSeriesOverall
| Name | Description | Type |
|---|---|---|
| *results | Paginated list of time-based rates overall data series grouped by group_type requested field. |
array[LocationRatesGroupedSeriesOverallElement] |
| paging | Response pagination. | Paging |
LocationRatesGroupedSeriesOverallElement
| Field | Description | Type |
|---|---|---|
| *group | Field value within the requested grouping by field. | string |
| *series | Rates overall data series of corresponding group. |
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 |
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",
"series": [
{
"period": "2021-01-01",
"value": {
"poi": {
"partition": 4.96,
"count": 12
},
"average": 85.09,
"percentiles": [
{
"request": 0.5,
"response": 61.832897
}
]
}
},
{
"period": "2021-02-01",
"value": {
"poi": {
"partition": 4.37,
"count": 18
},
"average": 72.43,
"percentiles": [
{
"request": 0.5,
"response": 54.13138
}
]
}
}
]
},
{
"group": "2",
"series": [
{
"period": "2021-01-01",
"value": {
"poi": {
"partition": 8.26,
"count": 20
},
"average": 118.44,
"percentiles": [
{
"request": 0.5,
"response": 82.20162
}
]
}
},
{
"period": "2021-02-01",
"value": {
"poi": {
"partition": 10.19,
"count": 42
},
"average": 110.67,
"percentiles": [
{
"request": 0.5,
"response": 69.81566
}
]
}
}
]
},
{
"group": "3",
"series": [
{
"period": "2021-01-01",
"value": {
"poi": {
"partition": 30.99,
"count": 75
},
"average": 147.05,
"percentiles": [
{
"request": 0.5,
"response": 79.696205
}
]
}
},
{
"period": "2021-02-01",
"value": {
"poi": {
"partition": 41.75,
"count": 172
},
"average": 121.16,
"percentiles": [
{
"request": 0.5,
"response": 73.32997
}
]
}
}
]
},
{
"group": "4",
"series": [
{
"period": "2021-01-01",
"value": {
"poi": {
"partition": 48.35,
"count": 117
},
"average": 176.58,
"percentiles": [
{
"request": 0.5,
"response": 137.83028
}
]
}
},
{
"period": "2021-02-01",
"value": {
"poi": {
"partition": 39.08,
"count": 161
},
"average": 163.56,
"percentiles": [
{
"request": 0.5,
"response": 127.948845
}
]
}
}
]
},
{
"group": "5",
"series": [
{
"period": "2021-01-01",
"value": {
"poi": {
"partition": 7.44,
"count": 18
},
"average": 706.4,
"percentiles": [
{
"request": 0.5,
"response": 395.60114
}
]
}
},
{
"period": "2021-02-01",
"value": {
"poi": {
"partition": 4.61,
"count": 19
},
"average": 749.85,
"percentiles": [
{
"request": 0.5,
"response": 415.52185
}
]
}
}
]
}
],
"paging": {
"last": "/rates/overall/series/grouped?page=1&page_size=25&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-02-28",
"first": "/rates/overall/series/grouped?page=1&page_size=25&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-02-28",
"prev": null,
"next": null,
"current": "/rates/overall/series/grouped?page=1&page_size=25&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-02-28",
"pages": [
{
"number": 1,
"uri": "/rates/overall/series/grouped?page=1&page_size=25&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&group_type=poi_class&to=2021-02-28"
}
],
"total": 5,
"size": 25,
"elements": [
1,
2,
3,
4,
5
]
}
}