How to Use Hotel Search Filters in Quick Builder

Quick Builder supports a range of filters to help users narrow down hotel search results. Filters are passed in the filters object within the search request body. This article covers all available filter options, sorting, pagination, and async search mode.

Filters Object

Add a filters object to your search request body to narrow results:

JSON

{
  "checkin_date": "2026-04-15",
  "checkout_date": "2026-04-18",
  "occupancy": [
    {
      "adults": 2,
      "childs": 0,
      "childages": []
    }
  ],
  "lat": 25.7617,
  "long": -80.1918,
  "countryofresidence": "US",
  "placeid": "placeabc123",
  "filters": {
    "ratings": [
      4,
      5
    ],
    "amenities": [
      "pool",
      "wifi",
      "parking"
    ],
    "name": "Hilton",
    "min_price": 100,
    "max_price": 500,
    "distance": 10
  }
}

Available Filters

Star Ratings

Filter properties by star rating. Pass an array of integers representing the desired star levels.

Parameter	Type	Description
`ratings`	array of numbers	Star ratings to include (e.g., `[3, 4, 5]` for 3-star and above)

JSON

{
  "filters": {
    "ratings": [
      4,
      5
    ]
  }
}

Amenities

Filter by specific amenities. Pass an array of amenity name strings.

Parameter	Type	Description
`amenities`	array of strings	Amenity names to filter by (e.g., `["pool", "wifi", "gym"]`)

JSON

{
  "filters": {
    "amenities": [
      "pool",
      "wifi",
      "parking",
      "breakfast"
    ]
  }
}

Tip: To see what amenities are available for a given search, set amenities=true in the query string of the search endpoint. The response will include amenity data for each property.

Property Name

Search for properties matching a specific name or keyword.

Parameter	Type	Description
`name`	string	Full or partial property name to match

JSON

{
  "filters": {
    "name": "Marriott"
  }
}

Price Range

Filter results by minimum and/or maximum nightly price. Prices are in the currency specified in the query string.

Parameter	Type	Description
`minprice`	number	Minimum price per night
`maxprice`	number	Maximum price per night

JSON

{
  "filters": {
    "min_price": 150,
    "max_price": 400
  }
}

Distance

Limit results to properties within a certain distance from the search coordinates.

Parameter	Type	Description
`distance`	number	Maximum distance in kilometers from the search lat/long

JSON

{
  "filters": {
    "distance": 5
  }
}

Combining Filters

All filters can be combined in a single request. Only properties matching all specified filters are returned.

JSON

{
  "filters": {
    "ratings": [
      4,
      5
    ],
    "amenities": [
      "pool",
      "wifi"
    ],
    "name": "Resort",
    "min_price": 200,
    "max_price": 800,
    "distance": 15
  }
}

Sorting

Control the order of results with the sort array. Each sort object has a key and an order.

Field	Type	Description
`sort[].key`	string	The field to sort by (e.g., `"price"`)
`sort[].order`	string	Sort direction: `"asc"` (ascending) or `"desc"` (descending)

JSON

{
  "sort": [
    {
      "key": "price",
      "order": "asc"
    }
  ]
}

Pagination

Paginate through results using the page and limit query parameters.

Parameter	Type	Description
`page`	number	Page number, starting at 1
`limit`	number	Number of results per page (max 50)

POST /hotels/api/v2/properties?currency=USD&page=2&limit=25&amenities=true

To iterate through all results:

Start with page=1.
Check the total count in the response.
Increment page until you have retrieved all results.

Async Search Mode

When is_async is set to true, the search returns results as they become available rather than waiting for all suppliers to respond.

JSON

{
  "is_async": true
}

How Async Mode Works

Send the search request with is_async: true.
The response may have status: "in_progress" with partial results.
Re-send the same request with the same x-correlation-id to get updated results.
Continue polling until status changes to "success", indicating all results are in.

When to Use Async Mode

Scenario	Recommended Mode
Fast initial results are acceptable	Async (`isasync: true`)
Need all results before displaying	Sync (`isasync: false`)
Real-time search UI with loading indicators	Async (`is_async: true`)

Complete Example

A fully configured search request with filters, sorting, and pagination:

POST /hotels/api/v2/properties?currency=USD&page=1&limit=50&amenities=true

JSON

{
  "checkin_date": "2026-04-15",
  "checkout_date": "2026-04-18",
  "occupancy": [
    {
      "adults": 2,
      "childs": 1,
      "childages": [
        8
      ]
    }
  ],
  "lat": 25.7617,
  "long": -80.1918,
  "countryofresidence": "US",
  "placeid": "placeabc123",
  "radius": 25,
  "sort": [
    {
      "key": "price",
      "order": "asc"
    }
  ],
  "filters": {
    "ratings": [
      4,
      5
    ],
    "amenities": [
      "pool",
      "wifi"
    ],
    "min_price": 150,
    "max_price": 600,
    "distance": 20
  },
  "is_async": false
}

Next Steps

Check the Quick Builder FAQ for answers to common integration questions.