Skip to content

▪ Saturation

Rates Saturation API returns accommodation occupancy data for the specified {Viewport} within the specified {Location}.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/maps/rates/saturation/overall/

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}/maps/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
*{Viewport} Viewport identifier. Viewport Viewport
*{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
ⓝ 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 facility
  • breakfast
  • lunch
  • dinner
Example 
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/maps/rates/saturation/overall?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01' \
-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}/maps/rates/sample/saturation/overall?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 Rates Saturation data has been successfully returned.

Body

MapsRatesSaturation

Field Description Type
tiles Map quads rates saturation data for requested {Viewport} and {Location}. array[MapsRatesSaturationElement]
MapsRatesOverallElement
Field Description Type
*saturation Rates saturation data of corresponding quadkey. LocationRatesSaturation
*quadkey Identifier of the map quad. Quadkey
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.
equation		 decimal 34.09
Quadkey
Field Description Type Examples
*tile Map quad identifier in Bing Maps Tile System standard format. string 1202231311
*wkt Map quad expressed in WKT standard format. string POLYGON ((10.8984375 43.83452678223682, 11.25 43.83452678223682, 11.25 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.83452678223682))
Example 
{
    "tiles": [
        {
            "poi": {
                "count": 46,
                "partition": 96.0
            },
            "quadkey": {
                "tile": "12022313113",
                "wkt": "POLYGON ((11.07421875 43.83452678223682, 11.25 43.83452678223682, 11.25 43.96119063892024, 11.07421875 43.96119063892024, 11.07421875 43.83452678223682))"
            },
            "saturation": {
                "total_offers": 100716,
                "available_offers": 88077,
                "saturation": 12.55
            }
        },
        {
            "poi": {
                "count": 1,
                "partition": 2.0
            },
            "quadkey": {
                "tile": "12022313112",
                "wkt": "POLYGON ((10.8984375 43.83452678223682, 11.07421875 43.83452678223682, 11.07421875 43.96119063892024, 10.8984375 43.96119063892024, 10.8984375 43.83452678223682))"
            },
            "saturation": {
                "total_offers": 2652,
                "available_offers": 2652,
                "saturation": 0.0
            }
        },
        {
            "poi": {
                "count": 1,
                "partition": 2.0
            },
            "quadkey": {
                "tile": "12022313131",
                "wkt": "POLYGON ((11.07421875 43.707593504052944, 11.25 43.707593504052944, 11.25 43.83452678223682, 11.07421875 43.83452678223682, 11.07421875 43.707593504052944))"
            },
            "saturation": {
                "total_offers": 560,
                "available_offers": 332,
                "saturation": 40.71
            }
        },
        {
            "poi": {
                "count": 0,
                "partition": 0.0
            },
            "quadkey": {
                "tile": "12022313130",
                "wkt": "POLYGON ((10.8984375 43.707593504052944, 11.07421875 43.707593504052944, 11.07421875 43.83452678223682, 10.8984375 43.83452678223682, 10.8984375 43.707593504052944))"
            },
            "saturation": {
                "total_offers": 0,
                "available_offers": 0,
                "saturation": null
            }
        }
    ]
}