ACCOMMODATION
/
Quick guide
Last updated

Accommodation quick guide

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

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

⏱️ Estimated time to complete: 15 - 30 minutes

  • Purpose: Fast setup to search, get property details and retrieve availability/prices.
  • When to use: You’re not familiar with the Accommodation APIs and want to try it quickly.
  • You´ll learn how to:
    1. Search for accommodation.
    2. Look at results and property details.
    3. Get availability and prices.
    4. Order options.
  • Code samples: Minimal, only required fields.

Before you start

Before you start, make sure you’ve completed the prerequisites. You’ll need:

✓ A valid API key token.
✓ Your X-Affiliate-Id
✓ Open the try out console.
✓ Use the sandbox environment.

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:

{
  "city": -2140479,
  "booker": {
    "country": "nl",
    "platform": "mobile"
  },
  "checkin": "2025-11-06",
  "checkout": "2025-11-08",
  "guests": {
    "number_of_rooms": 1,
    "number_of_adults": 2
  }
}
More details

See the accommodation search guide for examples and tips on creating search requests.

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.

In this example, the Demand API sandbox Onion hotel.

{
  "id": 10507360,
  "currency": "EUR",
  "price": {
    "book": 184.00,
    "total": 184.00
  },
  "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509&checkin=2023-11-06&checkout=2023-11-08&no_rooms=1&group_adults=2&mcid=10"
}

Keep the accommodation id for the next step.

→ Try it yourself

2. Get accommodation details

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

Example request:

{
  "accommodations": [
      10507360
  ],
  "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 the accommodations/availability endpoint with the same traveller criteria.

Example request:


{
  "accommodation": 10507360,
  "booker": { "country": "nl", "platform": "mobile" },
  "checkin": "2025-11-06",
  "checkout": "2025-11-08",
  "guests": { "number_of_rooms": 1, "number_of_adults": 2 }
}

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 can change between search and availability calls — always confirm before booking.

→ (Try it yourself)

4. Handle the booking

Choose your integration type:

  • Search and look → Redirect to the url in the availability response.

  • Search, look and book → Book within your application:

    1. Use /orders/preview to confirm price, policies, and payment options.
    2. Use /orders/create to complete the booking within your application.

For Search, look and book, you must have:

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

See the Orders creation guide to learn how to proceed the booking.

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.
  • Cache 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!

  • See the Tutorial for full step by step guide.
  • Refer to the Orders and payments guides to make your first order.
Previous page
Next page