Skip to content

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/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} Actual location identifier. Geospatial Area
GeometryID
Circle
*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 day
week
month
{ComparisonLocation} Comparison location identifier. ComparisonGeospatial ComparisonArea
ComparisonGeometryID
ComparisonCircle
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 breakfast
lunch
dinner
guests
compare_guests
Filter offers by number of allowed guests. int 1 2
refundable
compare_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/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
PartitionVariation
Field Description Type
partition Count incidence percentage variation of the group's elements over total elements. Variation
count Total elements variation of the group. 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"
                        }
                    }
                }
            }
        ]
    }
}