Hotel search

Search live availability in two steps: a city search lists hotels with a lead-in price, then a hotel search lists that property's bookable rates. You pick a rate, confirm it, and turn it into an order.

Search availability

POST/v3/HAPI/hotels/searches

Requires the hotels:read scope.

Body

Field	Type	Required	Description
`check_in`	string	Yes	Check-in date, `YYYY-MM-DD`.
`check_out`	string	Yes	Check-out date, after check-in.
`city_id`	integer	*	Destination city id → a city search. Provide exactly one of `city_id` or `hotel_id`.
`hotel_id`	integer	*	A single hotel id (from a city search result) → a hotel search with bookable rates.
`occupancies`	array	Yes	One entry per room.
`occupancies[].adults`	integer	Yes	Adults in the room, 1–8.
`occupancies[].children`	array	No	Child ages, e.g. `[4, 9]`.
`sort`	string	No	City mode only: a sort `id` from the response `sorts` (e.g. `price`, `stars_desc`, `review_score`).
`filters`	object	No	City mode only: facet `key` → array of option `value`s — see below.
`page`, `page_size`	integer	No	Paging (page_size up to 200).

Filtering & sorting a city search

Filtering is facet-based and applied across the whole city result (not just one page). A city response includes:

facets — the filter groups available for this destination and dates. Each group has a key, a title, a type, and options of {value, name, count}. Groups include stars, review_score, meals, facility (Free WiFi, Swimming pool, …), room_facility, property_type, district, chain, free_cancellation, and more — all listed below.
sorts — the sort options, each {id, name} (e.g. price, stars_desc, review_score, distance, popularity).
total — total matching properties, and pagination for the pages.

To filter, send filters as a map of facet key → array of option values, and sort as a sort id:

curl -X POST https://api.hermeseus.com/v3/HAPI/hotels/searches \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "check_in": "2026-11-14",
    "check_out": "2026-11-16",
    "city_id": 1019782831,
    "occupancies": [ { "adults": 2 } ],
    "sort": "review_score",
    "filters": {
      "stars": [4, 5],
      "facility": [107, 433],
      "meals": ["breakfast"],
      "free_cancellation": [true]
    }
  }'

Each facet group is { key, title, type, options: [{ value, name, count }] }. type is range (ordered numbers), enum (a set) or boolean. To filter, put the option values under the group key in filters. Multiple values in a group are OR; different groups are AND.

Filter groups

Groups with a fixed set of values are listed in full below — you can build these without reading facets. Groups marked catalogue have per-destination values (ids with a human name): read them from facets and pass the value back.

key	Title	type	Values
`stars`	Property rating	range	`0` (unrated) – `5`.
`review_score`	Guest review score	range	`5`,`6`,`7`,`8`,`9` — minimum score (e.g. `8` = 8+).
`meals`	Meals	enum	`breakfast`, `breakfast_lunch`, `breakfast_dinner`, `full_board`, `all_inclusive`, `self_catering`.
`free_cancellation`	Free cancellation	boolean	`true`.
`adults_only`	Adults only	boolean	`true`.
`sustainable`	Sustainability certified	boolean	`true`.
`distance_km`	Max distance from centre	range	`1`, `3`, `5` (km).
`min_beds`	Minimum beds	range	`1`–`5`.
`min_bedrooms`	Minimum bedrooms	range	`1`–`4`.
`bed_type`	Bed preference	enum	`single` (2 single beds), `double`.
`property_type`	Property type	enum	Full list below.
`facility`	Facilities	enum · catalogue	Full list below.
`room_facility`	Room facilities	enum · catalogue	Full list below.
`district`	Neighbourhood	enum · per-city	Values are per-city (a neighbourhood id + name); read them from `facets`.
`chain`	Hotel chain	enum · per-city	Values are per-city (a chain id + name); read them from `facets`.
`landmark`	Near a landmark	enum · per-city	Values are per-city (a landmark id + name); read them from `facets`.

Example: {"stars":[4,5], "facility":[107,433], "meals":["breakfast"], "free_cancellation":[true]} means (4- or 5-star) AND (has Free WiFi and Swimming pool) AND (breakfast included) AND (free cancellation).

`property_type` values

value	Name	value	Name
`3`	Entire homes & apartments	`216`	Guest houses
`201`	Apartments	`220`	Holiday homes
`203`	Hostels	`221`	Lodges
`204`	Hotels	`222`	Homestays
`205`	Motels	`223`	Country houses
`206`	Resorts	`224`	Luxury tents
`208`	Bed and breakfasts	`225`	Capsule hotels
`209`	Ryokans	`226`	Love hotels
`212`	Holiday parks	`228`	Chalets
`213`	Villas	`231`	Economy hotels
`214`	Campsites	`235`	Student accommodation
`215`	Boats

`facility` values

value	Name	value	Name
`2`	Parking	`46`	Free parking
`3`	Restaurant	`54`	Spa & wellness centre
`4`	Pets allowed	`72`	BBQ facilities
`5`	Room service	`107`	Free WiFi
`8`	24-hour front desk	`139`	Airport shuttle (free)
`11`	Fitness centre	`182`	Electric vehicle charging station
`16`	Non-smoking rooms	`185`	Wheelchair accessible
`17`	Airport shuttle	`433`	Swimming pool
`28`	Family rooms

`room_facility` values

value	Name	value	Name
`5`	Bath	`81`	View
`11`	Air conditioning	`86`	Electric kettle
`16`	Kitchenette	`93`	Private pool
`17`	Balcony	`108`	Sea view
`23`	Desk	`120`	Coffee machine
`34`	Washing machine	`123`	Terrace
`37`	Patio	`998`	Coffee/tea maker
`38`	Private bathroom	`999`	Kitchen/kitchenette
`75`	Flat-screen TV	`79`	Soundproofing

facility and room_facility are catalogue groups: the response facets only lists the values present for the current destination and dates (each with a live count). The tables above are the catalogue values; always send ids that appeared in facets.

These filters are not the amenity list. facility / room_facility are the short, curated set of facilities you can filter by (the values above). They are not the per-hotel/per-room amenities you receive in a hotel-details response — that is an open-ended, free-text descriptive list (Bathrobe, Slippers, Wake-up service, Socket near the bed, …) that varies by property and has no fixed value set. Filter by the ids here; display the descriptive amenities from the response.

Sort options

Pass a sort id as sort (city mode):

id	Meaning
`price`	Price, low to high.
`stars_desc`	Stars, high to low.
`stars_asc`	Stars, low to high.
`review_score`	Guest review score, high to low.
`distance`	Distance from city centre.
`popularity`	Popularity.

Example facets block

"facets": [
  { "key": "stars", "title": "Property rating", "type": "range",
    "options": [ { "value": 5, "name": "5 stars", "count": 639 }, { "value": 4, "name": "4 stars", "count": 4196 } ] },
  { "key": "facility", "title": "Facilities", "type": "enum",
    "options": [ { "value": 107, "name": "Free WiFi", "count": 6110 }, { "value": 433, "name": "Swimming pool", "count": 5604 } ] },
  { "key": "meals", "title": "Meals", "type": "enum",
    "options": [ { "value": "breakfast", "name": "Breakfast included", "count": 652 } ] },
  { "key": "free_cancellation", "title": "Free cancellation", "type": "boolean",
    "options": [ { "value": true, "name": "Free cancellation", "count": 4614 } ] }
],
"sorts": [ { "id": "price", "name": "Price (low to high)" }, { "id": "review_score", "name": "Guest review score" } ]

A property's full facilities also appear on the hotel search (by hotel_id) under hotel.facility_groups.

City search — hotel summaries

With city_id, every offer is a hotel_summary: the property, its review scores, and the cheapest available price. Nothing is bookable yet — take the hotel_id you like and search again with it.

curl -X POST https://api.hermeseus.com/v3/HAPI/hotels/searches \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "check_in": "2026-11-14",
    "check_out": "2026-11-16",
    "city_id": 1019782831,
    "occupancies": [ { "adults": 2 } ]
  }'

{
  "object": "hotel_search",
  "id": "hsr_485158995",
  "mode": "city",
  "check_in": "2026-11-14",
  "check_out": "2026-11-16",
  "nights": 2,
  "total": 6263,
  "sort": null,
  "filters_applied": {},
  "sorts": [ { "id": "price", "name": "Price (low to high)" }, { "id": "stars_desc", "name": "Stars (5 to 0)" } ],
  "facets": [
    { "key": "stars", "title": "Property rating", "type": "range", "options": [ { "value": 5, "name": "5 stars", "count": 639 } ] },
    { "key": "facility", "title": "Facilities", "type": "enum", "options": [ { "value": 107, "name": "Free WiFi", "count": 6110 } ] }
  ],
  "pagination": { "page": 1, "page_size": 140, "total_pages": 8, "has_next": true, "has_prev": false },
  "offer_count": 140,
  "offers": [
    {
      "object": "hotel_summary",
      "hotel_id": "70784396381",
      "name": "Vida Creek Harbour",
      "lead_rate": { "amount": "165.52", "currency": "USD" },
      "lead_rate_before_discount": null,
      "discount_percent": 0,
      "deal_badges": [],
      "meal_plan": "Room Only",
      "refundable": true,
      "free_cancellation": true,
      "nights": 2,
      "occupancy": { "adults": 2, "children": 0 },
      "rating": 5,
      "review_score": 8.6,
      "review_count": 1565,
      "review_word": "Very good",
      "accommodation": "Hotels",
      "address": { "city": "Dubai", "country": "United Arab Emirates", "country_code": "AE" },
      "location": { "lat": 25.19, "lng": 55.35 },
      "images": [ "…" ]
    }
  ]
}

Hotel search — bookable rates

With hotel_id, the response carries the property once under hotel (address, check-in/out times, description, facilities) and each offer is a bookable hotel_rate with a real rate id, board, room and cancellation terms.

{
  "object": "hotel_search",
  "id": "hsr_738363500",
  "mode": "hotel",
  "check_in": "2026-11-14",
  "check_out": "2026-11-16",
  "nights": 2,
  "hotel": {
    "id": "70784396381",
    "name": "Vida Creek Harbour",
    "rating": 5,
    "address": { "line": "…", "city": "Dubai", "country": "United Arab Emirates", "country_code": "AE", "postal_code": "…" },
    "location": { "lat": 25.19, "lng": 55.35 },
    "images": [ "…" ],
    "description": "…",
    "check_in_from": "15:00",
    "check_out_until": "12:00",
    "facility_groups": [ { "name": "General", "facilities": [ "Air conditioning", "…" ] } ]
  },
  "offer_count": 39,
  "offers": [
    {
      "object": "hotel_rate",
      "id": "hrt_TkRNNU5qTTRNWHd5…",
      "total": { "amount": "165.52", "currency": "USD" },
      "total_before_discount": null,
      "discount_percent": 0,
      "deal_badges": [],
      "refundable": true,
      "refundable_until": "2026-11-12T23:59:00",
      "available_rooms": 5,
      "units": 1,
      "board": "Breakfast included",
      "board_basis": "breakfast_included",
      "board_included": [ "Breakfast included (Buffet)" ],
      "rooms": [
        {
          "id": "…",
          "name": "Classic Twin Room with City View",
          "adults": 2,
          "children": 0,
          "beds": [ "2 single beds" ],
          "max_occupancy": 2,
          "size_m2": 32,
          "description": "…",
          "images": [ "…" ]
        }
      ],
      "payment": { "title": "Pay online", "description": "…", "deposit_required": true },
      "cancellation": { "non_refundable": false, "type": "free_cancellation", "policy_text": "…" }
    }
  ]
}

Rates are quotes. Confirm the rate right before booking to lock the price and availability. The next step, confirm a rate, does that and is required before an order.

Was this page helpful?

Search destinations

Confirm a rate