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_data

The 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