▪ Saturation Series

Rates Saturation Series API returns a time-based rate saturation data series for the specified {Location}, grouped by a time period.

Request

Endpoint

GET/v4/ondemand/account/{account_id}/locations/rates/saturation/overall/series
GET/v4/licence/{licence_id}/territorial/rates/saturation/overall/series

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}	Location identifier.	Geospatial	Area GeometryID Circle
*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	day week month
ⓝ poi_class	Filter POIs with "category": "hotel" by stars rating in the range [1,5].	int	4
ⓝ poi_industry	Filter by POI Industry.	string	Dictionary
ⓝ poi_category	Filter by POI Category.	string	Dictionary
ⓝ facility	Filter offers by included facility.	string	breakfast lunch dinner
guests	Filter offers by number of allowed guests.	int	1	2
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/licence/{licence_id}/territorial/rates/saturation/overall/series?geometry_id=379c730942e570d586a5520770c0a65d&from=2025-01-01&to=2025-02-28&period=month' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Rates Saturation Series data has been successfully returned.

Body

LocationRatesSeriesSaturation

Field	Description	Type
series	Rates saturation data series for the requested timeframe and period.	array[LocationRatesSeriesSaturationElement]

LocationRatesSeriesSaturationElement

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 saturation data of corresponding period.	LocationRatesSaturation

LocationRatesSaturation

Field	Description	Type	Examples
*total_offers	Total number of accommodation offers.	int	1106
*available_offers	Number of available accommodation offers.	int	729
*saturation	Occupancy ratio in the range [0,100] calculated by the following formula.	decimal	34.09

Example

{
    "series": [
        {
            "period": "2025-01-01",
            "value": {
                "total_offers": 339729,
                "available_offers": 227484,
                "saturation": 33.04
            }
        },
        {
            "period": "2025-02-01",
            "value": {
                "total_offers": 383273,
                "available_offers": 248195,
                "saturation": 35.24
            }
        }
    ]
}