curl "$UNIFYSTAYS_BASE_URL/hotels/filters?place_id=2930267" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
{
"success": true,
"message": "Filters fetched successfully",
"data": {
"place_id": 1050645,
"total_hotels": 12899,
"stars": [
{ "value": 5, "label": "5★", "count": 310 },
{ "value": 4, "label": "4★", "count": 2204 }
],
"price_range": { "min_usd_cents": 6100, "max_usd_cents": 48200 },
"property_types": [{ "value": "Hotel", "label": "Hotel", "count": 9000 }],
"chains": [{ "value": 12, "label": "Baron Group", "count": 3 }],
"facilities": [{ "value": 107, "label": "Free WiFi", "count": 8000 }],
"cached_until": "2026-09-27T00:00:00.000Z"
}
}
Search & hotels
Get Hotel Filters
Retrieve the filter options and counts for a place, to build a filter drawer before searching.
GET
/
hotels
/
filters
curl "$UNIFYSTAYS_BASE_URL/hotels/filters?place_id=2930267" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
{
"success": true,
"message": "Filters fetched successfully",
"data": {
"place_id": 1050645,
"total_hotels": 12899,
"stars": [
{ "value": 5, "label": "5★", "count": 310 },
{ "value": 4, "label": "4★", "count": 2204 }
],
"price_range": { "min_usd_cents": 6100, "max_usd_cents": 48200 },
"property_types": [{ "value": "Hotel", "label": "Hotel", "count": 9000 }],
"chains": [{ "value": 12, "label": "Baron Group", "count": 3 }],
"facilities": [{ "value": 107, "label": "Free WiFi", "count": 8000 }],
"cached_until": "2026-09-27T00:00:00.000Z"
}
}
Call this endpoint after the guest picks a destination and before (or alongside) Search Hotels. It returns the filter options that exist for that destination, with the number of hotels behind each one: star ratings, a typical price range, property types, hotel chains and facilities. Use it to build a filter drawer that only offers choices that will return hotels.
Other fields of the response:
The range shows typical prices and leaves out extreme outliers, so it is a good slider scale but not a guarantee. Price filters stay in USD even if your account receives EUR prices in search results.
Send exactly one of
place_id or hotel_id. Sending both or neither
returns HTTP 400. The payload is cached on the server for 24 hours and
data.cached_until tells you when it will be rebuilt.Request example
curl "$UNIFYSTAYS_BASE_URL/hotels/filters?place_id=2930267" \
-H "x-api-key: $UNIFYSTAYS_API_KEY"
| Parameter | What it means | How to use it |
|---|---|---|
place_id | Place ID from Destination Autocomplete (type = place). Counts cover every searchable hotel in the place. | Use for a place search. |
hotel_id | Hotel ID from autocomplete (type = hotel), as a string. The API resolves the hotel’s place and returns facets for that whole place, not for the one hotel. An unknown hotel returns 404. | Use when the guest searched a single hotel and you still want the filter set of its area. |
Response example
{
"success": true,
"message": "Filters fetched successfully",
"data": {
"place_id": 1050645,
"total_hotels": 12899,
"stars": [
{ "value": 5, "label": "5★", "count": 310 },
{ "value": 4, "label": "4★", "count": 2204 }
],
"price_range": { "min_usd_cents": 6100, "max_usd_cents": 48200 },
"property_types": [{ "value": "Hotel", "label": "Hotel", "count": 9000 }],
"chains": [{ "value": 12, "label": "Baron Group", "count": 3 }],
"facilities": [{ "value": 107, "label": "Free WiFi", "count": 8000 }],
"cached_until": "2026-09-27T00:00:00.000Z"
}
}
From filter value to search field
Each option has the same shape:value (send this), label (show this) and count (hotels with it).
| Response field | Search request field | What to send | Behaviour in search |
|---|---|---|---|
stars[].value | star_ratings | Array of numbers 1 to 5. | A hotel matches if it has any chosen rating. |
price_range | price_min_usd_cents, price_max_usd_cents | Whole-stay totals in USD cents (see below). | Keeps hotels whose typical price falls in the range. |
property_types[].value | property_types | Array of strings, exactly as returned. | A hotel matches if it has any chosen type. |
chains[].value | chain_ids | Array of numbers. | A hotel matches if it belongs to any chosen chain. |
facilities[].value | facility_ids | Array of numbers. | A hotel must have all chosen facilities. |
| Field | What it means | How to use it |
|---|---|---|
data.place_id | The place the counts were computed for. | Equals your place_id, or the hotel’s place when you sent hotel_id. |
data.total_hotels | Searchable hotels in the place (at least one supplier mapping). | Show as a results hint. |
data.cached_until | ISO time when the payload can change. | Cache until then; re-fetch afterwards. |
Price range is per night
price_range is the typical price per night for one standard room
(about 2 adults), in USD cents. The search filters are totals for the whole
stay across all nights and rooms. Before sending the slider values, multiply
by the number of nights and rooms in the guest’s search. For example, a
max_usd_cents of 48200 for a 3-night, 1-room stay is about 144600 as
price_max_usd_cents.Behaviour to know
- Counts describe the catalogue, not live availability or prices for the guest’s dates. A filter can still leave a hotel whose price turns out to be unavailable.
- Counts do not change when other filters are selected. Do not grey out options based on them.
- Lists are limited: up to 30 property types, 50 chains and 50 facilities (most common first). Star options cover ratings 1 to 5 only, so unrated hotels have no star option.
- Counts cover hotels with at least one supplier mapping, the base set a search starts from. A search for your organization can return fewer, for example when your enabled suppliers do not cover a hotel.
- The cursor of a search is tied to its filters: changing a filter means starting again from the first page.
hotel_name (free text, case-insensitive “contains”) and hotel_ids (restrict to specific hotels).
Next step
Send the chosen values to Search Hotels, then use fresh room options and prebook before checkout. The OpenAPI section below lists every parameter and response field.Authorizations
Environment-specific API key created in the Unifystays portal
Headers
Hotel API contract version. Optional: 2 is the current version and the default.
Available options:
2 ISO 4217 currency for display amounts (display_ledger, display_amount, commercial_display). Optional: defaults to your organization's display currency, USD unless configured. Read pricing.display_currency in the response.
Required string length:
3Example:
"EUR"
Query Parameters
Place ID from destination autocomplete (type=place). Facets cover every searchable hotel in the place (e.g. all of Bali). Send exactly one of place_id or hotel_id; sending both or neither returns 400.
Example:
2930267
Hotel ID from destination autocomplete (type=hotel), as a string. The server resolves the hotel's pricing place and returns facets for that whole place, not for the single hotel. Unknown hotel returns 404.
Example:
"1892345"