▪ Saturation Compare

Rates Saturation Compare API returns two different rates saturation data sets 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 data between the two data sets is returned as well.

Request

Endpoint

GET/v4/ondemand/account/{account_id}/locations/rates/saturation/overall/compare
GET/v4/licence_id/{licence_id}/territorial/rates/saturation/overall/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
{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.
ⓝ 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 facility

• breakfast
• lunch
• dinner

Example

curl -X GET 'https://api.datappeal.io/v4/licence/{licence_id}/territorial/rates/saturation/overall/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2025-01-01&to=2025-07-01&compare_from=2020-07-01&compare_to=2025-01-01' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

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

Body

LocationRatesComparedSaturation

Field	Description	Type
actual	Rates overall data for the actual timeframe.	LocationRatesComparableSaturation
comparison	Rates overall data for the comparison timeframe.	LocationRatesComparableSaturation
variation	Calculated difference between actual and comparison.	LocationRatesSaturationVariation

LocationRatesComparableSaturation

Field	Description	Type
timeframe	Reference date range.	Timeframe
value	Rates saturation data for the corresponding timeframe.	LocationRatesSaturation

Timeframe

Field	Description	Type
*from	Start date of timeframe.	date
*to	End date of timeframe.	date

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

LocationRatesSaturationVariation

Field	Description	Type
*total_offers	Variation of accommodation offers.	Variation
*available_offers	Variation of available accommodation offers.	Variation
*saturation	Occupancy ratio variation.	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-07-01"
        },
        "value": {
            "total_offers": 3679044,
            "available_offers": 2524739,
            "saturation": 31.38
        }
    },
    "comparison": {
        "timeframe": {
            "from": "2020-07-01",
            "to": "2025-01-01"
        },
        "value": {
            "total_offers": 2219254,
            "available_offers": 1476429,
            "saturation": 33.47
        }
    },
    "variation": {
        "total_offers": {
            "value": 1459790,
            "variation": "POSITIVE"
        },
        "available_offers": {
            "value": 1048310,
            "variation": "POSITIVE"
        },
        "saturation": {
            "value": -2.09,
            "variation": "NEGATIVE"
        }
    }
}