Use on-demand API calls to prevent system overload
We request Connectivity partners (providers) to enable their properties to retrieve Market Insights data only on demand. Prefetching and caching Market insights data for all properties is discouraged as it places significant load on our internal systems. Thank you for your cooperation.
Use this topic to implement the various endpoints in the Market insights API. By implementing Market insights API, you can:
- Retrieve booking window information
- Retrieve booker's data
- Retrieve revenue forecasting data
- Retrieve sales statistics data
Accessing performance insights needs additional permission
To access the performance data of a property, properties must grant the "Performance data and insights" permission while requesting a new connection via the Extranet.
For existing connections: Providers with individual property accounts can use the Quick connect interface in the Provider portal to request for an additional permission Performance data and insights from the connected partner.
For providers with group accounts: Adding permissions for existing connections is currently not supported.
GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/area_demand_dataThe area_demand_data endpoint enables you to retrieve demand data for the target property's region.
Use this path parameter to specify the property.
| Element | Description | Type | Required/Optional | Notes |
|---|---|---|---|---|
propertyId | Specifies the ID of the property for which you want to retrieve demand data. | integer | required | Path parameter |
The following is a successful response body example:
{
"errors": [],
"warnings": [],
"data": {
"report_area": "Paris",
"report_date": "2021-02-06",
"demand_data": [
{
"stats": [
{
"title": "0-1 day",
"key": "bookwindow_0_1",
"formatted_score": "23.32%"
},
{
"title": "2-7 days",
"key": "bookwindow_2_7",
"formatted_score": "19.13%"
},
{
"formatted_score": "20.86%",
"key": "bookwindow_8_30",
"title": "8-30 days"
},
{
"title": "31-90 days",
"key": "bookwindow_31_90",
"formatted_score": "8.88%"
},
{
"key": "bookwindow_91",
"formatted_score": "16.74%",
"title": "90+ days"
},
{
"title": "No dates",
"key": "bookwindow_unknown",
"formatted_score": "11.07%"
}
],
"category_name": "book_window",
"category_summary": "Most searches were looking for 0-1 day in the future",
"title": "Book window"
},
{
"stats": [
{
"formatted_score": "72.11%",
"key": "traveller_couple",
"title": "Couple"
},
{
"title": "Solo traveller",
"key": "traveller_solo",
"formatted_score": "14.38%"
},
{
"title": "Family",
"formatted_score": "7.44%",
"key": "traveller_family"
},
{
"title": "Group",
"formatted_score": "6.07%",
"key": "traveller_group"
}
],
"category_summary": "Most searches were from couples",
"category_name": "traveller_type",
"title": "Traveller type"
},
{
"category_summary": "Most searches were made by domestic travellers",
"stats": [
{
"formatted_score": "57.00%",
"key": "origin_domestic",
"title": "Domestic"
},
{
"title": "International",
"key": "origin_international",
"formatted_score": "43.00%"
}
],
"category_name": "origin",
"title": "Domestic and international travellers"
},
{
"stats": [
{
"title": "Mobile",
"key": "device_mobile",
"formatted_score": "75.17%"
},
{
"title": "Desktop",
"formatted_score": "24.83%",
"key": "device_web"
},
{
"key": "device_other",
"formatted_score": "0.00%",
"title": "Unidentified"
}
],
"category_summary": "Most searches were mobile searches",
"category_name": "device",
"title": "Device"
},
{
"title": "Top 5 countries",
"stats": [
{
"title": "France",
"formatted_score": "57.00%",
"key": "fr"
},
{
"title": "United States",
"formatted_score": "5.58%",
"key": "us"
},
{
"title": "Germany",
"formatted_score": "3.29%",
"key": "de" },
{
"title": "United Kingdom",
"formatted_score": "3.24%",
"key": "gb" },
{
"formatted_score": "3.11%",
"key": "it",
"title": "Italy"
}
],
"category_name": "rank",
"category_summary": "Most searches were from France"
},
{
"category_name": "policy",
"stats": [
{
"formatted_score": "60.29%",
"key": "policy_flexible",
"title": "Free cancellation"
},
{
"formatted_score": "35.65%",
"key": "policy_non_refundable",
"title": "Non-refundable"
},
{
"formatted_score": "4.06%",
"key": "policy_flexible_cost_to_cancel",
"title": "Partially refundable"
}
],
"category_summary": "Most guests staying in Paris made free cancellation bookings",
"title": "Cancellation policy"
},
{
"category_summary": "Most searches were looking for a stay of 3-7 nights",
"category_name": "length_of_stay",
"title": "Length of stay",
"stats": [
{
"key": "3_7_days",
"title": "3-7 nights",
"formatted_score": "67.38%"
},
{
"key": "8_14_days",
"title": "8-14 nights",
"formatted_score": "14.56%"
},
{
"key": "1_day",
"title": "1 night",
"formatted_score": "10.43%"
},
{
"key": "2_days",
"title": "2 nights",
"formatted_score": "5.34%"
},
{
"key": "15_plus_days",
"title": "15+ nights",
"formatted_score": "2.29%"
}
]
}
]
},
"meta": {
"ruid": "UmFuZG9tSVYkc2RlIyh9YWK4dAYm/RbIozfcP2hSPnPAOqhtG+bpYhV/L/tGC7zZG+dij2j4C7a/uJKLKBFjwdaMOm4Zg7OruP7iaM8+h9OG6uhGHIy7zg=="
}
}
The following table describes the response elements:
| Element | Description | Type | Notes |
|---|---|---|---|
data | Contains the response object. | object | |
> report_area | Specifies the property's region to which the demand data applies. | string | |
> report_date | Specifies the date on which the demand data is generated. | string | |
> demand_data | Contains the demand data objects. | array | |
>> category_name | Specifies the category of the demand data. | string | Possible values are: book_window, device, origin, policy, rank, traveller_type, and length_of_stay. The API omits a category when no data is available for it. |
>> category_summary | Specifies the key insight from the demand data in the category it belongs to. | string | |
>> stats | Contains details of metrics for each category. | array | |
>>> key | Specifies a data point within a specific category. | string | |
>>> formatted_score | Specifies the percentage of the data point. | string | |
>>> title | Specifies a human readable version of the data point. | string | |
>> title | Specifies a human readable version of the category name. | string |
For more information on how to handle error responses, see the Troubleshooting section.
GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/book_window_dataThe book_window_data endpoint enables you to retrieve booking window information for the target property's region based on historical data. The API uses the reservations based on date of booking minus cancellations.
You can see insights:
- Filtered by date range. For example, for the last 365 days, last 90 days and so on.
- Compared to last year, a Booking.com-defined competitive set, a peer group, market value or none. For more information, see analysing the metrics impact.
The following path and query parameters are available:
| Element | Description | Type | Required/Optional | Location | Notes |
|---|---|---|---|---|---|
propertyId | Specifies the ID of the property for which you want to retrieve insight values. | integer | required | Path parameter | |
date_range | Specifies the date range within which you want to see the insight values. | enumerated string | required | Query parameter | Possible values: - LAST_365_DAYS - LAST_90_DAYS - LAST_60_DAYS - LAST_30_DAYS - LAST_14_DAYS - LAST_7_DAYS |
compare_with | Specifies the condition to compare the insights with. | enumerated string | optional | Query parameter | If omitted, defaults to NONE. Possible values: - NONE - LAST_YEAR: The API compares the report with the same period one year earlier. - COMPETITIVE_SET: Includes properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of a group of similar properties in a property's area. You can use the peer group to see how a specific property is doing compared to similar properties. The properties in the peer group are chosen by Booking.com based on similarities in conversion, cancellations, property type, and other factors. - MARKET: All properties in the target property's region. |
The following is a successful response body example:
{
"data": {
"book_window": [
{
"value": "0-1 days",
"percent": 1.3333333333333335,
"percent_comparison_set": 0.0,
"report": {
"adr": {
"value": 128.8,
"comparison_set": 101.10764705882352,
"percent_change": 27.3889797129443
}
}
},
{
"value": "2-3 days",
"percent": 0.0,
"percent_comparison_set": 0.0,
"report": {}
},
{
"value": "90+ days",
"percent": 53.333333333333336,
"percent_comparison_set": 0.0,
"report": {
"adr": {
"value": 135.05846153846153,
"comparison_set": 158.22608870967744,
"percent_change": -14.64210318294933
}
}
},
{
"value": "61-90 days",
"percent": 10.666666666666668,
"percent_comparison_set": 0.0,
"report": {
"adr": {
"value": 95.75047619047619,
"comparison_set": 147.8230769230769,
"percent_change": -35.2263001261284
}
}
},
{
"value": "31-60 days",
"percent": 17.333333333333336,
"percent_comparison_set": 0.0,
"report": {
"adr": {
"value": 149.8385714285714,
"comparison_set": 152.38607142857146,
"percent_change": -1.671740714960384
}
}
},
{
"value": "8-14 days",
"percent": 5.333333333333334,
"percent_comparison_set": 0.0,
"report": {
"adr": {
"value": 119.17428571428572,
"comparison_set": 113.22576923076925,
"percent_change": 5.25367725379953
}
}
},
{
"value": "15-30 days",
"percent": 8.0,
"percent_comparison_set": 0.0,
"report": {
"adr": {
"value": 102.72133333333333,
"comparison_set": 125.55599999999998,
"percent_change": -18.186838276678653
}
}
},
{
"value": "4-7 days",
"percent": 4.0,
"percent_comparison_set": 0.0,
"report": {
"adr": {
"value": 71.3,
"comparison_set": 116.91105263157894,
"percent_change": -39.01346502739374
}
}
}
],
"total_booked_rooms": 113.0
},
"warnings": [],
"errors": [],
"meta": {
"ruid": "Um123G9tSVYkc2RlIyh9YQzdwh+280lx897rDZF1JIZYdbF3XplmMYPN87IIbYDpF4gg5ppLWSo9FTHqy5069iHVvB2blrvu"
}
}
The following table describes the response elements:
| Element | Description | Type | Notes |
|---|---|---|---|
data | Contains the response object. | object | |
> book_window | Contains the insight values by different booking windows. | array | |
>> value | Specifies the booking window bucket. | string | |
>> percent | Specifies the percentage of all reservations that fall into the booking window bucket. | float | |
>> percent_comparison_set | If the request contains a compare_with filter, then the API returns a percent change in comparison to the value specified in the compare_with filter. | float or string | When the comparison total is zero, the API returns the string "NaN" instead of a number. |
>> report | Contains the various insights. | object | |
>>> adr | Contains the average daily rate value. | object | |
>>>> value | Specifies the average rate charged per room per night. It is calculated as the total revenue divided by room nights sold. | float | |
>>>> comparison_set | If compare_with is specified in the request, then this specifies the average rate charged per room per night based on the given input for comparison. | float | |
>>>> percent_change | Specifies the percent change comparing the two values provided based on the compare_with value. | float |
For more information on how to handle error responses, see the Troubleshooting section.
GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/booker_insights_dataThe booker_insights_data endpoint enables you to understand which countries your guests are booking from. The API uses the reservations based on date of booking minus cancellations.
You can see insights:
- Filtered by date range. For example, for the last 365 days, last 90 days and so on.
- Compared to last year, a Booking.com-defined competitive set, a peer group, market value or none. For more information, see analysing the metrics impact.
The following path and query parameters are available:
| Element | Description | Type | Required/Optional | Location | Notes |
|---|---|---|---|---|---|
propertyId | Specifies the ID of the property for which you want to retrieve insight values. | integer | required | Path parameter | |
date_range | Specifies the date range within which you want to see the insight values. | enumerated string | required | Query parameter | Possible values: - LAST_365_DAYS - LAST_90_DAYS - LAST_60_DAYS - LAST_30_DAYS - LAST_14_DAYS - LAST_7_DAYS |
compare_with | Specifies the condition to compare the insights with. | enumerated string | optional | Query parameter | If omitted, defaults to NONE. Possible values: - NONE - LAST_YEAR: The API compares the report with the same period one year earlier. - COMPETITIVE_SET: Includes properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of a group of similar properties in a property's area. You can use the peer group to see how a specific property is doing compared to similar properties. The properties in the peer group are chosen by Booking.com based on similarities in conversion, cancellations, property type, and other factors. - MARKET: All properties in the target property's region. |
The following is a successful response body example:
{
"data": {
"country": [
{
"value": "de",
"percent": 67.15007332572918,
"percent_comparison_set": "NaN"
},
{
"value": "nl",
"percent": 19.912009124979633,
"percent_comparison_set": "NaN"
},
{
"value": "be",
"percent": 10.624083428385205,
"percent_comparison_set": "NaN"
},
{
"value": "gb",
"percent": 0.6354896529248819,
"percent_comparison_set": "NaN"
},
{
"value": "lu",
"percent": 0.5214274075281082,
"percent_comparison_set": "NaN"
},
{
"value": "other",
"percent": 1.1569170604529901,
"percent_comparison_set": "NaN"
}
],
"total_booked_rooms": 2870.0
},
"warnings": [],
"errors": [],
"meta": {
"ruid": "Um123G9tSVYkc2RlIyh9YQzdwh+280lx897rDZF1JIZYdbF3XplmMYPN87IIbYDpF4gg5ppLWSo9FTHqy5069iHVvB2blrvu"
}
}The following table describes the response elements:
| Element | Description | Type | Notes |
|---|---|---|---|
data | Contains the response object. | object | |
> country | Contains the insight values by countries. | array | |
>> value | Specifies the country. | string | |
>> percent | Specifies the percentage of all reservations that were made in properties in the specified country. | float | |
>> percent_comparison_set | If the request contains a compare_with filter, then the API returns a percent change in comparison to the value specified in the compare_with filter. | float or string | When the comparison total is zero, the API returns the string "NaN" instead of a number. |
For more information on how to handle error responses, see the Troubleshooting section.
GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/pace_report_dataUse the pace_report_data endpoint to keep track of your future reservations, and compare your performance to previous years. You can also check how the property compares with their peer group, competitive set or the market in general.
The API uses the bookings where the stay date is in the future and not yet cancelled.
You can see insights:
- Filtered by date range. For example, for the last 365 days, last 90 days and so on.
- Compared to last year, a Booking.com-defined competitive set, a peer group, market value or none. For more information, see analysing the metrics impact.
- View by date, week, month or none (aggregates by total).
The following path and query parameters are available:
| Element | Description | Type | Required/Optional | Location | Notes |
|---|---|---|---|---|---|
propertyId | Specifies the ID of the property for which you want to retrieve insight values. | integer | required | Path parameter | |
date_range | Specifies the date range within which you want to see the insight values. | enumerated string | required | Query parameter | Possible values: - LAST_365_DAYS - LAST_90_DAYS - LAST_60_DAYS - LAST_30_DAYS - LAST_14_DAYS - LAST_7_DAYS |
compare_with | Specifies the condition to compare the insights with. | enumerated string | optional | Query parameter | If omitted, defaults to NONE. Possible values: - NONE - LAST_YEAR: The API compares the report with the same period one year earlier. - COMPETITIVE_SET: Includes properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of a group of similar properties in a property's area. You can use the peer group to see how a specific property is doing compared to similar properties. The properties in the peer group are chosen by Booking.com based on similarities in conversion, cancellations, property type, and other factors. - MARKET: All properties in the target property's region. |
|view_by| Specifies the sorting order to view the insights. | string | optional | Query parameter | If omitted, defaults to NONE. Supports the following options:
- NONE: Aggregates by total
- DATE
- WEEK
- MONTH |
The following is a successful response body example:
{
"data": {
"report": {
"adr": {
"value": 152.92956521738412
},
"room_nights": {
"value": 138.0
},
"revenue": {
"value": 21104.27999999901
}
}
},
"warnings": [],
"errors": [],
"meta": {
"ruid": "Um123G9tSVYkc2RlIyh9YQzdwh+280lx897rDZF1JIZYdbF3XplmMYPN87IIbYDpF4gg5ppLWSo9FTHqy5069iHVvB2blrvu"
}
}
The following table describes the response elements:
| Element | Description | Type | Notes |
|---|---|---|---|
data | Contains the response object. | object | |
> report | Contains the report details | object | |
>> adr | Contains the average daily rate value. | object | |
>>> value | Specifies the average rate charged per room per night, calculated as the total revenue divided by room nights sold. | float | |
>> room_nights | Contains the room nights value. | object | |
>>> value | Specifies the number of room nights stayed. | float | |
>> revenue | Contains the revenue value. | object | |
>>> value | Specifies the total amount of revenue earned in a certain time period, minus cancellations. | float |
For more information on how to handle error responses, see the Troubleshooting section.
GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/sales_statistics_report_dataUse the sales_statistics_report_data endpoint to view the reservations from guests who have booked or stayed at the property, and compare it to the previous year. You can compare the past performance with the property’s peer group, competitive set or the market in general. You can also specify which bookings to take into consideration.
You can see insights:
- Filtered by date range.
- Based on reservations:
- Book date gross: Takes all reservations based on the date of the booking (rather than the stay), even if cancelled.
- Book date net: Takes all reservations based on the date of the booking (rather than the stay), excluding cancelled reservations.
- Stay date net: Takes all reservations based on the stay date, net of any cancellations - therefore all stayed bookings.
- Comparing the results with values from last year or with the Booking.com-defined competitive set, peer group or market.
- View by date, week, month or none (aggregates by total).
The following path and query parameters are available:
| Element | Description | Type | Required/Optional | Location | Notes |
|---|---|---|---|---|---|
propertyId | Specifies the ID of the property for which you want to retrieve insight values. | integer | required | Path parameter | |
start_date | Specifies the start date. | string | required | Query parameter | The API considers bookings within the start_date and end_date. |
end_date | Specifies the end date. | string | required | Query parameter | The API considers bookings within the start_date and end_date. |
include_reservations | Specifies the booking category for which you want to retrieve insight values. | string | required | Query parameter | Supports: - BOOK_DATE_GROSS: All reservations based on book date, including cancelled bookings. - BOOK_DATE_NET: All reservations based on book date, excluding cancelled bookings. - STAY_DATE_NET: All stayed reservations based on stay date, excluding cancelled bookings. |
view_by | Specifies how to group the insights. | string | optional | Query parameter | If omitted, defaults to NONE. Supports: - NONE: Aggregates by total - DATE - WEEK - MONTH |
compare_with | Specifies the condition to compare the insights with. | enumerated string | optional | Query parameter | If omitted, defaults to NONE. Possible values: - NONE - LAST_YEAR: The API compares the report with the same period one year earlier. - COMPETITIVE_SET: Includes properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of a group of similar properties in the target property's area. - MARKET: All properties in the target property's region. |
The following is a successful response body example:
{
"data": {
"report": {
"adr": {
"value": 147.1306211792597
},
"room_nights": {
"value": 5071.0
},
"revenue": {
"value": 746099.380000026
}
}
},
"warnings": [],
"errors": [],
"meta": {
"ruid": "Um123G9tSVYkc2RlIyh9YQzdwh+280lx897rDZF1JIZYdbF3XplmMYPN87IIbYDpF4gg5ppLWSo9FTHqy5069iHVvB2blrvu"
}
}The following table describes the response elements:
| Element | Description | Type | Notes |
|---|---|---|---|
data | Contains the response object. | object | |
> report | Contains the report details | object | |
>> adr | Contains the average daily rate value. | object | |
>>> value | Specifies the average rate charged per room per night, calculated as the total revenue divided by room nights sold. | float | |
>> room_nights | Contains the room nights value. | object | |
>>> value | Specifies the number of room nights stayed. | float | |
>> revenue | Contains the revenue value. | object | |
>>> value | Specifies the total amount of revenue earned in a certain time period, minus cancellations. | float |
For more information on how to handle error responses, see the Troubleshooting section.
Before you go live with your API integration, take a look at Going Live.