Skip to content

▪ Seasonal Peak Series Compare

Seasonal Peak Series Compare API returns two, time-based index score 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 index score series are returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/index/seasonality/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

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.
ⓝ network
ⓝ compare_network		 Filter by network. string Dictionary
ⓝ 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
ⓝ user_type
ⓝ compare_user_type		 Filter by reviewer type. string Dictionary
ⓝ user_country
ⓝ compare_user_country		 Filter by reviewer's country of origin in ISO 3166-1 alpha-2 standard format (in lower case). string it
de
ⓝ content_language
ⓝ compare_content_language		 Filter by contents language in ISO_639-1 standard format. string en
fr
Supported values for period
  • week
  • month
Example 
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/index/seasonality/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 Seasonal Peak Series Compare data has been successfully returned.

Body

LocationComparedSeriesIndex

Field Description Type
actual Index score series for the actual timeframe. LocationComparableSeriesIndex
comparison Index score series for the comparison timeframe. LocationComparableSeriesIndex
variation Calculated difference between actual and comparison. LocationSeriesIndexVariation
LocationComparableSeriesIndex
Field Description Type
timeframe Reference date range. Timeframe
value Index score series for the corresponding timeframe. LocationSeriesIndex
Timeframe
Field Description Type
*from Start date of timeframe. date
*to End date of timeframe. date
LocationSeriesIndex
Field Description Type
series Index series data for the requested timeframe and period. array[LocationSeriesIndexElement]
LocationSeriesIndexElement
Field Description Type
*period Date representing a specific day, corresponding to the first day of the requested period.
day: the day itself.
week: first day of the corresponding week.
month: first day of the corresponding month.		 date
*value Index score of corresponding period. LocationIndexScore
LocationIndexScore
Field Description Type
score Index score value in the range [0,100]. decimal
LocationSeriesIndexVariation
Field Description Type
series Index score series for the requested timeframe and period. array[LocationSeriesIndexVariationElement]
LocationSeriesIndexVariationElement
Field Description Type
*actual_period Date representing the actual period, corresponding to the first day of the period.
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.
week: first day of the corresponding week.
month: first day of the corresponding month.		 date
*value Index score variation between actual_period and comparison_period. 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": {
        "timeframe": {
            "from": "2021-01-01",
            "to": "2021-02-28"
        },
        "value": {
            "series": [
                {
                    "period": "2021-01-01",
                    "value": {
                        "score": 31.21
                    }
                },
                {
                    "period": "2021-02-01",
                    "value": {
                        "score": 25.75
                    }
                }
            ]
        }
    },
    "comparison": {
        "timeframe": {
            "from": "2020-11-01",
            "to": "2020-12-31"
        },
        "value": {
            "series": [
                {
                    "period": "2020-11-01",
                    "value": {
                        "score": 19.33
                    }
                },
                {
                    "period": "2020-12-01",
                    "value": {
                        "score": 26.26
                    }
                }
            ]
        }
    },
    "variation": {
        "series": [
            {
                "actualPeriod": "2021-01-01",
                "previousPeriod": "2020-11-01",
                "value": {
                    "value": 11.88,
                    "variation": "POSITIVE"
                }
            },
            {
                "actualPeriod": "2021-02-01",
                "previousPeriod": "2020-12-01",
                "value": {
                    "value": -0.51,
                    "variation": "NEGATIVE"
                }
            }
        ]
    }
}