▪ Rate Series Compare
Rate Series Compare API returns two, time-based rate series for the selected POI for two different timeframes at once: one defined by [from,to] query parameters and another auto-calculated for the same duration in the past.
Additional comparative time-based data series between the two timeframes are returned as well.
Request
Endpoint
GET
/v4/{billing_plan}/account/{account_id}/poi/{poi_id}/rates/series/compare
Path Parameters
| Name | Description | Type | Examples |
|---|---|---|---|
| *{billing_plan} | Billing plan to be applied to the call. | string | licence ondemand |
| *{account_id} | Provided identifier of the account. | string | |
| *{poi_id} | Identifier of the POI to retrieve data for. Value obtainable either : - if {billing_plan}= licence, from $.results[*].resource.id field of List Licences Response Body- if {billing_plan}= ondemand, from $.results.pois[*].id field of any Search API Response Body. |
string | XXeUNbmtYZTsH7UGvNfXWo |
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 |
|---|---|---|---|---|
| *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 | |
| refundable | Filter offers that can be refunded. | boolean | ||
| breakfast_included | Filter by breakfast inclusion in offers. | boolean | ||
| lunch_included | Filter by lunch inclusion in offers. | boolean | ||
| dinner_included | Filter by dinner inclusion in offers. | boolean | ||
| ⓝ percentile | Request percentile expressed in the range (0, 1).Median value 0.5 will always be implicitly requested. | decimal | 0.5 | |
| ⓝ number_of_guests | Filter by allowed number of guests. | int |
Supported values for period
- day
- week
- month
Example
curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/HF8xjSQW4W43NGr56denSh/rates/series/compare?from=2022-05-01&to=2022-05-31&period=week' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \
Response
Status
| Status | Description |
|---|---|
| 200 | Rates Series Compare data has been successfully returned. |
Body
ComparedSeriesOverall
| Field | Description | Type |
|---|---|---|
| actual | Overall data for the requested timeframe. | ComparableSeriesRates |
| comparison | Overall data for the self-calculated past timeframe. | ComparableSeriesRates |
| variation | Calculated difference between actual and comparison. |
SeriesRatesVariation |
ComparableSeriesRates
| Field | Description | Type |
|---|---|---|
| value | Rates data series for the corresponding timeframe. |
SeriesRates |
| timeframe | Reference date range. | Timeframe |
SeriesRates
| Field | Description | Type |
|---|---|---|
| series | Rates Series data for the requested timeframe and period. | array[SeriesRatesElement] |
SeriesRatesElement
| 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 | Statistical data about prices expressed in Euros. | Statistics |
Statistics
| Field | Description | Type | Examples |
|---|---|---|---|
| *min | Statistical minimum. | decimal | 49.0 |
| *max | Statistical maximum. | decimal | 209.0 |
| *average | Statistical average. | decimal | 88.44 |
| *percentile | Statistical percentiles. | array[Percentile] | |
| *trend | Ratio between last detected average and previously detected averages for the timeframe.= 100: stable average rate.> 100: growing average rate.< 100: decreasing average rate. |
decimal | 95.8 |
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 |
Timeframe
| Field | Description | Type |
|---|---|---|
| *from | Start date of timeframe. | date |
| *to | End date of timeframe. | date |
SeriesRatesVariation
| Field | Description | Type |
|---|---|---|
| series | Rates Series data for the requested timeframe and period. | array[SeriesRatesVariationElement] |
SeriesRatesVariationElement
| Field | Description | Type |
|---|---|---|
| *value | Variation data expressed in Euros between actual_period and previous_period. |
StatisticsVariation |
| *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 |
| *previous_period | Date representing the previous 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 |
StatisticsVariation
| Field | Description | Type | Examples |
|---|---|---|---|
| *min | Statistical minimum variation. | Variation | |
| *max | Statistical maximum variation. | Variation | |
| *average | Statistical average variation. | Variation | |
| *percentile | Statistical percentiles variation. | array[PercentileVariation] | |
| *trend | Variation of ratio between last detected average and previously detected averages for the timeframe.= 100: stable average rate.> 100: growing average rate.< 100: decreasing average rate. |
Variation |
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 |
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 |
Example
{
"actual": {
"value": {
"series": [
{
"period": "2022-05-02",
"value": {
"min": 49.0,
"max": 209.0,
"average": 86.1,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 95.6
}
},
{
"period": "2022-05-09",
"value": {
"min": 49.0,
"max": 209.0,
"average": 86.1,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 95.6
}
},
{
"period": "2022-05-16",
"value": {
"min": 49.0,
"max": 209.0,
"average": 86.1,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 95.6
}
},
{
"period": "2022-05-23",
"value": {
"min": 49.0,
"max": 211.0,
"average": 88.48,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 95.85
}
},
{
"period": "2022-05-30",
"value": {
"min": 49.0,
"max": 209.0,
"average": 88.44,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 95.8
}
}
]
},
"timeframe": {
"from": "2022-05-01",
"to": "2022-05-31"
}
},
"comparison": {
"value": {
"series": [
{
"period": "2022-04-04",
"value": {
"min": 49.0,
"max": 211.0,
"average": 88.08,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 93.79
}
},
{
"period": "2022-04-11",
"value": {
"min": 49.0,
"max": 209.0,
"average": 87.89,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 94.96
}
},
{
"period": "2022-04-18",
"value": {
"min": 49.0,
"max": 209.0,
"average": 87.89,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 94.96
}
},
{
"period": "2022-04-25",
"value": {
"min": 49.0,
"max": 209.0,
"average": 87.89,
"percentile": [
{
"request": 0.5,
"response": 73.00
}
],
"trend": 94.96
}
}
]
},
"timeframe": {
"from": "2022-04-01",
"to": "2022-04-30"
}
},
"variation": {
"series": [
{
"value": {
"min": {
"value": 0.0,
"variation": "NEUTRAL"
},
"max": {
"value": -2.0,
"variation": "NEGATIVE"
},
"average": {
"value": -1.98,
"variation": "NEGATIVE"
},
"percentile": [
{
"request": 0.5,
"response": {
"value": 0.00,
"variation": "NEUTRAL"
}
}
],
"trend": {
"value": 1.81,
"variation": "POSITIVE"
}
},
"actual_period": "2022-05-02",
"previous_period": "2022-04-04"
},
{
"value": {
"min": {
"value": 0.0,
"variation": "NEUTRAL"
},
"max": {
"value": 0.0,
"variation": "NEUTRAL"
},
"average": {
"value": -1.79,
"variation": "NEGATIVE"
},
"percentile": [
{
"request": 0.5,
"response": {
"value": 0.00,
"variation": "NEUTRAL"
}
}
],
"trend": {
"value": 0.64,
"variation": "POSITIVE"
}
},
"actual_period": "2022-05-09",
"previous_period": "2022-04-11"
},
{
"value": {
"min": {
"value": 0.0,
"variation": "NEUTRAL"
},
"max": {
"value": 0.0,
"variation": "NEUTRAL"
},
"average": {
"value": -1.79,
"variation": "NEGATIVE"
},
"percentile": [
{
"request": 0.5,
"response": {
"value": 0.00,
"variation": "NEUTRAL"
}
}
],
"trend": {
"value": 0.64,
"variation": "POSITIVE"
}
},
"actual_period": "2022-05-16",
"previous_period": "2022-04-18"
},
{
"value": {
"min": {
"value": 0.0,
"variation": "NEUTRAL"
},
"max": {
"value": 2.0,
"variation": "POSITIVE"
},
"average": {
"value": 0.59,
"variation": "POSITIVE"
},
"percentile": [
{
"request": 0.5,
"response": {
"value": 0.00,
"variation": "NEUTRAL"
}
}
],
"trend": {
"value": 0.89,
"variation": "POSITIVE"
}
},
"actual_period": "2022-05-23",
"previous_period": "2022-04-25"
}
]
}
}