Retrieve accommodation details v3.2

Understand the accommodations/details endpoint, the required fields for each request, best practices and use cases.

→ Use the /accommodations/details endpoint to retrieve information about accommodation properties.

• You can request details for accommodation IDs, search by a location, or combine a location with filters. Availability and pricing are returned by other endpoints.
• The response can include property information such as its name, type, location, check-in and check-out times, and rating.
• Use the extras field to request additional information such as photos, policies, facilities, or rooms.

To obtain details for a specific property, you must provide at least one ID of accommodations, airport, city, country, or region.

• If using accommodation IDs in the request, you can get them from the /accommodations/search response.

Example:

{
  "accommodations": [
    10004,
    10507360
  ],
  "extras": [
    "description",
    "photos",
    "rooms"
  ],
  "languages": [
    "en-gb"
  ]
}

• If using a location ID in the request, you can get it from the /common/locations endpoints.

Example:

{
  "city": -2140479,
  "accommodation_types": [
    204
  ],
  "accommodation_facilities": [
    5
  ],
  "extras": [
    "facilities"
  ],
  "languages": [
    "en-gb"
  ],
  "rows": 100
}

Use extras to request additional property or room data. Pass one or more values from the schema's supported list.

For example, to request property facilities and photos:

{
  "accommodations": [
    10004
  ],
  "extras": [
    "facilities",
    "photos"
  ],
  "languages": [
    "en-gb"
  ]
}

Include description as extras in the request to receive:

• host type - Indicating whether the host is private, professional, or unknown.
• important information - Any relevant details the property wants to share like those regarding the booking conditions, or any other.
• license number
• text - Brief overall of the property main characteristics.
• trader - The property personal details as required by the Digital Services Act(“DSA”).

Example:

{
  "description": {
    "host_type": "professional",
    "important_information": {
      "en-gb": "The credit card that has been used to book a non-refundable rate, will be charged on the day of booking and needs to be presented upon check-in..."
    },
    "license_numbers": [],
    "text": {
      "en-gb": "The Demand API Sandbox Hotel Orion features elegant accommodation alongside the famous Keizersgracht canal, around the corner from the Anne Frank House."
    },
    "trader": {
      "address": {
        "address_line": "Keizersgracht 164",
        "city": "Amsterdam",
        "country": "nl",
        "post_code": "1015CZ"
      },
      "email": "info@hoteltoren.nl",
      "name": "Demand API Sandbox Hotel Orion",
      "registration_number": "1233454645",
      "telephone": "+3112356456",
      "trade_register": "KVK",
      "trader_verified": true
    }
  }
}

When the facilities field is included in the extras field, the accommodations/details response includes a list of available facilities, each with an ID and attributes, such as whether the facility requires payment or is located off-site.

It also includes the "facility_details" object, depicting detailed information about specific key facilities:

Example of response:

{
  "facilities": [
    {
      "id": 21,
      "attributes": [
        "paid"
      ]
    },
    {
      "id": 75,
      "attributes": [
        "offsite"
      ]
    }
  ],
  "facility_details": {
    "internet_facility": {
      "price": 0,
      "charge_mode": "free",
      "coverage": "entire_property",
      "connection_type": "wifi"
    },
    "parking_facilities": [
      {
        "price": 0,
        "charge_mode": "charges_may_apply",
        "type": "public",
        "location": "nearby",
        "reservation": "not_possible"
      }
    ],
    "restaurant_facilities": [
      {
        "name": "Restaurant Oasis",
        "status": "open",
        "guests_only": false,
        "accept_reservations": false
      }
    ],
    "swimming_pool_facilities": []
  }
}

• To identify the facility with a specific id, use the accommodations/constants endpoint. This will retrieve the list of facilities id:

Example response for facility IDs 21 and 75:

[
  {
    "id": 21,
    "name": {
      "en-gb": "Babysitting/child services"
    },
    "facility_type": 3
  },
  {
    "id": 75,
    "name": {
      "en-gb": "Car hire"
    },
    "facility_type": 3
  }
]

Include payment as extra in the request, to receive payment methods and timings supported by the property, as well as CVC requirement indicators.

Example of response including payment:

{
  "request_id": "01jmmjn081ta8d5a0kt83sgg1d",
  "data": [
    {
      "id": 10507360,
      "name": {
        "en-gb": "Demand API Sandbox Hotel Orion"
      },
      "accommodation_type": 204,
      "booker_address_required": false,
      "brands": [],
      "checkin_checkout_times": {...},
      "contacts": {
        "general": {...},
        "reservations": null
      },
      "currency": "EUR",
      "deep_link_url": "booking://hotel/10507360?affiliate_id=956509",
      "is_work_friendly": false,
      "location": {...},
      "meal_prices": {
        "breakfast": 12,
        "lunch": null,
        "dinner": null
      },
      "number_of_rooms": 300,
      "payment": {
        "amex_cvc_required": false,
        "cvc_required": false,
        "domestic_no_cc": false,
        "methods": {
          "cards": [
            1,
            2,
            3
          ],
          "cash": true,
          "virtual_cards": [
            1,
            2,
            3
          ]
        },
        "timings": [
          "pay_at_the_property",
          "pay_online_later",
          "pay_online_now"
        ]
      },
      "price_category": "",
      "programmes": {
        "travel_proud": false,
        "sustainable_offerings": {
          "certifications": [],
        }
      },
      "ranking": 4066029,
      "rating": {
        "number_of_reviews": 0,
        "preferred": true,
        "review_score": null,
        "stars": 5,
        "stars_type": "official"
      },
      "spoken_languages": [
        "en-gb"
      ],
      "themes": [],
      "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509"
    }
  ]
}

Request photos to receive property photo URLs in available sizes, with tags and an indication of the main photo where supplied. The number of photos returned may be limited by contract, and photos are not returned in a particular order. Room-level photos require both rooms and photos.

Request policies for property rules and constraints. The response can include cot and extra bed prices, minimum guest age, minimum and maximum check-in ages, pet policies, and damage policies. Use these details when explaining property conditions to travellers.

Request rooms for the property's room types or accommodation units.

• A room can include a translated name and description, bed options, room attributes, facilities, maximum occupancy, internal layout, photos, room type, and size.
• Room facilities require rooms and facilities; room photos require rooms and photos.
• Occupancy and bed details describe room options and limits. They do not indicate current availability.

A successful response contains a data array.

• Each item represents an accommodation.
• The returned data is static property information; it does not indicate availability or provide a price for a stay.

The response can include fields such as:

This example shows the response structure, including the current url object and pagination metadata. Optional fields and values vary by property.

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 10004,
      "accommodation_status": "open",
      "accommodation_type": 204,
      "booker_address_required": false,
      "brands": [],
      "checkin_checkout_times": {
        "checkin_from": "15:00:00",
        "checkin_to": null,
        "checkout_from": "07:00:00",
        "checkout_to": "12:00:00"
      },
      "currency": "EUR",
      "is_genius": true,
      "location": {
        "address": {
          "en-us": "Keizersgracht 164"
        },
        "city": -2140479,
        "coordinates": {
          "latitude": 52.375858,
          "longitude": 4.886006
        },
        "country": "nl",
        "districts": [
          145,
          3024
        ],
        "postal_code": "1015 CZ",
        "regions": [
          1010,
          2776
        ]
      },
      "long_stay_friendly": false,
      "meal_prices": {
        "breakfast": 20,
        "dinner": null,
        "lunch": null
      },
      "name": {
        "en-us": "The Pavilions Amsterdam, The Toren"
      },
      "number_of_rooms": 11,
      "payment": {
        "amex_cvc_required": false,
        "cvc_required": true,
        "domestic_no_cc": false,
        "methods": {
          "cash": true,
          "cards": [
            1,
            2,
            3
          ],
          "virtual_cards": [
            1,
            2,
            3
          ]
        },
        "timings": [
          "pay_at_the_property"
        ]
      },
      "price_category": "$$$$",
      "ranking": 123456,
      "rating": {
        "number_of_reviews": 930,
        "preferred": true,
        "review_score": 9,
        "stars": 4,
        "stars_type": "official"
      },
      "spoken_languages": [
        "de",
        "en-gb",
        "fr",
        "nl"
      ],
      "themes": [
        6
      ],
      "url": {
        "web": "https://www.booking.com/hotel/nl/toren.html?affiliate_id=!AFFILIATE_ID!",
        "app": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!"
      },
      "work_friendly": false
    }
  ],
  "metadata": {
    "next_page": null
  }
}

In the Demand API, number_of_rooms is an approximate count of bookable rooms or accommodation units configured in Booking.com.

• It does not show current availability and does not necessarily match the property's physical room count.
• For holiday homes and similar private rentals, the entire property may be one bookable unit, so number_of_rooms can be 1 even if the unit has multiple bedrooms.

It is calculated as the sum of the “Number of this type” quantities configured for each Booking.com room type.

Important:

• It is not a count of unique room IDs.

• It is not an availability indicator.

• It does not necessarily represent the property’s total physical room count.

• It may be lower than the physical room count if not all rooms are configured in Booking.com.

• You should treat number_of_rooms as an inventory size indicator (bookable units) (for example, for filtering, bucketing, or ranking properties), not as a reconciled operational or financial source of truth.

For properties that include additional unmapped third-party inventory (TPI) rooms, the total number of rooms returned in the rooms payload may be higher than the value shown in number_of_rooms.

• This is expected behaviour. Unmapped TPI rooms are intentionally excluded from number_of_rooms to avoid double-counting or inflating the perceived property size.

If "number_of_rooms" is 0, the property has no rooms configured in the Booking.com internal system.

This can occur when:

• The property is active but room configuration has not yet been completed.
• Only unmapped third-party inventory (TPI) rooms exist for the property.

In such cases, room data may still appear in the rooms payload if TPI inventory is available.

A property has 4 physical rooms in total.

In the Booking.com internal system:

• 2 rooms are configured using the “Number of this type” setting.
• 2 additional rooms are supplied as unmapped TPI inventory.

In the /accommodations/details response:

"number_of_rooms": 2,

However, the rooms payload may return 4 room entries (2 mapped + 2 unmapped).

This does not indicate a data inconsistency.

• number_of_rooms reflects only the rooms configured.
• The rooms array reflects all room types returned in the response, including unmapped TPI rooms.

For holiday homes, villas, apartments, chalets, and other private rentals: number_of_rooms may not represent the property's internal bedroom count.

In these cases, the property is often sold as a single bookable unit. As a result:

• number_of_rooms may be 1, because there is one bookable accommodation unit available for reservation.
• The property's internal layout (for example, the number of bedrooms) is represented separately in the room and unit details.

For example, a holiday home with 3 bedrooms may return:

"number_of_rooms": 1

This does not mean the property has only one bedroom. It means the entire property is offered as a single bookable unit.

When you need information about the property's internal room layout or sleeping arrangements, always rely on the room and unit details returned in the response rather than number_of_rooms.