Managing Market insights API

Use this topic to implement the various endpoints in the Market insights API. By implementing Market insights API, you can:

Retrieve market demand data in a property's region

Performance insights reports:

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 can use the Quick connect interface in the Provider portal to request for an additional permission Performance data and insights from the connected partners.

Retrieving a demand report

GET https://supply-xml.booking.com/market-insights-api/properties/{property_id}/area_demand_data

The area_demand_data endpoint enables you to retrieve demand data for the target 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

For more information on how to handle error responses, see the Troubleshooting section.

Retrieving booking window information

GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/book_window_data

The 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.

Path parameters

You can include the following path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the ID of the property for which you want to retrieve insight values.	string	required
`date_range`	Specifies the date range within which you want to see the insight values.	enumerated string	required	Possible values are: - LAST_365_DAYS, - LAST_90_DAYS - LAST_60_DAYS - LAST_30_DAYS - LAST_14_DAYS - LAST_07_DAYS
`compare_with`	Specifies the condition to compare the insights with.	enumerated string	optional	Possible values are: - NONE - LAST_YEAR: The API compares the report with the values from last year, (365 days earlier than the specified date). - COMPETITIVE_SET: Includes up to 50 properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of 50 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.

Response body example

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"
  }
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`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
>> `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.

Retrieving booker insights data

GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/booker_insights_data

The 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.

Path parameters

You can include the following path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the ID of the property for which you want to retrieve insight values.	string	required
`date_range`	Specifies the date range within which you want to see the insight values.	enumerated string	required	Possible values are: - LAST_365_DAYS, - LAST_90_DAYS - LAST_60_DAYS - LAST_30_DAYS - LAST_14_DAYS - LAST_07_DAYS
`compare_with`	Specifies the condition to compare the insights with.	enumerated string	optional	Possible values are: - NONE - LAST_YEAR: The API compares the report with the values from last year, (365 days earlier than the specified date). - COMPETITIVE_SET: Includes up to 50 properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of 50 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.

Response body example

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"
  }
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`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

For more information on how to handle error responses, see the Troubleshooting section.

Retrieving Pace report data

GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/pace_report_data

Use 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).

Path parameters

You can include the following path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the ID of the property for which you want to retrieve insight values.	string	required
`date_range`	Specifies the date range within which you want to see the insight values.	enumerated string	required	Possible values are: - LAST_365_DAYS, - LAST_90_DAYS - LAST_60_DAYS - LAST_30_DAYS - LAST_14_DAYS - LAST_07_DAYS
`compare_with`	Specifies the condition to compare the insights with.	enumerated string	optional	Possible values are: - NONE - LAST_YEAR: The API compares the report with the values from last year, (365 days earlier than the specified date). - COMPETITIVE_SET: Includes up to 50 properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of 50 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	required	Supports the following options: - NONE: Aggregates by total - DATE - WEEK - MONTH

Response body example

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"
  }
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`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.

Retrieving Sales statistics report data

GET https://supply-xml.booking.com/market-insights-api/properties/{propertyId}/sales_statistics_report_data

Use 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:
- Books 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).

Path parameters

You can include the following path parameters:

Element	Description	Type	Required/Optional	Notes
`property_id`	Specifies the ID of the property for which you want to retrieve insight values.	string	required
`start_date`	Specifies the start date.	string	required	The API considers bookings within the `start_date` and `end_date`.
`end_date`	Specifies the end date.	string	required	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	Supports the following options: - 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 the sorting order to view the insights.	string	optional	Supports the following options: - NONE: Aggregates by total - DATE - WEEK - MONTH
`compare_with`	Specifies the condition to compare the insights with.	enumerated string	optional	Possible values are: - NONE - LAST_YEAR: The API compares the report with the values from last year, (365 days earlier than the specified date). - COMPETITIVE_SET: Includes up to 50 properties selected by Booking.com based on what guests were looking at before booking a specific property. - PEER_GROUP: Consists of 50 similar properties in the target 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.

Response body example

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"
  }
}

Response body elements

The following table describes the response elements:

Element	Description	Type
`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.

Going live

Before you go live with your API integration, take a look at Going Live.