▪ Overall Series Compare
Rates Overall Series Compare API returns two, time-based rates overall data series at once: one defined by the specified {Location} and [from,to] query parameters and another defined by compare_ prefixed query parameters (or auto-calculated with default values where specified).
Additional comparative time-based data series between the two data series are returned as well.
Request
Endpoint
GET
/v4/{billing_plan}/account/{account_id}/locations/rates/overall/series/compare
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/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} | Actual location identifier. | Geospatial | AreaGeometryIDCircle | |
| *from | Start date of actual timeframe. | date | 2020-01-01 | |
| *to | End date of actual timeframe. | date | 2020-12-31 | |
| *period | Time unit of the series. | string | dayweekmonth | |
| {ComparisonLocation} | Comparison location identifier. | Comparison |
ComparisonAreaComparisonGeometryIDComparisonCircle | Same as {Location}. |
| compare_from | Start date of comparison timeframe. | date | 2020-07-01 | One year before from. |
| compare_to | End date of comparison timeframe. | date | 2021-01-01 | One year before to. |
| ⓝ percentile | Request percentile expressed in the range (0, 1).Median value 0.5 will always be implicitly requested. | decimal | 0.5 | |
| ⓝ poi_classⓝ compare_poi_class | Filter POIs with "category": "hotel" by stars rating in the range [1,5]. |
int | 4 | |
| ⓝ poi_industryⓝ compare_poi_industry | Filter by POI Industry. | string | Dictionary | |
| ⓝ poi_categoryⓝ compare_poi_category | Filter by POI Category. | string | Dictionary | |
| ⓝ facilityⓝ compare_facility | Filter offers by included facility. | string | breakfastlunchdinner | |
| guestscompare_guests | Filter offers by number of allowed guests. | int | 1 | 2 |
| refundablecompare_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 |
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/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&compare_from=2020-11-01&compare_to=2020-12-31&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/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&compare_from=2020-11-01&compare_to=2020-12-31&period=month' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \
Response
Status
| Status | Description |
|---|---|
| 200 | Rates Overall Series Compare data has been successfully returned. |
Body
LocationRatesComparedSeriesOverall
| Field | Description | Type |
|---|---|---|
| actual | Rates overall data for the actual timeframe. | LocationRatesComparableSeriesOverall |
| comparison | Rates overall data for the comparison timeframe. | LocationRatesComparableSeriesOverall |
| variation | Calculated difference between actual and comparison. |
LocationRatesSeriesOverallVariation |
LocationRatesComparableSeriesOverall
| Field | Description | Type |
|---|---|---|
| timeframe | Reference date range. | Timeframe |
| value | Rates overall data series for the corresponding timeframe. |
LocationRatesSeriesOverall |
Timeframe
| Field | Description | Type |
|---|---|---|
| *from | Start date of timeframe. | date |
| *to | End date of timeframe. | date |
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 |
LocationRatesSeriesOverallVariation
| Field | Description | Type |
|---|---|---|
| series | Rates overall data series for the requested timeframe and period. | array[LocationRatesSeriesOverallVariationElement] |
LocationRatesSeriesOverallVariationElement
| Field | Description | Type |
|---|---|---|
| *actual_period | Date representing the actual 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 |
| *comparison_period | Date representing the comparison 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 variation data between actual_period and comparison_period. |
LocationRatesOverallVariation |
LocationRatesOverallVariation
| Field | Description | Type |
|---|---|---|
| average | Average accommodation offers price variation in Euros. | Variation |
| *percentiles | Accommodation offers percentiles variations expressed in Euros. | array[PercentileVariation] |
| poi | Count variation of POIs with accommodation offers within the group. | PartitionVariation |
Variation
| Field | Description | Type | Examples |
|---|---|---|---|
| value | Difference between actual value and comparison value. |
decimal | 1.12 |
| variation | The explicit variation polarity. It is null when values are not available in both timeframes. |
string | POSITIVE NEUTRAL NEGATIVE |
PercentileVariation
| Field | Description | Type | Examples |
|---|---|---|---|
| *request | Requested percentile expressed in the range (0, 1), e.g. 0.5 (the median). | decimal | 0.5 |
| *response | Resulting variation value of the request percentile. |
Variation |
Value of $.actual,comparison.value.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
{
"actual": {
"timeframe": {
"from": "2021-01-01",
"to": "2021-02-28"
},
"value": {
"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
}
]
}
}
]
}
},
"comparison": {
"timeframe": {
"from": "2020-11-01",
"to": "2020-12-31"
},
"value": {
"series": [
{
"period": "2020-11-01",
"value": {
"poi": {
"partition": 100.0,
"count": 496
},
"average": 192.18,
"percentiles": [
{
"request": 0.5,
"response": 97.674866
}
]
}
},
{
"period": "2020-12-01",
"value": {
"poi": {
"partition": 100.0,
"count": 459
},
"average": 194.69,
"percentiles": [
{
"request": 0.5,
"response": 106.6192
}
]
}
}
]
}
},
"variation": {
"series": [
{
"actual_period": "2021-01-01",
"comparison_period": "2020-11-01",
"value": {
"average": {
"value": 15.630005,
"variation": "POSITIVE"
},
"percentiles": [
{
"request": 0.5,
"response": {
"value": 17.8,
"variation": "POSITIVE"
}
}
],
"poi": {
"partition": {
"value": 0.0,
"variation": "NEUTRAL"
},
"count": {
"value": -75,
"variation": "NEGATIVE"
}
}
}
},
{
"actual_period": "2021-02-01",
"comparison_period": "2020-12-01",
"value": {
"average": {
"value": -8.300003,
"variation": "NEGATIVE"
},
"percentiles": [
{
"request": 0.5,
"response": {
"value": -7.18,
"variation": "NEGATIVE"
}
}
],
"poi": {
"partition": {
"value": 0.0,
"variation": "NEUTRAL"
},
"count": {
"value": 931,
"variation": "POSITIVE"
}
}
}
}
]
}
}