ACCOMMODATION
/
Quick guide
/
Version 3.1
Last updated

v3.1 Accommodation quick guide

Follow this quick guide to start playing with our v3.1 Accommodation API collection in your client application.

⏱️ Estimated time to complete: 15 - 30 minutes

This quick guide shows the minimum steps needed to integrate the Demand API accommodation endpoints.

Steps

Follow these steps to test a basic example:

A traveller searches for a 2-night stay in Amsterdam for 2 adults in 1 room.

1. Search for accommodation

To find properties that match the use case search criteria:

→ Use the accommodations/search endpoint.

Example request:

{
  "country": "es",
  "booker": {
    "country": "es",
    "platform": "mobile"
  },
  "checkin": "2026-11-06",
  "checkout": "2026-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}
More details You can use different search parameters: * `city` is a Booking.com location ID (get these from [/locations/cities endpoint](/demand/docs/open-api/demand-api/commonlocations/common/locations/cities)). * Always use ISO 3166-1 alpha-2 lowercase for `country` (get these from [/locations/countries endpoint](/demand/docs/open-api/demand-api/commonlocations/common/locations/countries)). * `platform` can be "desktop", "mobile", or "tablet". * You can also use `accommodations` IDs for specific property search.

Example response:

The response contains a list of accommodations that match the specified search criteria, including the price and url to Booking.com property page.

{
  "request_id": "01khtsn77md9gvwbw157960692",
  "data": [
    {
      "id": 13766008,
      "commission": {
        "amount": 0,
        "percentage": 0
      },
      "currency": "EUR",
      "deep_link_url": "booking://hotel/13766008?affiliate_id=956509&checkin=2026-11-06&checkout=2026-11-08&mcid=10",
      "price": {
        "book": 644.8,
        "total": 644.8
      },
      "products": [
        {
          "id": "1376600801_409788848_0_0_0_843543",
          "bundle": 843543,
          "children": [],
          "deal": {
            "discount_percentage": 14,
            "public_price": 748,
            "tags": [
              "seasonal_deal"
            ]
          },
          "number_available_at_this_price": 1,
          "number_of_adults": 2,
          "policies": {
            "cancellation": {
              "free_cancellation_until": null,
              "type": "special_conditions"
            },
            "meal_plan": {
              "meals": [],
              "plan": "no_plan"
            },
            "payment": {
              "prepayment_required": true,
              "timings": [
                "pay_online_now"
              ]
            }
          },
          "price": {
            "book": 644.8,
            "total": 644.8
          },
          "room": 1376600801
        }
      ],
      "url": "https://www.booking.com/hotel/es/beach-apartment-denia.html?aid=956509&checkin=2026-11-06&checkout=2026-11-08&no_rooms=1&group_adults=2&mcid=10"
    }
  ]
}

Keep the accommodation id (13766008) for the next step.

→ Try it yourself

2. Get accommodation details

→ Call /accommodations/details using the accommodation id from the search response (13766008).

Example request:

{
  "accommodations": [
      13766008
  ],
  "extras": [
    "description"
  ],
  "languages": [
    "en-gb"
  ]
}
More details

Multiple languages can be requested; if data isn't available in your preferred language, English is returned by default.

genius-bulb Use the extras field to retrieve more details about the accommodation. For example:

  • If you want to use a photograph in your search results, add the field "extras": ["photos"] to your request.
  • If you wish to see the property supported payment methods, add the field "extras": ["payment"] to your request.

Example:

  "extras": [
    "description",
    "photos",
    "facilities",
    "payment"
  ],

→ Try it yourself

Example response:

The response contains all the information about the selected accommodation including contact information, number of rooms, score/reviews, etc.

{
  "request_id": "01k2kv6g4de00n4cw4cvr4v5bm",
  "data": [
    {
      "id": 10507360,
      "name": {
        "en-gb": "Demand API Sandbox Hotel Orion"
      },
      "accommodation_type": 204,
      "booker_address_required": false,
      "checkin_checkout_times": {
        "checkin_from": "12:00:00",
        "checkin_to": "20:00:00",
        "checkout_from": "08:00:00",
        "checkout_to": "12:00:00"
      },
      "contacts": {
        "general": {
          "email": "demand.api.dev@booking.com",
          "telephone": "+31207125609"
        },
        "reservations": null
      },
      "currency": "EUR",
      "is_genius": true,
      "is_work_friendly": false,
      "location": {
        "address": {
          "en-gb": "Oosterdoksstraat 154"
        },
        "city": -2140479,
        "coordinates": {
          "latitude": 52.376388,
          "longitude": 4.90919
        },
        "country": "nl",
        "districts": [
          145,
          9173
        ],
        "postal_code": "1011 DL",
        "regions": [
          1010
        ]
      },
      "meal_prices": {
        "breakfast": 12,
        "lunch": 10,
        "dinner": 15
      },
      "number_of_rooms": 300,
      "ranking": 4703915,
      "rating": {
        "number_of_reviews": 0,
        "preferred": true,
        "review_score": null,
        "stars": 5,
        "stars_type": "official"
      },
      "spoken_languages": [
        "en-gb"
      ],
      "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509"
    }
  ]
}

3. Get availability and prices

→ Use accommodations/availability endpoint with the same traveller criteria..

  • Include the accommodation id (13766008) from search.

Example request:

{
  "accommodation": 13766008,
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },

  "checkin": "2026-02-02",
  "checkout": "2026-02-10",
  "extras": [
    "include_bundle_variants"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

Example response:

The response includes the available products and prices, together with a recommendation.

{
  "request_id": "01k2m3js8k6rkgb09vehxcfbjy",
  "data": {
    "id": 10507360,
    "currency": "EUR",
    "products": [
      {
        "id": "1050736003_405384551_0_42_0_1122794",
        "commission": {...},
        "deal": {
          "discount_percentage": 3,
          "public_price": 98.2,
          "tags": [
            "mobile_rate"
          ]
        },
        "maximum_occupancy": {
          "adults": 4,
          "children": null,
          "total": 4
        },
        "number_available_at_this_price": 6,
        "policies": {...},
        "price": {
          "book": 95.38,
          "total": 95.38
        },
        "room": 1050736003
      },
      {
        "id": "1050736003_377312697_0_41_0_1122794",
        "commission": {
          "amount": 0,
          "percentage": 0
        },
        "deal": {
          "discount_percentage": 5,
          "public_price": 140,
          "tags": [
            "mobile_rate"
          ]
        },
        "maximum_occupancy": {
          "adults": 4,
          "children": null,
          "total": 4
        },
        "number_available_at_this_price": 6,
        "policies": {
          "cancellation": {
            "free_cancellation_until": "2025-10-29T22:59:59+00:00",
            "schedule": [
              {
                "from": "now",
                "price": 0
              },
              {
                "from": "2025-10-29T23:00:00+00:00",
                "price": 31.5
              }
            ],
            "type": "free_cancellation"
          },
          "meal_plan": {
            "meals": [
              "breakfast"
            ],
            "plan": "breakfast_included"
          },
          "payment": {
            "prepayment_required": false,
            "timings": [
              "pay_at_the_property",
              "pay_online_later",
              "pay_online_now"
            ]
          }
        },
        "price": {
          "book": 133,
          "total": 133
        },
        "room": 1050736003
      },
    ],
    "recommendation": {
      "price": {
        "book": 95.38,
        "total": 95.38
      },
      "products": [
        {
          "id": "1050736003_405384551_0_42_0_1122794",
          "children": [],
          "number_of_adults": 2,
          "price": {
            "book": 95.38,
            "total": 95.38
          }
        }
      ]
    },
    "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509&checkin=2025-11-06&checkout=2025-11-08&no_rooms=1&group_adults=2"
  }
}

genius-bulb Highlight the recommendation field to show the best-priced option.

Prices may change between search and availability. Always confirm before booking.

→ (Try it yourself)

4. Handle the booking

Choose your integration type:

  • Search, look and redirect → Redirect travelleres to the Booking.com url provided in the availability response.
  • Search, look and book → Book within your application using /orders/preview and /orders/create

For Search, look and book, you must have:

  • An approved business case.
  • A signed partner agreement.
Orders guides

Best practices

✓ Always include your API key token and X-Affiliate-Id in every request.

✓ Use the correct data conventions in your requests to avoid errors.

✓ Store static location data (cities, countries, etc) to reduce API calls.

Next steps

Congratulations, by now you know the basics of how to use the key accommodation endpoints!

Previous page
Next page