▪ Saturation Compare
Rates Saturation Compare API returns two different rates saturation data sets at once for a specified {Viewport} and {Location}: one defined by the specified [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/{billing_plan}/account/{account_id}/maps/rates/saturation/overall/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 | |
/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} | Actual location identifier. | Geospatial | AreaGeometryIDCircle | |
| *from | Start date of actual timeframe. | date | 2020-01-01 | |
| *to | End date of actual timeframe. | date | 2020-12-31 | |
| 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. |
| ⓝ 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 | breakfastlunchdinner | |
| guestscompare_guests | Filter offers by number of allowed guests. | int | 1 | 2 |
| refundablecompare_refundable | Filter offers that can be refunded. | boolean | truefalse | |
| 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/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-01-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/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-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
MapsRatesComparedSaturation
| Field | Description | Type |
|---|---|---|
| actual | Rates saturation data for the actual timeframe. | MapsRatesComparableSaturation |
| comparison | Rates saturation data for the comparison timeframe. | MapsRatesComparableSaturation |
| variation | Calculated difference between actual and comparison. |
array[MapsRatesSaturationVariation] |
MapsRatesComparableSaturation
| Field | Description | Type |
|---|---|---|
| timeframe | Reference date range. | Timeframe |
| value | Rates saturation map quads data for the corresponding timeframe. |
array[MapsRatesSaturationElement] |
Timeframe
| Field | Description | Type |
|---|---|---|
| *from | Start date of timeframe. | date |
| *to | End date of timeframe. | date |
MapsRatesSaturationElement
| 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. |
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)) |
MapsRatesSaturationVariation
| Field | Description | Type |
|---|---|---|
| *compare | Rates saturation variation data of corresponding quadkey. |
LocationRatesSaturationVariation |
| *quadkey | Identifier of the map quad. | Quadkey |
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 |
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
{
"actual": {
"timeframe": {
"from": "2022-07-01",
"to": "2023-07-01"
},
"value": [
{
"poi": {
"count": 49,
"partition": 60.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": 102018,
"available_offers": 88591,
"saturation": 13.16
}
},
{
"poi": {
"count": 24,
"partition": 28.999999999999996
},
"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": 64356,
"available_offers": 49898,
"saturation": 22.47
}
},
{
"poi": {
"count": 2,
"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": 3176,
"available_offers": 3017,
"saturation": 5.01
}
},
{
"poi": {
"count": 6,
"partition": 7.000000000000001
},
"quadkey": {
"tile": "12022313111",
"wkt": "POLYGON ((11.07421875 43.96119063892024, 11.25 43.96119063892024, 11.25 44.087585028245165, 11.07421875 44.087585028245165, 11.07421875 43.96119063892024))"
},
"saturation": {
"total_offers": 2701,
"available_offers": 2068,
"saturation": 23.44
}
},
{
"poi": {
"count": 1,
"partition": 1.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": "12022311333",
"wkt": "POLYGON ((11.07421875 44.087585028245165, 11.25 44.087585028245165, 11.25 44.21370990970204, 11.07421875 44.21370990970204, 11.07421875 44.087585028245165))"
},
"saturation": {
"total_offers": 0,
"available_offers": 0,
"saturation": null
}
},
{
"poi": {
"count": 0,
"partition": 0.0
},
"quadkey": {
"tile": "12022313110",
"wkt": "POLYGON ((10.8984375 43.96119063892024, 11.07421875 43.96119063892024, 11.07421875 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.96119063892024))"
},
"saturation": {
"total_offers": 0,
"available_offers": 0,
"saturation": null
}
},
{
"poi": {
"count": 0,
"partition": 0.0
},
"quadkey": {
"tile": "12022311332",
"wkt": "POLYGON ((10.8984375 44.087585028245165, 11.07421875 44.087585028245165, 11.07421875 44.21370990970204, 10.8984375 44.21370990970204, 10.8984375 44.087585028245165))"
},
"saturation": {
"total_offers": 0,
"available_offers": 0,
"saturation": null
}
}
]
},
"comparison": {
"timeframe": {
"from": "2021-07-01",
"to": "2022-07-01"
},
"value": [
{
"poi": {
"count": 51,
"partition": 61.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": 125453,
"available_offers": 93826,
"saturation": 25.21
}
},
{
"poi": {
"count": 22,
"partition": 26.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": 56177,
"available_offers": 38093,
"saturation": 32.19
}
},
{
"poi": {
"count": 3,
"partition": 4.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": 9431,
"available_offers": 7163,
"saturation": 24.05
}
},
{
"poi": {
"count": 6,
"partition": 7.000000000000001
},
"quadkey": {
"tile": "12022313111",
"wkt": "POLYGON ((11.07421875 43.96119063892024, 11.25 43.96119063892024, 11.25 44.087585028245165, 11.07421875 44.087585028245165, 11.07421875 43.96119063892024))"
},
"saturation": {
"total_offers": 3809,
"available_offers": 2623,
"saturation": 31.14
}
},
{
"poi": {
"count": 1,
"partition": 1.0
},
"quadkey": {
"tile": "12022311333",
"wkt": "POLYGON ((11.07421875 44.087585028245165, 11.25 44.087585028245165, 11.25 44.21370990970204, 11.07421875 44.21370990970204, 11.07421875 44.087585028245165))"
},
"saturation": {
"total_offers": 74,
"available_offers": 54,
"saturation": 27.03
}
},
{
"poi": {
"count": 1,
"partition": 1.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": 8,
"available_offers": 8,
"saturation": 0.0
}
},
{
"poi": {
"count": 0,
"partition": 0.0
},
"quadkey": {
"tile": "12022313110",
"wkt": "POLYGON ((10.8984375 43.96119063892024, 11.07421875 43.96119063892024, 11.07421875 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.96119063892024))"
},
"saturation": {
"total_offers": 0,
"available_offers": 0,
"saturation": null
}
},
{
"poi": {
"count": 0,
"partition": 0.0
},
"quadkey": {
"tile": "12022311332",
"wkt": "POLYGON ((10.8984375 44.087585028245165, 11.07421875 44.087585028245165, 11.07421875 44.21370990970204, 10.8984375 44.21370990970204, 10.8984375 44.087585028245165))"
},
"saturation": {
"total_offers": 0,
"available_offers": 0,
"saturation": null
}
}
]
},
"variation": [
{
"saturation": {
"total_offers": {
"value": -23435,
"variation": "NEGATIVE"
},
"available_offers": {
"value": -5235,
"variation": "NEGATIVE"
},
"saturation": {
"value": -12.05,
"variation": "NEGATIVE"
}
},
"poi": {
"partition": {
"value": -1.0,
"variation": "NEGATIVE"
},
"count": {
"value": -2,
"variation": "NEGATIVE"
}
},
"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": {
"value": 8179,
"variation": "POSITIVE"
},
"available_offers": {
"value": 11805,
"variation": "POSITIVE"
},
"saturation": {
"value": -9.72,
"variation": "NEGATIVE"
}
},
"poi": {
"partition": {
"value": 3.0,
"variation": "POSITIVE"
},
"count": {
"value": 2,
"variation": "POSITIVE"
}
},
"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": {
"value": -6255,
"variation": "NEGATIVE"
},
"available_offers": {
"value": -4146,
"variation": "NEGATIVE"
},
"saturation": {
"value": -19.04,
"variation": "NEGATIVE"
}
},
"poi": {
"partition": {
"value": -2.0,
"variation": "NEGATIVE"
},
"count": {
"value": -1,
"variation": "NEGATIVE"
}
},
"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": {
"value": -1108,
"variation": "NEGATIVE"
},
"available_offers": {
"value": -555,
"variation": "NEGATIVE"
},
"saturation": {
"value": -7.7,
"variation": "NEGATIVE"
}
},
"poi": {
"partition": {
"value": 0.0,
"variation": "NEUTRAL"
},
"count": {
"value": 0,
"variation": "NEUTRAL"
}
},
"quadkey": {
"tile": "12022313111",
"wkt": "POLYGON ((11.07421875 43.96119063892024, 11.25 43.96119063892024, 11.25 44.087585028245165, 11.07421875 44.087585028245165, 11.07421875 43.96119063892024))"
}
},
{
"saturation": {
"total_offers": {
"value": 552,
"variation": "POSITIVE"
},
"available_offers": {
"value": 324,
"variation": "POSITIVE"
},
"saturation": {
"value": 40.71,
"variation": "POSITIVE"
}
},
"poi": {
"partition": {
"value": 0.0,
"variation": "NEUTRAL"
},
"count": {
"value": 0,
"variation": "NEUTRAL"
}
},
"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": {
"value": -74,
"variation": "NEGATIVE"
},
"available_offers": {
"value": -54,
"variation": "NEGATIVE"
},
"saturation": {
"value": null,
"variation": null
}
},
"poi": {
"partition": {
"value": -1.0,
"variation": "NEGATIVE"
},
"count": {
"value": -1,
"variation": "NEGATIVE"
}
},
"quadkey": {
"tile": "12022311333",
"wkt": "POLYGON ((11.07421875 44.087585028245165, 11.25 44.087585028245165, 11.25 44.21370990970204, 11.07421875 44.21370990970204, 11.07421875 44.087585028245165))"
}
},
{
"saturation": {
"total_offers": {
"value": 0,
"variation": "NEUTRAL"
},
"available_offers": {
"value": 0,
"variation": "NEUTRAL"
},
"saturation": {
"value": null,
"variation": null
}
},
"poi": {
"partition": {
"value": 0.0,
"variation": "NEUTRAL"
},
"count": {
"value": 0,
"variation": "NEUTRAL"
}
},
"quadkey": {
"tile": "12022313110",
"wkt": "POLYGON ((10.8984375 43.96119063892024, 11.07421875 43.96119063892024, 11.07421875 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.96119063892024))"
}
},
{
"saturation": {
"total_offers": {
"value": 0,
"variation": "NEUTRAL"
},
"available_offers": {
"value": 0,
"variation": "NEUTRAL"
},
"saturation": {
"value": null,
"variation": null
}
},
"poi": {
"partition": {
"value": 0.0,
"variation": "NEUTRAL"
},
"count": {
"value": 0,
"variation": "NEUTRAL"
}
},
"quadkey": {
"tile": "12022311332",
"wkt": "POLYGON ((10.8984375 44.087585028245165, 11.07421875 44.087585028245165, 11.07421875 44.21370990970204, 10.8984375 44.21370990970204, 10.8984375 44.087585028245165))"
}
}
]
}