ACCOMMODATION
/
Look at details
Last updated

Retrieve accommodation details

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

→ Use the /accommodations/details endpoint to retrieve information about a specific property, or a list of properties.

This data is typically displayed on the accommodation page once it has been returned in the search results, allowing travellers to learn more about the property before proceeding with the booking process.

Create the request body

To obtain details for a specific property:

  1. Access the response from the accommodations/search.

  2. Copy the unique identifier (id) of the accommodation you wish to retrieve details for.

  3. Use the accommodation id in your request to the /accommodations/details endpoint.

  • You can use a single id to retrieve details for a specific property.

    Example:

{
  "accommodations": [
    445243
  ],
  "extras": [
    "description",
  ],
  "languages": [
    "en-gb"
  ]
}
  • Alternatively, you can request details for multiple properties by providing a list of ids. This list could be:
    • Derived from the response to a previous search request.
    • A specific list curated for a particular purpose, such as promoting a selection of properties. Example: A promotion on your search page for a specific set of hotels near a particular beach.

Example:

{
 "accommodations": [
   10507360,
   445243
}

Optional extras

You can optionally include additional fields to narrow down the response and request specific information about the properties:

Extra field
Use it to...
description
  • Retrieve both the license number and trader information, which is needed for EEA travellers for Digital Services Act (“DSA”) compliance.
  • See any important information shared by the property.
facilities
  • Get a list of available facilities, including their attributes that indicate whether they require payment.
  • See further details about Internet, Parking, Restaurant and Swimming pool facilites.
paymentView the payment options supported by this property: the payment methods, timings, whether cvc or amex_cvc is required.
photosRetrieve the URLs to different size photos of the property and the main photo used to identify the property.
policiesCheck the property policies around cots and extra beds, pets, minimum guest age (useful to identify adults only hotels)
roomsRetrieve room details such as bed configurations, maximum occupancy, size, name, and whether is smoking or non-smoking.

Example :

{
  "extras": [
    "facilities",
    "photos"
  ]
}

Example response

The returned response will include details about the selected accommodation including the name, accommodation type, checkin-checkout times, links, contact, location, meal prices, total number of rooms, etc.

{
  "request_id": "01jn6g0dxqexafjp8mm0nqmfjz",
  "data": [
    {
      "id": 10507360,
      "name": {
        "en-gb": "Demand API Sandbox Hotel Orion"
      },
      "accommodation_type": 204,
      "booker_address_required": false,
      "brands": [],
      "checkin_checkout_times": {...},
      "contacts": {...},
        "reservations": null
      },
      "currency": "EUR",
      "deep_link_url": "booking://hotel/10507360?affiliate_id=956509",
      "is_work_friendly": false,
      "location": {
        "address": {
          "en-gb": "Oosterdoksstraat 154"
        },
        "city": -2140479,
        "coordinates": {
          "latitude": 52.376388,
          "longitude": 4.90919
        },
        "country": "nl",
        "districts": [...],
        "postal_code": "1011 DL",
        "regions": [...]
      },
      "meal_prices": {
        "breakfast": 12,
        "lunch": null,
        "dinner": null
      },
      "number_of_rooms": 300,
      "price_category": "",
      "programmes": {...}
      },
      "ranking": 4108446,
      "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"
    }
  ]
}

Extras information

Description

When the description field is included in the extras parameter, the accommodations/details response returns:

  • 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”).
    • Including the trader_verified parameter - Refer to the DSA compliance guide for more details on how to interpret this value.

Make sure you follow the DSA recommendations when displaying this sort of information in your platform.

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
    }
  }
}

Facilities

When the facilities field is included in the extras parameter, 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:

InternetDisplays information about the internet facilities available at the accommodation, including the type of connection and the charging model.
ParkingRetrieves details about the parking facilities available at the accommodation, including pricing, type, location, and reservation requirements.
RestaurantReturns details about the restaurants available at the accommodation including: restaurant name, restaurant status, available for guests only and reservations requirement.
Swimming poolInformation about the swimming pools available at the accommodation including: their type, payment options and age restrictions.

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": []
  }
}

Using constants

  • 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
  }
]

Payment

When including the "payment" extra in the request, the response provides details about the supported payment method and timing.

Example:

{
  "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": {
          "chain_programmes": [],
          "certifications": [],
          "practices": []
        }
      },
      "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"
    }
  ]
}
Curious to know more?
  • For detailed instructions on how to manage trader information for EEA travellers, refer to the DSA compliance guide.
  • Refer to the Payments section for more details on how to interpret the "payment" extras details.
Previous page
Next page