Skip to content

▪ Saturation Series Compare

Pricing Tier Licence Type

Saturation Series Compare API returns two, time-based accommodation occupancy data series for the selected POI for two different timeframes at once: one defined by [from,to] query parameters and another auto-calculated for the same duration in the past.
Additional comparative time-based data series between the two timeframes are returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/poi/{poi_id}/rates/saturation/series/compare

Path Parameters

Name                       Description Type Examples
*{billing_plan} Billing plan to be applied to the call. string licence
ondemand
*{account_id} Provided identifier of the account. string
*{poi_id} Identifier of the POI to retrieve data for.
Value obtainable either :
- if {billing_plan}= licence, from $.results[*].resource.id field of List Licences Response Body
- if {billing_plan}= ondemand, from $.results.pois[*].id field of any Search API Response Body.		 string XXeUNbmtYZTsH7UGvNfXWo

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
*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
refundable Filter by offers refundability. boolean
breakfast_included Filter by breakfast inclusion in offers. boolean
lunch_included Filter by lunch inclusion in offers. boolean
dinner_included Filter by dinner inclusion in offers. boolean
ⓝ number_of_guests Filter by allowed number of guests. int
Supported values for period
  • day
  • week
  • month
Example 
curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/HF8xjSQW4W43NGr56denSh/rates/saturation/series/compare?from=2022-05-01&to=2022-05-31&period=week' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

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

Body

ComparedSeriesSaturation

Field Description Type
actual Saturation data for the requested timeframe. ComparableSeriesSaturation
comparison Saturation data for the self-calculated past timeframe. ComparableSeriesSaturation
variation Calculated difference between actual and comparison. SeriesSaturationVariation
ComparableSeriesSaturation
Field Description Type
value Saturation data series for the corresponding timeframe. SeriesSaturation
timeframe Reference date range. Timeframe
SeriesSaturation
Field Description Type
series Saturation Series data for the requested timeframe and period. array[SeriesSaturationElement]
SeriesSaturationElement
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 Saturation data for the corresponding period. Saturation
Saturation
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
Timeframe
Field Description Type
*from Start date of timeframe. date
*to End date of timeframe. date
SeriesSaturationVariation
Field Description Type
series Saturation Series data for the requested timeframe and period. array[SeriesSaturationVariationElement]
SeriesSaturationVariationElement
Field Description Type
*value Saturation variation data between actual_period and previous_period. SaturationVariation
*actual_period Date representing the actual 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
*previous_period Date representing the previous 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
SaturationVariation
Field Description Type Examples
*total_offers Total number of offers. Variation
*available_offers Number of available 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": {
        "value": {
            "series": [
                {
                    "period": "2022-05-02",
                    "value": {
                        "total_offers": 1172,
                        "available_offers": 1172,
                        "saturation": 0.00
                    }
                },
                {
                    "period": "2022-05-09",
                    "value": {
                        "total_offers": 1172,
                        "available_offers": 1172,
                        "saturation": 0.00
                    }
                },
                {
                    "period": "2022-05-16",
                    "value": {
                        "total_offers": 1172,
                        "available_offers": 1172,
                        "saturation": 0.00
                    }
                },
                {
                    "period": "2022-05-23",
                    "value": {
                        "total_offers": 1176,
                        "available_offers": 1166,
                        "saturation": 0.85
                    }
                },
                {
                    "period": "2022-05-30",
                    "value": {
                        "total_offers": 336,
                        "available_offers": 336,
                        "saturation": 0.00
                    }
                }
            ]
        },
        "timeframe": {
            "from": "2022-05-01",
            "to": "2022-05-31"
        }
    },
    "comparison": {
        "value": {
            "series": [
                {
                    "period": "2022-04-04",
                    "value": {
                        "total_offers": 1176,
                        "available_offers": 1176,
                        "saturation": 0.00
                    }
                },
                {
                    "period": "2022-04-11",
                    "value": {
                        "total_offers": 1176,
                        "available_offers": 1170,
                        "saturation": 0.51
                    }
                },
                {
                    "period": "2022-04-18",
                    "value": {
                        "total_offers": 1176,
                        "available_offers": 1176,
                        "saturation": 0.00
                    }
                },
                {
                    "period": "2022-04-25",
                    "value": {
                        "total_offers": 1008,
                        "available_offers": 1008,
                        "saturation": 0.00
                    }
                }
            ]
        },
        "timeframe": {
            "from": "2022-04-01",
            "to": "2022-04-30"
        }
    },
    "variation": {
        "series": [
            {
                "value": {
                    "total_offers": {
                        "value": -4,
                        "variation": "NEGATIVE"
                    },
                    "available_offers": {
                        "value": -4,
                        "variation": "NEGATIVE"
                    },
                    "saturation": {
                        "value": 0.00,
                        "variation": "NEUTRAL"
                    }
                },
                "actual_period": "2022-05-02",
                "previous_period": "2022-04-04"
            },
            {
                "value": {
                    "total_offers": {
                        "value": -4,
                        "variation": "NEGATIVE"
                    },
                    "available_offers": {
                        "value": 2,
                        "variation": "POSITIVE"
                    },
                    "saturation": {
                        "value": -0.51,
                        "variation": "NEGATIVE"
                    }
                },
                "actual_period": "2022-05-09",
                "previous_period": "2022-04-11"
            },
            {
                "value": {
                    "total_offers": {
                        "value": -4,
                        "variation": "NEGATIVE"
                    },
                    "available_offers": {
                        "value": -4,
                        "variation": "NEGATIVE"
                    },
                    "saturation": {
                        "value": 0.00,
                        "variation": "NEUTRAL"
                    }
                },
                "actual_period": "2022-05-16",
                "previous_period": "2022-04-18"
            },
            {
                "value": {
                    "total_offers": {
                        "value": 168,
                        "variation": "POSITIVE"
                    },
                    "available_offers": {
                        "value": 158,
                        "variation": "POSITIVE"
                    },
                    "saturation": {
                        "value": 0.85,
                        "variation": "POSITIVE"
                    }
                },
                "actual_period": "2022-05-23",
                "previous_period": "2022-04-25"
            }
        ]
    }
}