Last edited: 22 feb 2023
Analysing Booking.com guests' demand data¶
Use the Market insights API to explore what the guests are searching for using Booking.com and to better understand the demand in your property's region. Booking.com provides insights into guests' searches by helping you analyse the anonymised search data.
Prerequisites¶
To provide reliable and accurate data, the API is currently supported only for properties meeting the following criteria:
- Have been open and bookable at least once.
- Have at least 30 open and bookable properties listed on Booking.com in the property's area.
- Have at least 1200 guest searches in the previous two weeks for properties in the property's area.
Using the API without meeting the criteria
The API returns the following error message if the property does not meet the criteria mentioned above:
The property is not eligible for retrieving demand data.
Reports use past two-weeks data¶
The API returns a report that provides insights on the property's region based on the property ID you specify. The report uses the previous two weeks data from the date the report is generated. The data is updated once per 24 hours and the report generation process starts every day at midnight (CET).
Retrieving demand data for a test property
When using the endpoint on a test property, the API returns mock data for the Paris region.
Understanding the report¶
Using the Market insights API, you can find:
- The guest's search window: The number of days ahead of their stay that guests took to search.
- The traveller type: For example, whether guests wanted to travel alone, as a couple, a family or a group.
- The most popular device type they use to search for the stay. For example, mobile or a computer.
- The cancellation policy attached to the stay. For example, you can find the details of cancellation policies that were most popular based on actual reservations.
- The top 5 countries from where the bulk of the guests' search come, based on IP address.
- The guests' stay destination, whether domestic or international. For example, guests from France searching for stays in New Zealand are reported as an international destination.
The report contains a score in percentage for each of the metrics grouped under six categories as shown in the following table.
| Category | Book window ( book_window) |
|||||
| Metrics | 0-1 days | 2-7 days | 8-30 days | 31-90 days | 90+ day | No dates |
| Description | Guests looking for stays less than 2 days | Guests looking for stays between two and seven days | Guests looking for stays between eight and thirty days | Guests looking for stays between thirty one and ninety days | Guests looking for stays longer than ninety days | Guests searching without any fixed dates |
| Category | Traveller type ( traveller_type) |
|||
| Metrics | Couple | Solo traveller | Family | Group |
| Description | Two guests travelling together | A single guest travelling | Two or more adult guests accompanied by one or more children | More than two adult guests travelling as a group |
| Category | Domestic and international travellers (origin) |
|
| Metrics | Domestic | International |
| Description | Guests who are searching for stays in your property's region and from the same country | Guests searching for stays in your property's region but are currently residing in a different country |
| Category | Device (device) |
||
| Metrics | Mobile | Desktop | Unidentified |
| Description | Guests using mobile devices to search | Guests using desktop computers | Guests using devices that are neither mobile nor desktop |
| Category | Top 5 countries (rank) |
||||
| Metrics | Country 1 | Country 2 | Country 3 | Country 4 | Country 5 |
| Description | Guests from country 1 searching for stays in your property's region | Guests from country 2 searching for stays in your property's region | Guests from country 3 searching for stays in your property's region | Guests from country 4 searching for stays in your property's region | Guests from country 5 searching for stays in your property's region |
| Category | Cancellation policy (policy) |
||
| Metrics | Free cancellation | Non-refundable | Partially refundable |
| Description | Guests making reservations for a property (or room) where the cancellation policy allows for free cancellation | Guests making reservations for a property (or room) where the cancellation policy charges in full on any cancellations | Guests making reservations for a property (or room) where the cancellation policy charges a partial amount on cancellations |
Retrieving a demand report¶
GET https://supply-xml.booking.com/market-insights-api/properties/{property_id}/area_demand_dataThe GET /market-insights-api/properties/{property_id}/area_demand_data request enables you to retrieve demand data for your property's region.
Path parameters¶
You must include the following path parameter to specify the property.
| Element | Description | Type | Required/Optional | Notes |
|---|---|---|---|---|
property_id |
Specifies the ID of the property for which you want to retrieve demand data. | string | required |
Response body example¶
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=="
}
} Response body elements¶
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, and traveler_type. |
>> 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 |