Getting Started

Introduction

This guide is intended primarily for developers, as a supplement to the technical documentation. See the technical documentation for detailed specifications on all endpoints.

Major and Minor Versions

Versions are named as follows: MAJOR.MINOR

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

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).
  • Some fields may be marked as deprecated. These fields will be removed in the next major version.

Migrating from v1.1 to v2

API users migrating from v1.1. to v2 can use the migration guide to quickly see what's changed in v2.

Authentication

The Booking.com Demand API uses HTTP Basic Authentication. For more information 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/json/hotels?hotel_ids=10004
  • GET https://distribution-xml.booking.com/2.0/xml/hotels?hotel_ids=10004

The full 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 output request_params (requested parameters) in the output, show_request_params=1 input parameter needs to be set. This can be useful for debugging.

Pagination

Pagination is done with offset and rows input parameters.

  • offset: Where in the resulting list to start.
  • rows: The maximum number of entries to return.

Usage Examples:

Get first 100 entries: cities?offset=0&rows=100

Get the next 100 entries starting from the 100th row: cities?offset=100&rows=100