Getting Started

Introduction

This guide is intended primarily for developers. It is a supplement to our technical documentation, which should be consulted for more detailed information on all endpoints.

Major and Minor Versions

Versions are named as follows: MAJOR.MINOR

Examples:
v2.0 - major version 2, minor version 0
v2.1 - major version 2, minor version 1

Features will not be removed in minor versions except when required for legal or security reasons. This means that minor versions will be backwards-compatible with their corresponding major versions.

Minor versions may include:

• New features (parameters and output values).
• Fields that may be marked as deprecated. These fields will be removed in the next major version.

Authentication

The Booking.com Demand API uses HTTP Basic Authentication. For more details, please refer to this Wikipedia article.

Sample URLs

General syntax:

https://[domain]/[version]</[xml or json]>/[endpoint]?[parameters]

JSON and XML examples for v2.0:

• GET https://distribution-xml.booking.com/2.0/hotels?hotel_ids=10004
• GET https://distribution-xml.booking.com/2.0/xml/hotels?hotel_ids=10004

The default output format is JSON. XML output can be obtained adding /xml to the URL, or by passing the HTTP header Accept: text/xml

Our technical documentation contains JSON URL samples for every endpoint.

Output format

JSON example

{
  "result": [
  ],
  "errors": [ {
    "code": 1000,
    "message": "Sample error message"
  } ],
  "warnings": [ {
    "code": 1001,
    "message": "Sample warning message"
  } ],
  "request_params": {
  }
}

XML example

<EndpointName>
  <result></result>
  <result></result>
  <errors>
    <code>1000</code>
    <message>Sample error message</message>
  </errors>
  <warnings>
    <code>1001</code>
    <message>Sample warning message</message>
  </warnings>
  <request_params></request_params>
</EndpointName>

Note: To generate request_params (requested parameters) in the output, the input parameter show_request_params=1 needs to be added in the request. This can be useful for debugging.

Pagination

The offset and rows input parameters are used for pagination.
The offset input parameter specifies where in the resulting list to start pagination.
The rows parameter specifies the maximum number of entries to return.

Usage Examples:

Retrieve the first 100 entries: cities?offset=0&rows=100
Retrieve the next 100 entries starting from the 100th row: cities?offset=100&rows=100

Limitations

Requests made to the API cannot exceed 8192 characters. In the event of a violation, user will receive a HTTP 403 error response.
HTTP GET requests may not contain a request body. In the event of a violatoin, user will receive a HTTP 403 error response.