ACCOMMODATION
/
Quick guide
/
Version 3.2
Last updated

v3.2 Accommodation quick guide

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

⏱️ Estimated time to complete: 15 - 30 minutes v3.2

This quick guide shows the minimum steps needed to integrate the v3.2 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.

  • By default, the response returns the cheapest available product per accommodation.
  • When filtering by broader locations such as country or region, results are ranked by Booking.com popularity (top picks) rather than strictly by price.

Required fields

The following fields are mandatory:

  • booker
  • checkin
  • checkout
  • guests

Example request:

{
  "country": "nl",
  "booker": {
    "country": "nl",
    "platform": "mobile"
  },
  "extras": [
    "extra_charges",
    "products"
  ],
  "checkin": "2026-11-06",
  "checkout": "2026-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  },
    "sort": {
    "by": "price",
    "direction": "ascending"
  }
}
More details

You must specify at least one location parameter. Supported options include:

  • city — city ID
  • country — ISO 3166-1 alpha-2 lowercase
  • region
  • district
  • airport
  • landmark
  • coordinates
  • accommodations — specific accommodation IDs (max 100)

Get location IDs from location endpoints

Filters

Use the filters object to refine results. For example:

  • price (per night range — requires currency)
  • rating (review score and/or stars)
  • meal_plan
  • cancellation_type
  • payment timing
  • accommodation_types
  • accommodation_facilities
  • room_facilities
  • travel_proud
  • sustainability_certification

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": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 10507360,
      "currency": {
        "accommodation": "EUR",
        "booker": "EUR"
      },
      "deep_link_url": "booking://hotel/10507360?affiliate_id=956509&checkin=2026-11-06&checkout=2026-11-08&mcid=10",
      "price": {
        "base": {
          "accommodation_currency": 1081.49,
          "booker_currency": 1081.49
        },
        "charges": [],
        "display": {
          "accommodation_currency": 1260.52,
          "booker_currency": 1260.52
        },
        "total": {
          "accommodation_currency": 1260.52,
          "booker_currency": 1260.52
        }
      },
      "products": [
        {
          "id": "10507360_95127794_2_0_0",
          "number_of_adults": 2,
          "price": {
            "total": {
              "accommodation_currency": 1260.52,
              "booker_currency": 1260.52
            }
          }
        }
      ],
      "url": "https://www.booking.com/hotel/nl/example.html?aid=956509&checkin=2026-11-06&checkout=2026-11-08&group_adults=2&no_rooms=1"
    }
  ],
  "metadata": {
    "next_page": "eyJwYWdlIjoyfQ=="
  }
}

Keep the accommodation id for the next step.

Try it yourself

2. Get accommodation details

Use this step to retrieve static property information (not availability or pricing). Availability and prices must be retrieved via /accommodations/availability.

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

You must provide at least one of the following parameters:

  • accommodations
  • airport
  • city
  • country
  • region

You can query up to 100 accommodation IDs in a single request.

Example request:

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

Languages

  • You can request multiple languages using IETF language tags (e.g. en-gb, zh-cn).
  • If content is not available in a requested language, English is returned by default.

Using extras

  • The extras array controls which additional datasets are returned.
  • Common extras values include: description, photos, facilities, policies, rooms, bundles, payment.

Example:

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

Check the "Extras" use guide.

Pagination

  • Use rows to control the number of results (max 1000).

Try it yourself

Example response:

The response contains all static information about the selected accommodation, including:

  • Name and translated content.
  • Location and coordinates.
  • Contact details.
  • Facilities and photos (if requested via extras).
  • Policies and payment configuration.
  • Ratings and ranking.
  • URLs for web and app redirects.
{
  "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,
      "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": {
        "web": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509",
        "app": "booking://hotel/10507360?affiliate_id=956509"
      }
  ]
}
  • Use this information to enrich your property listing page (photos, facilities, descriptions, policies, payment methods, etc.).
  • To retrieve live prices and available products, continue with the availability step.

3. Get availability and prices

Use this step to retrieve real-time availability, prices, and extra charges for the selected accommodations.

→ Call the accommodations/availability endpoint using the accommodation id from the previous step.

Mandatory fields: accommodations, booker, checkin, checkout, and guests. Maximum 50 accommodation IDs per request.

Example request:

{
  "accommodations": [10507360],
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2026-11-06",
  "checkout": "2026-11-08",
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "extras": [
    "extra_charges"
  ],
  "filters": {
    "meal_plan": "breakfast_included",
    "cancellation_type": "free_cancellation"
  }
}
More details
  • Use Filters: Apply criteria like meal_plan, cancellation_type, or other product-specific filters.

Example response

The response provides available products, prices, policies, and a recommendation for the best option.

{
  "request_id": "01k2m3js8k6rkgb09vehxcfbjy",
  "data": [
    {
      "id": 10507360,
      "currency": {
        "accommodation": "EUR",
        "booker": "EUR"
      },
      "deep_link_url": "booking://hotel/10507360?affiliate_id=!AFFILIATE_ID!&checkin=2026-02-02&checkout=2026-02-10",
      "products": [
        {
          "id": "1050736003_405384551_2_0_0",
          "bundle": null,
          "deal": {
            "discount_percentage": 3,
            "public_price": 98.2,
            "tags": ["mobile_rate"]
          },
          "maximum_occupancy": {
            "adults": 4,
            "children": null,
            "total": 4
          },
          "number_available": 6,
          "policies": {
            "cancellation": {
              "free_cancellation_until": "2026-10-31T00:00:00+00:00",
              "type": "free_cancellation",
              "schedule": [
                { "from": "now", "price": { "accommodation_currency": 0, "booker_currency": 0 } },
                { "from": "2026-10-31T00:00:00+00:00", "price": { "accommodation_currency": 95.38, "booker_currency": 95.38 } }
              ]
            },
            "meal_plan": {
              "meals": ["breakfast"],
              "plan": "breakfast_included"
            },
            "payment": {
              "timings": ["pay_at_the_property"]
            }
          },
          "price": {
            "base": { "accommodation_currency": 95.38, "booker_currency": 95.38 },
            "chargeable_online": { "accommodation_currency": 95.38, "booker_currency": 95.38 },
            "total": { "accommodation_currency": 95.38, "booker_currency": 95.38 }
          },
          "room": "1050736003"
        }
      ],
      "recommendation": {
        "price": {
          "base": { "accommodation_currency": 95.38, "booker_currency": 95.38 },
          "chargeable_online": { "accommodation_currency": 95.38, "booker_currency": 95.38 },
          "total": { "accommodation_currency": 95.38, "booker_currency": 95.38 }
        },
        "products": [
          {
            "id": "1050736003_405384551_2_0_0",
            "children": [],
            "number_of_adults": 2,
            "price": {
              "base": { "accommodation_currency": 95.38, "booker_currency": 95.38 },
              "chargeable_online": { "accommodation_currency": 95.38, "booker_currency": 95.38 },
              "total": { "accommodation_currency": 95.38, "booker_currency": 95.38 }
            }
          }
        ]
      },
      "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=!AFFILIATE_ID!&checkin=2026-11-06&checkout=2026-11-08&no_rooms=1&group_adults=2"
    }
  ]
}

genius-bulb Use the recommendation field to highlight the best-priced option for your user.

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

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