Retrieving opportunities

Retrieving opportunities enables you to:

  • Retrieve information on all existing opportunities.
  • Find out which properties are eligible for which opportunities.
  • Retrieve instructions to render opportunities into a property's interface.
  • Retrieve information on which dates the demand in a property's area is high.

→ If you want to implement or dismiss opportunities after retrieving them, see implementing or dismissing opportunities.

Retrieving all opportunities

GET
https://supply-xml.booking.com/opportunity-api/opportunities

The GET /opportunity-api/opportunities request enables you to retrieve all the opportunities that are available on Booking.com.

→ If you want to know the opportunities for which a specific property is eligible, see retrieving opportunities for a property
→ If you want to know the properties that can implement a specific opportunity, see retrieving properties by opportunity

Header parameters

The following table lists the header parameters in the request:

Parameter Description Type Required/Optional Notes
Accept-Language Specifies the language in which you want to receive the opportunity information. enum optional You can find the lists of possible language codes at https://connect.booking.com/user_guide/site/en-US/codes-bcl/
Authorization Machine account username and password string Required Example: Authorization: Basic {username:password}

Sample request

You can find an example request in cURL here:

curl -X GET \
  https://supply-xml.booking.com/opportunity-api/opportunities \

PROVIDER opportunities look slightly different.

PROVIDER opportunities do not have all of the elements that TOGGLE and REDIRECT have. You can find examples of each in the following sample.

You can find a sample response here:

{
   "meta":{
      "ruid":"UmFuZG9tSVYkc2RlIyh6tr5vLrXVLc8GmUNIDetw/f912Hsa9sYk3GpQsk+ue9zdmvFPiClRDlNCaDgNDpsoMuOgnyDN"
   },
   "data":{
      "opportunities":[
         {
            "description":"We noticed your property is unavailable to book on certain high-demand dates for guests looking to stay in your area. We've highlighted these dates”as well as your most popular rooms”for you to take action on. Add more availability right away to start getting bookings!",
            "title":"You're missing out on bookings for the most popular dates in your area",
            "opportunity_id":"high_demand_dates_inventory",
            "implementation":"PROVIDER",
            "destination_api":"Unassigned"
         },
         {
            "opportunity_id":"cucc_adoption_oc_promotion",
            "destination_api":"Unassigned",
            "cta":"Implement opportunity",
            "title":"Attract more guests from China by enabling payment with China UnionPay credit cards",
            "description":"Most guests from China prefer using their China UnionPay credit card for their trips. Having a payment method available for their frequently used credit cards is a key element for them to make a decision of where to book. This will help promote your property and provide a more localised experience for your guests from China.",
            "implementation":"TOGGLE"
         },
         {
            "url":"https://admin.booking.com/hotel/hoteladmin/extranet_ng/manage/connectivity_redirect.html?source=opp_api&hotel_id=5729902&redirect_id=no_credit_card_details_for_domestic_bookings&lang=en",
            "implementation":"REDIRECT",
            "destination_api":"Content API",
            "description":"Some guests may not have a credit card or may not want to use this. For customers living in your home country, you can offer a simplified booking process that doesn’t require credit card details.",
            "instructions":"Enable by clicking the button",
            "title":"Attract domestic customers by enabling room reservations without credit cards",
            "cta":"Activate through Booking.com",
            "opportunity_id":"no_credit_card_details_for_domestic_bookings"
         }
      ]
   },
   "warnings":[],
   "errors":[]
}

Response body

The following table describes the elements of the response body:

Element Description Type Notes
meta Contains the meta data that comes with the response. object
ruid Specifies the unique id of the request. string You can send this id to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
data Contains the response data. object
opportunities Contains the opportunity objects. array
description Specifies a recommendation for describing the opportunity. string
title Specifies a recommendation for introducing the opportunity. string
opportunity_id Specifies the unique id of the opportunity. string
implementation Specifies the type of implementation. string The three possible implementation types are TOGGLE, REDIRECT, and PROVIDER.
destination_api Specifies the API to which an opportunity belongs. string
categories Contains the categories in which opportunities are organised. array
category_name Specifies the name of the opportunity category. The possible values are: Availability, Ranking, Page views, Conversions, Length of stay, Average daily rate, Cancellations, Reduce workload, and Promotions. string
cta Specifies a recommendation for describing the action. string
title Specifies a recommendation for introducing the opportunity. string
description Specifies a recommendation for describing the opportunity. string
url Specifies the URL that enables you to perform an action on the opportunity. string
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array

Retrieving opportunities for a property

GET
https://supply-xml.booking.com/opportunity-api/properties/{property_id}/opportunities

The GET /opportunity-api/properties/{property_id}/opportunities request enables you to retrieve all the possible opportunities for a specific property. This means you must specify the property id to receive a list of opportunities that the property is eligible for.

Prioritisation of opportunities

The response lists the available opportunities by priority. You should present them in the same order on the property's interface.

Path parameters

The following table lists the query parameters in the request:

Parameter Description Type Required/Optional Notes
property_id Specifies the id of the property you want to retrieve opportunities for. integer required You can only specify one property id per call.

Header parameters

The following table lists the header parameters in the request:

Parameter Description Type Required/Optional Notes
Accept-Language Specifies the language in which you want to receive the opportunity information. enum optional You can find the lists of possible language codes at https://connect.booking.com/user_guide/site/en-US/codes-bcl/
Authorization Machine account username and password string Required Example: Authorization: Basic {username:password}

Sample request

You can find a cURL example request here:

curl -X GET \
  https://supply-xml.booking.com/opportunity-api/properties/5729902/opportunities \

PROVIDER opportunities look slightly different.

PROVIDER opportunities have a few different elements from TOGGLE and REDIRECT opportunities, and vice versa.

You can find a sample response here:

{
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyh6tr5vLrXVLc8GmUNIDetw/f912Hsa9sYk3GpQsk+ue9zdmvFPiClRDlNCaDgNDpsoMuOgnyDN"
  },
  "data": {
    "opportunities": [
      {
        "implementation_data": [
          {
            "entity_id": "1234599_2020-02-19",
            "entity_type": "STAY_ID"
          },
          {
            "entity_id": "1234500_2020-02-19",
            "entity_type": "STAY_ID"
          },
          {
            "entity_id": "1234599_2020-02-20",
            "entity_type": "STAY_ID"
          }
        ],
        "description": "We noticed your property is unavailable to book on certain high-demand dates for guests looking to stay in your area. We've highlighted these dates”as well as your most popular rooms”for you to take action on. Add more availability right away to start getting bookings!",
        "title": "You're missing out on bookings for the most popular dates in your area",
        "opportunity_id": "high_demand_dates_inventory",
        "categories":[
               {
                  "category_name":"Availability"
               },
               {
                  "category_name":"Conversion"
               },
               {
                  "category_name":"Ranking"
               }
            ],
        "implementation": "PROVIDER"
      },
      {
        "opportunity_id": "cucc_adoption_oc_promotion",
        "destination_api": "Unassigned",
        "categories": [
          {
            "category_name": "Conversions"
          },
          {
            "category_name": "Promotions"
          }
        ],
        "cta": "Implement opportunity",
        "title": "Attract more guests from China by enabling payment with China UnionPay credit cards",
        "description": "Most guests from China prefer using their China UnionPay credit card for their trips. Having a payment method available for their frequently used credit cards is a key element for them to make a decision of where to book. This will help promote your property and provide a more localised experience for your guests from China.",
        "implementation": "TOGGLE"
      },
      {
        "url": "https://admin.booking.com/hotel/hoteladmin/extranet_ng/manage/connectivity_redirect.html?source=opp_api&hotel_id=5729902&redirect_id=no_credit_card_details_for_domestic_bookings&lang=en",
        "implementation": "REDIRECT",
        "destination_api": "Content API",
        "description": "Some guests may not have a credit card or may not want to use this. For customers living in your home country, you can offer a simplified booking process that doesn’t require credit card details.",
        "instructions": "Enable by clicking the button",
        "categories": [
          {
            "category_name": "Conversions"
          },
          {
            "category_name": "Promotions"
          }
        ],
        "title": "Attract domestic customers by enabling room reservations without credit cards",
        "cta": "Activate through Booking.com",
        "opportunity_id": "no_credit_card_details_for_domestic_bookings"
      }
    ]
  },
  "warnings": [],
  "errors": []
}

Response body

The following table describes the elements of the response body:

Element Description Type Notes
meta Contains the meta data that comes with the response. object
ruid Specifies the unique id of the request. string You can send this id to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
data Contains the response data. object
opportunities Contains the opportunity objects. array
implementation_data Contains the data specific to implementing the PROVIDER type opportunities. array
entity_id Specifies the room id and the date on which the demand is high. string
entity_type Specifies the type of the PROVIDER opportunity. string The only possible value is STAY_ID
description Specifies a recommendation for describing the opportunity. string
title Specifies a recommendation for introducing the opportunity. string
opportunity_id Specifies the unique id of the opportunity. string
implementation Specifies the type of implementation. string The three possible implementation types are TOGGLE, REDIRECT, and PROVIDER.
destination_api Specifies the API to which an opportunity belongs. string
categories Contains the categories in which opportunities are organised. array
category_name Specifies the name of the opportunity category. The possible values are: Availability, Ranking, Page views, Conversions, Length of stay, Average daily rate, Cancellations, Reduce workload, and Promotions. string
cta Specifies a recommendation for describing the action. string
title Specifies a recommendation for introducing the opportunity. string
description Specifies a recommendation for describing the opportunity. string
url Specifies the URL that enables you to perform an action on the opportunity. string
implementation Specifies the type of implementation. string The three possible implementation types are TOGGLE, REDIRECT, and PROVIDER.
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array

Retrieving properties by opportunity

GET
https://supply-xml.booking.com/opportunity-api/opportunities?opportunity_id={opportunity_id}

The GET /opportunity-api/opportunities?opportunity_id={opportunity_id} request enables you to retrieve all the properties that are eligible for a specific opportunity. This means you must specify the opportunity id to receive a list of eligible properties.

Use of pagination

Because the amount of properties for this bulk call can be big, retrieving all of them at once can cause issues. Therefore, this call includes pagination, which you can modify depending on your situation or preferences.

Query parameters

The following table lists the query parameters in the request:

Parameter Description Type Required/Optional Notes
opportunity_id Specifies the id of the opportunity for which you want to retrieve the eligible properties. string required You can only specify one opportunity id per call.
page Specifies the number of the page you want to retrieve. integer optional The default value is 1.
page_size Specifies the number of properties you want to retrieve per page. integer optional The default value is 100. For PROVIDER opportunities, the default value of 100 is also the max value.

Header parameters

The following table lists the header parameters in the request:

Parameter Description Type Required/Optional Notes
Accept-Language Specifies the language in which you want to receive the opportunity information. enum optional You can find the lists of possible language codes at https://connect.booking.com/user_guide/site/en-US/codes-bcl/
Authorization Machine account username and password string Required Example: Authorization: Basic {username:password}

Sample request

You can find a cURL example request for TOGGLE and REDIRECT opportunities below. For a PROVIDER opportunity example, see provider type sample request.

curl -X GET \
  https://supply-xml.booking.com/opportunity-api/opportunities?opportunity_id=free_wifi&page=2&pagesize=100 \

Sample response

{
  "data": { 
    "opportunity":{ 
      "opportunity_id":"free_wifi",
      "title":"Show guests that your property offers free Wi-Fi",
      "description":"WiFi is one of the most requested features by modern travellers. Meet demand and make properties more attractive by showing potential guests that they offer free Wifi included in the stay.",
      "instructions":"Just enable by clicking the button",
      "cta":"Enable",
      "implementation":"TOGGLE",
      "url":"https://admin.booking.com/hotel/hoteladmin/extranet_ng/manage/availability_calendar.html",
      "destination_api":"Content API",
   },
    "properties":[ 
      { 
      "property_id":"12345",
      "status":"eligible"
      },
      { 
      "property_id":"54321",
      "status":"ineligible/implemented"
      }
   ],
    "pagination":{ 
      "page":2,
      "page_size":100,
      "page_count":123,
      "total_count":12300
   }
 },
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyd4ggzfY4dZasPGAUcglKEyRzk2/HbSzspV7O+mQdkB4hP2dlEyQkjV+iI71VQFka7vNa5MAta305nepI2yvXTv4="
    },
 "errors": [],
 "warnings": []
}

Response body

The following table describes the elements of the response body:

Element Description Type Notes
meta Contains the meta data that comes with the response. object
ruid Specifies the unique id of the request. string You can send this id to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
data Contains the response data. object
opportunity Contains the specified opportunity information. array
opportunity_id Specifies the unique id of the opportunity. string
title Specifies a recommendation for introducing the opportunity. string
description Specifies a recommendation for describing the opportunity. string
instructions Specifies the instructions the property must follow to implement or dismiss the opportunity. string
cta Specifies a recommendation for describing the action. string
implementation Specifies the type of implementation. string The three possible implementation types are TOGGLE, REDIRECT, and PROVIDER.
url Specifies the url that enables you to perform an action on the opportunity. string
destination_api Specifies the api to which an opportunity belongs. string
categories Contains the categories in which opportunities are organised. array
category_name Specifies the name of the opportunity category. The possible values are: Availability, Ranking, Page views, Conversions, Length of stay, Average daily rate, Cancellations, Reduce workload, and Promotions. string
properties Contains the eligible opportunities. array
property_id Specifies the unique id of the eligible property. string
status Specifies the status of the opportunity. The possible values are: eligible and ineligible/implemented enum
pagination Contains the pagination information. object
page Specifies the page number that you requested. If you didn't specify the number, it returns page 1. integer
page_size Specifies the number of properties per page. If you didn't specify the amount, it returns 100 properties per page. integer
page_count Specifies the number of pages with properties. integer
total_count Specifies the total amount of properties connected to your machine account. integer
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array

Provider type sample request

You can find a cURL example request for a PROVIDER opportunity example here:

curl -X GET \
  https://supply-xml.booking.com/opportunity-api/opportunities?opportunity_id=high_demand_dates_inventory&page=1&pagesize=50 \

Provider type sample response

{
  "data": {  
    "properties": [
      {  
        "property_id": "6038700",  
        "implementation_data": []  
      },    
      {  
        "property_id": "6038692",  
        "implementation_data": [
          {  
            "entity_id": "566202102_2020-01-25",  
            "entity_type": "STAY_ID"  
          },  
          {  
            "entity_id": "566202102_2020-01-26",  
            "entity_type": "STAY_ID"  
          }
        ]
       }
      ],
    "opportunity": {  
      "title": "You're missing out on bookings for the most popular dates in your area",  
            "destination_api": "Unassigned",  
            "implementation": "PROVIDER",  
            "description": "We noticed your property is unavailable for bookings on some dates that are in high demand by guests looking for stays in your area. We have highlighted these dates, alongside your most popular rooms, for you to take action on. Add more availability right away to start gaining bookings!",  
            "opportunity_id": "high_demand_dates_inventory",
        },  
    "pagination": {  
      "page_size": 50,  
      "total_count": 263,  
      "page": 1,  
      "total_pages": 6  
    },     
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyd4ggzfY4dZasPGAUcglKEyRzk2/HbSzspV7O+mQdkB4hP2dlEyQkjV+iI71VQFka7vNa5MAta305nepI2yvXTv4="
  },
  "errors": [],
  "warnings": []
  }
}

Provider type response body

The following table describes the elements of the response body:

Element Description Type Notes
meta Contains the meta data that comes with the response. object
ruid Specifies the unique id of the request. string You can send this id to Booking.com customer support if you run into an issue. This can help to understand what went wrong.
data Contains the response data. object
opportunity Contains the specified opportunity information. array
opportunity_id Specifies the unique id of the opportunity. string
title Specifies a recommendation for introducing the opportunity. string
description Specifies a recommendation for describing the opportunity. string
implementation Specifies the type of implementation. string The three possible implementation types are TOGGLE, REDIRECT, and PROVIDER.
destination_api Specifies the api to which an opportunity belongs. string
properties Contains the eligible opportunities. array
property_id Specifies the unique id of the eligible property. string
implementation_data Contains the data specific to implementing the PROVIDER type opportunities. array
entity_id Specifies the room id and the date on which the demand is high. string
stay_id Specifies the type of the PROVIDER opportunity. string The only possible value is STAY_ID, which contains the room id and the date.
pagination Contains the pagination information. object
page Specifies the page number that you requested. If you didn't specify the number, it returns page 1. integer
page_size Specifies the number of properties per page. If you didn't specify the amount, it returns 100 properties per page. integer
page_count Specifies the number of pages with properties. integer
total_count Specifies the total amount of properties connected to your machine account. integer
warnings Contains potential warnings. These can help you improve your requests. array
errors Contains potential errors. These can help you understand what went wrong with your request. array