▪ 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/ondemand/account/{account_id}/locations/index/seasonality/series/compare
GET/v4/licence_id/{licence_id}/territorial/index/seasonality/series/compare

Path Parameters

Name	Description	Type	Examples
*{account_id}	Provided identifier of the account.	string
*{licence_id}	Provided identifier of the licence.	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	2025-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/licence/{licence_id}/territorial/index/seasonality/series/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2025-01-01&to=2025-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": "2025-01-01",
            "to": "2025-02-28"
        },
        "value": {
            "series": [
                {
                    "period": "2025-01-01",
                    "value": {
                        "score": 31.21
                    }
                },
                {
                    "period": "2025-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": "2025-01-01",
                "previousPeriod": "2020-11-01",
                "value": {
                    "value": 11.88,
                    "variation": "POSITIVE"
                }
            },
            {
                "actualPeriod": "2025-02-01",
                "previousPeriod": "2020-12-01",
                "value": {
                    "value": -0.51,
                    "variation": "NEGATIVE"
                }
            }
        ]
    }
}