Filtering and pagination

Learn how to filter your search results and organise payload with pagination.

Filters

Demand API offers a range of filters to help you refine accommodation search results based on various criteria. Some of the filters include location, accommodation type, price, guest reviews, and proximity to landmarks.

You can also filter properties by specific attributes such as availability of facilities like parking, Wi-Fi, or swimming pools.

To apply filters, include specific query parameters in your accommodation/search request.

Accommodation type filter

You can search for specific type of properties:

• Hotel: Standard hotel accommodations.
• Apartment: Includes serviced apartments and flats for more home-like stays.
• Hostel: Dormitory-style accommodations ideal for budget travellers.
• Bed and breakfast (B&B): Smaller properties offering personalised services.
• Villa: Standalone houses or luxury vacation homes.
• Resort: Larger properties with various on-site amenities, catering to vacations.
• Guest house: Smaller, often family-run, establishments.

You can use one of these filters passing the property_types id. For example 204 for hotels, 206 for resorts and, 213 for villas, etc.

→ Get the necessary ids from the accommodation/constants

Example: Search for hotels in Amsterdam:

{
"coordinates": {
"latitude": 52.378281,
"longitude": 4.900070,
"radius": 1
},
"accommodation_types": [204],
"booker": {
"platform": "desktop",
"country": "nl"
},
"currency": "EUR",
"checkin": "2025-03-09",
"checkout": "2025-03-10",
"guests": {
"number_of_rooms": 1,
"number_of_adults": 2
},
"sort": {
"by": "distance",
"direction": "descending"
}
}

To include multiple types, list them in the accommodation_types array (e.g. ["206", "213"]).

Cancellation policy filters

You can filter properties that offer free cancellation or specific payment conditions.

• free_cancellation: Filter accommodations that offer free cancellation up to a certain period before check-in. This is useful for travellers looking for flexibility in case their plans change.
• no_refund: Accommodations that do not offer refunds once booked. Non-flexible, cheaper rates that do not offer refunds.

Example:

{
"checkin_date": "2024-11-10",
"checkout_date": "2024-11-15",
"location": {
"city": "-2140479"
},
"cancellation_policy": {
"free_cancellation": true
},
"guests": {
"number_of_rooms": 1,
"number_of_adults": 2
}
}

Chains-brand filters

You can specify filters for well-known accommodation chains like "Marriott," "Hilton," "Radisson," or others.

→ Use the accommodation/chains endpoint with empty body to get the full list of brand ids. Select the one you need for your search request.

Example:

{
"checkin": "2024-11-10",
"checkout": "2024-11-15",
"city": "-2140479"
},
"chains": [
"19"
],
"guests": {
"number_of_rooms": 1,
"number_of_adults": 2
}
}

• In this example, "19" represents the "Radisson Hotel Group" brand.
• You can customise this filter to include multiple brands if needed (e.g., "19", "22").

Distance filters

Filter based on distance:

• To Landmarks: Users can filter accommodations by specifying a distance range from popular landmarks (e.g., airports, museums, etc.)

• From City Center: You can narrow down accommodations to those within a certain distance from the central part of a city.

• To Coordinates: This allows filtering based on a given latitude and longitude, enabling searches for properties near a particular spot on the map. You can get the coordinates by using:

  • locations/landmarks for landmarks.
  • /accommodations/details for an accommodation.
  • location/country for countries.

Example: This query filters properties within a 5 km radius of the provided latitude and longitude (Amsterdam in this case).

{
"coordinates": {
"latitude": 52.3676,
"longitude": 4.9041,
"radius": 5
},
"booker": {
"platform": "desktop",
"country": "nl"
},
"currency": "EUR",
"checkin": "2025-03-09",
"checkout": "2025-03-10",
"guests": {
"number_of_rooms": 1,
"number_of_adults": 2
}
}

Adjust the latitude, longitude, and radius as needed to search for different areas or distances​.

Facilities filters

This filter is based on the availability of facilities in the accommodation. Some accommodation_facilities are:

• Wi-Fi: Search for properties that offer free or paid Wi-Fi.
• Parking: Filter for accommodations with available parking facilities.
• Pool: Allows users to search for properties that have swimming pools.
• Air conditioning: Filter based on whether the rooms have air conditioning.
• Pet-Friendly: Locate properties that allow pets.
• Kitchen facilities: Helps to find accommodations with kitchen or kitchenette options.
• Fitness center: Search for accommodations with on-site gym facilities.
• Accessibility: Filters that allow searches for properties with amenities that cater to guests with disabilities.

→ Get facility IDs from accommodation/constants.

Location filters

You can filter by geographic locations using parameters like:

→ Retrieve the needed IDs from common/location.

Payment timing filters

You can restrict results to include properties that support only pay at the property (pay_at_the_property) and/or online payments (including pay_now or pay_later ).

Example of search request for pay at property timing:

{    
"coordinates": {  
    "latitude": 52.378281,  
    "longitude": 4.900070,  
    "radius": 100  
},  
  
"booker": {  
    "platform": "desktop",  
    "country": "nl"  
},  
"currency": "EUR",  
"checkin": "2024-12-12",  
"checkout": "2024-12-13",  
"extras": [  
    "products"  
],  
"guests": {  
    "allocation": [  
        {  
            "number_of_adults": 2  
        }  
    ],  
    "number_of_rooms": 1,  
    "number_of_adults": 2  
},  
"payment": {  
    "timing": "pay_at_the_property"  
}  
}

Price filters

Filter properties based on their price range using:

• min_price: Lower limit price per night. Only accommodations costing more than this specified amount will be returned.
• max_price: Sets an upper limit for the price per night, ensuring that results do not exceed a particular budget.
  • You can specify both minimum and maximum prices together to define a specific range, such as 100 Eur to 200 Eur per night.
  • If specified, will return only results where the price per night falls in the specified range (inclusive).

Example for accommodation in Amsterdam that cost between 100 Eur and 200 Eur per night, returning the prices in EUR.

{ 
"currency": "EUR",
"checkin": "2024-11-10",
"checkout": "2024-11-15",
"city": "-2140479",
},
"price_filter": {
"min_price": 100,
"max_price": 200
},

Rating and review filters

Filter based on guest reviews and ratings.

• min_review_score: Allows users to specify a minimum review score (e.g., 7 out of 10), so that only accommodations with ratings above this threshold are included in the results.
• review stars: Filters properties based on the number of given stars, ensuring that only those with sufficient stars are shown in the range of 1 to 5.

Example:

{
"booker": {
  "country": "nl",
  "platform": "desktop"
},
"checkin": "2024-11-10",
"checkout": "2024-11-15",
"city": "-2140479"
},
"review_filter": {
"min_score": 8,
"review_count": 50
},
"sort": "review_score_desc",
"guests": {
  "number_of_adults": 2,
  "number_of_rooms": 1
}

In this example, the request is configured to search for accommodations in Amsterdam (city id -2140479) with a minimum review score of 8 out of 10, and with at least 50 reviews.

The results are sorted to prioritise properties with the highest review scores, helping users quickly find the best-rated accommodations.

Filters in accommodation and products

The following tables summarise some other filters, some of which work on the accommodation level, and some on the product level.

Accommodation-level filters

Product-level filters

You can use these filters when looking at a specific property availability

Pagination

Pagination in our API is handled using standard mechanisms such as page and rows parameters.

• page: This parameter indicates the page number of the result set, and it can be used to retrieve subsequent pages.
• rows: This parameter specifies the maximum number of results returned per page. If not specified, it returns 100 items by default.

Pagination allows you to handle larger data sets by fetching smaller, more manageable chunks, improving both performance and user experience.

Next page token

When you make an API call, the response includes a next_page token.

• Use this token to fetch additional results without needing to specify certain parameters again, such as languages, which will be inherited from the initial request.
• If the next_page field is absent, it indicates there are no more results available.

Example:

{ "page":"eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJMT0NBVElPTlNfQ09VTlRSSUVTIiwiZXhwIjoxNTY4OTA2NDY4LCJwIjp7ImluZGV4IjoiaWUiLCJsYW5ndWFnZXMiOlsiZnIiLCJwdC1wdCJdfX0.tGDtqCszB-2f_4Id8g40nMA8tZQLFwFlLMr6eayVkCg"
}

By leveraging pagination, you can efficiently handle large volumes of data across various endpoints, such as accommodation availability, car rentals, and location queries.

Pagination for car rentals

For cars/search endpoints, pagination works similarly using the next_page token, with some differences:

The pagination fields are set under a "metadata" object:

• page: This parameter indicates the page number of the result set, and it can be used to retrieve subsequent pages.

• maximum_results: Sets the maximum number of results per page, defaulting to 20 if not specified.

  ],
  "metadata": {
  "next_page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoibmwifSwiY3VycmVuY3kiOiJFVVIiLCJkcml2ZXIiOnsiYWdlIjozNn0sInJvdXRlIjp7ImRyb3BvZmYiOnsiZGF0ZXRpbWUiOiIyMDI0LTEwLTE4VDEwOjAwOjAwIiwibG9jYXRpb24iOnsiYWlycG9ydCI6IkFNUyJ9fSwicGlja3VwIjp7ImRhdGV0aW1lIjoiMjAyNC0xMC0xNFQxMDowMDowMCIsImxvY2F0aW9uIjp7ImFpcnBvcnQiOiJBTVMifX19LCJvZmZzZXQiOjEwMH0sImF1ZCI6Ii9jYXJzL3NlYXJjaCIsImV4cCI6MTcyODY0Mjg0N30._KTqz3EgudUa3z-tReI7eP4D7ZdoCKd9xYIMhXvdHEA",
  "maximum_results": 160
  }
  

Sorting

Use "sort.by" option to organise the results on each page based on various criteria.

Available sorting options include:

• Distance: When ordering by distance please make sure to specify the latitude and longitude.
• Price.
• Review score.
• Stars.

You can also set the direction of results, by default is always "descending".

},
"sort": {
"by": "distance",
"direction": "descending"
}

Best practices

Combine filters with pagination parameters (page and rows) to effectively navigate through large datasets.

By combining these filters in your API requests, you can refine the search results to match specific criteria.