Searching for Stays

This guide will walk you through the different ways you can search for accommodation with Duffel.

Caution

Before you can get started with this guide, you need to follow some of the basic steps outlined in the Getting Started with Stays guide to set up your account and integration.

There are currently two main ways to search for Stays with Duffel: by location, or by accommodation ID.

If you want to search for availability in all the accommodation provided through Duffel, use the location based search. If you only want to check a short list of known accommodation options, use the accommodation ID based search. Both are described in more detail below.

The following search criteria is required and will apply to both:

number of guests
number of rooms
check in and check out dates

In both cases you will want to use our search endpoint.

Search flow diagram

Search by location

The location-based way of search accepts geographic coordinates (latitude and longitude), and a coverage radius in kilometres. Using a larger radius will yield more results, but it will also be slower.

Your users might not know the geographic coordinates of where they want to stay, so you will probably need to use a geocoding service to map their requested location (address, city name, etc.) to get the latitude and longitude. You can do this using a 3rd party service such as Mapbox, Google or many others. Our agent dashboard uses Mapbox.

A sample request would look like this:

JSON
{
  "location": {
    "radius": 5,
    "geographic_coordinates": {
      "longitude": -0.1416,
      "latitude": 51.5071
    }
  },
  "check_out_date": "2023-06-07",
  "check_in_date": "2023-06-04",
  "guests": [{ "type": "adult" }, { "type": "adult" }],
  "rooms": 1
}

Our endpoint will return a list of search results that match your criteria, each with its own accommodation. It is expected that a search result’s accommodation may not include rooms and rates information provided at this stage in the flow, but you will always know the price of the cheapest rate for each accommodation. To get all the rates and continue on with booking, you will need the search_result_id of this search result.

Search by accommodation ID

If you only want to show your customers a curated shortlist of accommodation options, you might want to use the accommodation ID based search functionality.

For that, you will first need to get the accommodation IDs of the stays you want to offer. You can do this by using the location-based search above, which will also return accommodation IDs in the results. The accommodation IDs will never change, so you only need to perform this step once.

There is a limit to the number of IDs you can search for at a time. If you need to search for more IDs than the limit, you will need to do multiple searches. If this is your use case, consider whether location based search would be more appropriate.

This type of search also has an option that allows you to fetch the rates of these accommodations in the search step. If you want to do that, set fetch_rates to true (it will default to false). This allows you to skip a separate “fetch all rates” step and go straight to getting a quote and then booking. However, you can still perform the steps sequentially like in the location-based search if you prefer.

A sample request would look like this:

JSON
{
  "accommodation": {
    "ids": ["acc_0000AWr2VsUNIF1Vl91xg0"],
    "fetch_rates": true
  },
  "check_out_date": "2023-06-07",
  "check_in_date": "2023-06-04",
  "guests": [{ "type": "adult" }, { "type": "adult" }],
  "rooms": 1
}