In beta

This product is still in beta. If you ended up here by mistake, you should direct any questions to your Booking.com contact person via the appropriate channels.

Managing area demand data

This section describes all the possible actions related to retrieving demand data via the Market insights API.

Historical data

You can retrieve a demand data report for your property's region by specifiying their property id. The data in this report is historical, going back two weeks from the date the report is generated. It updates once per 24 hours (report generation process starts midnight CET).

You retrieve the data in form of categories with multiple data points expressing in percentages the share each represents.

Demand data categories

This API returns demand data for the following categories (by title):

  • Book window: Refers to the number of days in the future that guests looked to book.
  • Traveller type: Refers to whether guests planned to travel solo, as a couple, family, or group.
  • Device: Refers to the device guests used to look for bookings.
  • Cancellation policy: Refers to which cancellation policies were most popular based on actual reservations.
  • Top 5 countries: Refers to the top countries from which the guests searched (based on ip address).
  • Domestic and international travellers: Refers to whether guests searched from the country in which the region is (domestically) or from another country (international).

Retrieving demand data

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 you want to retrieve demand data for. 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"  
            }  
        ]  
    },  
    "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 region of the property to which the demand data apply to. 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 take-away from the demand data in the category it belongs to. string
>> stats Contains the demand data specifics per 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 more human readable version of the data point. string
>> title Specifies a more human readable version of the category name. string