Managing Market insights API

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

Performance insights reports:

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

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

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

Going live

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