Changes in V3

This topic summarises the main changes in architecture, design and functionality between V2 and V3 of the Demand API. Read this topic to help you plan your migration.

API architecture and design

V2 used a monolithic design that was specific to the accommodation vertical of the travel market.

V3 replaces this design with a new, modular architecture that:

• Supports multiple and different verticals of the travel market.

• Provides new features, better performance and ease of use.

Version 3.0

V3.0 provides two new sets of endpoints:

• /accommodations/* endpoints provide functionality specific to the accommodation vertical of the travel market.

• /common/* endpoints provide generic, supporting information about different types of location (such as countries, cities, landmarks and airports), payments (currencies and payment cards) and languages. These endpoints are vertical-agnostic.

These endpoints support the [Search, look and redirect-to-book] (/demand/docs/getting-started/try-out-the-api#search-and-look) integration type.

Version 3.1

V3.1 adds the /orders/ endpoints, which provide common order processing and management functionality, and are vertical-agnostic.

These endpoints extend the API's capabilities to support Search, look and book and Post-booking integration types.

Authentication

In V3, each call to a Demand API endpoint must identify an API user that is authorised to access that endpoint. An API user is a unique pairing of your partner id and one of your affiliate ids.

To enable an API user to access the Demand API, you must do the following:

• Generate an API key for your partner account.

• Include your API key and the appropriate affiliate id in the header of every request.

The API key is an HTTP bearer token. Bearer tokens provide greater security than the Basic authentication method used in V2.

For more information, see Authentication and authorisation.

Endpoint structure

The following table compares the structure of V2 and V3 endpoints.

An example mapping

V2

GET https://distribution-xml.booking.com/2.10/hotelAvailability?
     city_ids=-2140479
     &guest_country="nl"
     &room1="A,A"
     &checkin="2023-08-15"
     &checkout="2023-08-16"

V3

POST https://demandapi.booking.com/3.1/accommodations/search
{
  "city": -2140479,
  "booker": {
      "platform": "desktop",
      "country": "nl"
      },
  "checkin": "2023-08-15",
  "checkout": "2023-08-16",
  "guests": {
      "number_of_rooms": 1,
      "number_of_adults": 2
      }
}

Reservation ids and order ids

An accommodation booking created in V2 is uniquely identified by a reservation_id, which is returned in the processBooking response. For example:

{
  "result": {
    "reservation_id": "1234567890"
    ...

An accommodation booking created in V3 has two identifiers, returned in the /orders/create response:

• accommodation.order is the unique id of the parent order that the accommodation booking is part of. The order id is the primary identifier that you should use when working with accommodation bookings (as part of orders) in V3.

• accommodation.reservation is the unique id of the accommodation booking itself. The reservation id is provided solely for backward compatibility with V2, so that you can still access orders created using V2 after you have migrated your integration to V3.

For example:

{
  ...
  {
    "accommodation": {
      "order": "509430129718799",
      "reservation": 2444627607
      ...

Errors

Error handling describes what errors can occur when calling V3 endpoints and what you should do to avoid or fix them. You should update your error handling code in line with the guidance and information given there.

Also, note that V3 reports errors differently to V2:

• The endpoint now returns an HTTP error status code (4_xx_ for a client-side error or 5_xx_ for a server-side error).

• A response body is only returned with an HTTP 400 code, or with some 5_xx_ codes.

• The response body contains further details about the error, but uses a different structure to V2 - see Client error ids for more details. For example:

{
    "request_id": "01gw5aaj8dkh7fvgwa7phs916x",
    "errors": [
        {
            "id": "missing_parameter",
            "message": "Parameter 'checkin' is missing."
        }
    ]
}

• request_id is the unique identifier for the response. This replaces the errors.ruid identifier used in a V2 error response.

New location endpoints

The following new location endpoints are available in V3:

• /common/locations/airports: This endpoint returns a list of airports, giving each airport's International Air Transport Association (IATA) code (id) and name (name).
  • In V2, these codes were only available in the documentation, not from the API itself. For example:

{
    "data": [
        ...
        {
            "id": "CDG",
            "name": {
                "fallback": "Paris - Charles de Gaulle Airport",
                "en-gb": "Paris - Charles de Gaulle Airport"
            }
        },
        ...
    ]
}

• /common/locations/landmarks: This endpoint returns a list of geographical landmarks, giving for each one a unique id its name and coordindates.

For example:

{
    "data": [
        ...
        {
            "id": 1,
            "name": {
                "fallback": "station-amsterdam-centraal",
                "en-gb": "Amsterdam Central Station"
            },
            "coordinates": {
                "latitude": 52.378281,
                "longitude": 4.900070
            }
        },
        ...
    ]
}

For more information see the following links in the API Reference:

• /common/locations/airports
• /common/locations/landmarks

Language support

New languages endpoint

The /common/languages endpoint returns a list containing the language code (id) and name of every language for which translations are available from the Demand API. In V2, these language codes were only available in the documentation, not from the API itself.

For example:

{
   "data": [
       {
           "id": "ar",
           "name": "العربية"
       },
       ...
       {
           "id": "en-gb",
           "name": "English (UK)"

       },
       ...
       {
           "id": "zh-cn",
           "name": "简体中文"
       },
    ]
}

You can use these language codes with any endpoint that provides translatable data in its response:

• In the request, specify the language(s) you want to return.

• In the response, identify the language used in any translated string.

Multiple language support

In V2, you could only get response data from the hotels endpoint in a single language (using the language query parameter).

In V3, you can now get response data from the equivalent /accommodations/details endpoint in multiple languages in the same call. If your application supports several different languages, using V3 can result in a significant reduction in the number of calls you need to make to obtain your content.

V3 uses a new languages request field, in which you can specify an array of language codes. For example, to get response data in British English, Spanish, Arabic and Chinese, specify the following in the request:

{
    "languages": [
        "en-gb",
        "es",
        "ar",
        "zh-cn"
    ]
}

In the response, each translatable field will be returned in each of the requested languages for which a translation exists. For example:

"name": {
    "ar": "كوخ حديقة \n\n",
    "zh-cn": "花园小屋 ",
    "en-gb": "Garden Cottage",
    "es": "Casa de campo Garden"
},

The following V2 endpoints also use the language parameter, but their V3 equivalents do not use the languages request field:

• blockAvailability and hotelAvailability: The V3 equivalents of these endpoints (accommodations/availability and accommodations/search) do not return any translatable content, so do not provide the languages request field.

• reviews and reviewScores: These endpoints use the language parameter differently.

Affiliate ID tracking

To allow you to redirect a traveller from your application to Booking.com to complete a booking, several Demand API endpoints return URLs to specific Booking.com accommodation pages.

For reporting and attribution purposes, these URLs should include the affiliate id that the request is to be tracked against:

• In V2, you could specify the affiliate ID to be used in the affiliate_id request parameter. This parameter is not supported in V3.

• In V3, these URLs automatically include the affiliate id specified in the X-Affiliate-Id header in the request. This makes it easier for partners who have multiple affiliate ids to track redirections on the affiliate, rather than partner, level. (See Authentication.)

You should modify your code as required to use the new mechanism. The following table shows:

• The V2 endpoints that return response fields containing redirection URLs, and the names of the returned fields. If the affiliate_id request parameter was specified, these fields will contain a query parameter containing that affiliate_id value.

• The equivalent V3 endpoints that return response fields containing redirection URLs, and the names of the returned fields. These fields will contain a query parameter containing the value of the affiliate id used to make the request.

The affiliate ID is appended to each redirection URL in the aid query parameter. For example:

{
   ...
   "deep_link_url": "booking://hotel/10004?affiliate_id=956509",
   ...
   "url": "https://www.booking.com/property/nl/testHotel-1.html?aid=956509",
   ...
}

Other improvements

• Pagination: V3 offers an easier way to use mechanism for paginating results.

• Support for long stays: Searches can now return data for long-stay bookings.

  • In an /accommodations/search request, the checkout date can now be up to 90 days after the checkin date.
  • In a V2 hotelAvailability request, the checkout date has to be within 30 days of the checkin date.

• Improved experience for more complex room needs, such as group and family searches - see Guest details and room allocation.