▪ Saturation Grouped Compare
Rates Saturation Grouped Compare API returns two, time-based rates saturation grouped data sets along with a comparative calculation.
Request
Endpoint
GET
/v4/{billing_plan}/account/{account_id}/locations/rates/saturation/overall/grouped/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}/locations/rates/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 |
|---|---|---|---|---|
| *{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 | |
| *group_type | Field for which perform grouping. | string | poi_industrypoi_categorypoi_class | |
| {ComparisonLocation} | Comparison location identifier. | Comparison |
ComparisonAreaComparisonGeometryIDComparisonCircle | 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 | 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 (only when group_type is not equal to guests) |
| 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 (only when group_type is not equal to scan_last_day) |
| page | Requested page number for paginated results. | int | 1 | |
| page_size | Requested page size for paginated results in the range [1, 100]. | int | 25 |
Supported values for group_type
- poi_industry
- poi_category
- poi_class
- guests
- scan_last_day
Supported values for facility
- breakfast
- lunch
- dinner
Example
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/rates/saturation/overall/grouped/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-01-01&group_type=poi_class' \
-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}/locations/rates/sample/saturation/overall/grouped/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-01-01&group_type=poi_class' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \
Response
Status
| Status | Description |
|---|---|
| 200 | Rates Saturation Grouped Compare data has been successfully returned. |
Body
LocationRatesGroupedComparedSaturation
| Field | Description | Type |
|---|---|---|
| *results | Paginated grouped compared overall data. | LocationGroupedComparedSaturationResults |
| paging | Response pagination. | Paging |
LocationRatesGroupedComparedSaturationResults
| Field | Description | Type |
|---|---|---|
| actual | Rates saturation grouped data for the actual timeframe. | LocationRatesGroupedComparableSaturation |
| comparison | Rates saturation grouped data for the comparison timeframe. | LocationRatesGroupedComparableSaturation |
| variation | Calculated difference between actual and comparison. |
array[LocationRatesGroupedSaturationVariation] |
LocationRatesGroupedComparableSaturation
| Field | Description | Type |
|---|---|---|
| timeframe | Reference date range. | Timeframe |
| value | Rates saturation grouped data for the corresponding timeframe. |
array[LocationRatesGroupedSaturationElement] |
Timeframe
| Field | Description | Type |
|---|---|---|
| *from | Start date of timeframe. | date |
| *to | End date of timeframe. | date |
LocationRatesGroupedSaturationElement
| Field | Description | Type | Examples |
|---|---|---|---|
| *group | Field value within the requested grouping by field. | string | |
| *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 |
LocationRatesGroupedSaturationVariation
| Field | Description | Type |
|---|---|---|
| *group | Field value within the requested grouping by field. | string |
| *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 |
Paging
| Field | Description | Type |
|---|---|---|
| last | A relative URI to the last page. | string |
| first | A relative URI to the first page. | string |
| prev | A relative URI to the previous page. | string |
| next | A relative URI to the next page. | string |
| current | A relative URI to the current page. | string |
| pages | A set of relative URIs calculated around the current page. | Page |
| elements | All indexes shown on the current page. | array[int] |
| total | The number of all elements that API can retrieve. | int |
| size | The selected page size. | int |
Page
| Field | Description | Type |
|---|---|---|
| number | Number of the page. | int |
| uri | URI of the page. | string |
Example
{
"results": {
"actual": {
"timeframe": {
"from": "2021-01-01",
"to": "2021-07-01"
},
"value": [
{
"group": "1",
"total_offers": 26910,
"available_offers": 23777,
"saturation": 11.64
},
{
"group": "2",
"total_offers": 105704,
"available_offers": 82501,
"saturation": 21.95
},
{
"group": "3",
"total_offers": 535204,
"available_offers": 403615,
"saturation": 24.59
},
{
"group": "4",
"total_offers": 1471946,
"available_offers": 957075,
"saturation": 34.98
},
{
"group": "5",
"total_offers": 406217,
"available_offers": 222759,
"saturation": 45.16
}
]
},
"comparison": {
"timeframe": {
"from": "2020-07-01",
"to": "2021-01-01"
},
"value": [
{
"group": "1",
"total_offers": 27309,
"available_offers": 25648,
"saturation": 6.08
},
{
"group": "2",
"total_offers": 69394,
"available_offers": 61374,
"saturation": 11.56
},
{
"group": "3",
"total_offers": 316426,
"available_offers": 261991,
"saturation": 17.2
},
{
"group": "4",
"total_offers": 1123747,
"available_offers": 688072,
"saturation": 38.77
},
{
"group": "5",
"total_offers": 274853,
"available_offers": 152132,
"saturation": 44.65
}
]
},
"variation": [
{
"group": "1",
"total_offers": {
"value": -399,
"variation": "NEGATIVE"
},
"available_offers": {
"value": -1871,
"variation": "NEGATIVE"
},
"saturation": {
"value": 5.5600000000000005,
"variation": "POSITIVE"
}
},
{
"group": "2",
"total_offers": {
"value": 36310,
"variation": "POSITIVE"
},
"available_offers": {
"value": 21127,
"variation": "POSITIVE"
},
"saturation": {
"value": 10.389999999999999,
"variation": "POSITIVE"
}
},
{
"group": "3",
"total_offers": {
"value": 218778,
"variation": "POSITIVE"
},
"available_offers": {
"value": 141624,
"variation": "POSITIVE"
},
"saturation": {
"value": 7.390000000000001,
"variation": "POSITIVE"
}
},
{
"group": "4",
"total_offers": {
"value": 348199,
"variation": "POSITIVE"
},
"available_offers": {
"value": 269003,
"variation": "POSITIVE"
},
"saturation": {
"value": -3.7900000000000063,
"variation": "NEGATIVE"
}
},
{
"group": "5",
"total_offers": {
"value": 131364,
"variation": "POSITIVE"
},
"available_offers": {
"value": 70627,
"variation": "POSITIVE"
},
"saturation": {
"value": 0.509999999999998,
"variation": "POSITIVE"
}
}
]
},
"paging": {
"last": "/rates/saturation/overall/grouped/compare?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-07-01&from=2021-01-01&group_type=poi_class&to=2021-07-01&compare_to=2021-01-01",
"first": "/rates/saturation/overall/grouped/compare?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-07-01&from=2021-01-01&group_type=poi_class&to=2021-07-01&compare_to=2021-01-01",
"prev": null,
"next": null,
"current": "/rates/saturation/overall/grouped/compare?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-07-01&from=2021-01-01&group_type=poi_class&to=2021-07-01&compare_to=2021-01-01",
"pages": [
{
"number": 1,
"uri": "/rates/saturation/overall/grouped/compare?page=1&page_size=25&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-07-01&from=2021-01-01&group_type=poi_class&to=2021-07-01&compare_to=2021-01-01"
}
],
"total": 5,
"size": 25,
"elements": [
1,
2,
3,
4,
5
]
}
}