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 \

Sample response

`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 datesas well as your most popular roomsfor 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"
         },
         {
            "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 \

Sample response

`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 datesas well as your most popular roomsfor 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"
      },
      {
        "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
`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
`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