Hotel booking API

The hotel booking API searches live availability and room rates for a destination and dates.

POST/v2/Hotel/HotelAvailability

Access requires the permission hotel_availability

This one endpoint runs two ways. Pass a CityId to list properties in a place. Pass a HotelId to open one property and get its room rates. Send exactly one of the two.

Two versions. The v2 path above is the recommended one. The v1 path /Hotel/HotelAvailability takes the same core fields and returns the same shape. New integrations should use v2.

Path parameters

None.

Query parameters

None.

Body parameters

Name Type Required Default Description

SessionId string Yes - Your session id.

CheckIn string Yes - Arrival date, YYYY-MM-DD.

CheckOut string Yes - Departure date, YYYY-MM-DD. Must be after CheckIn.

CityId integer One of - Place external_id from place search. City mode.

HotelId integer One of - A single property. Hotel mode. Send CityId as null.

Page integer No 1 1-based page number.

PageSize integer No - Results per page, 1 to 200.

Sort string No - Sort key, for example price. The available sorts come back in Meta.

Filters object No - Facet filters as { "key": [ids] }, combined with AND. See below.

Map object No - Viewport bounds to constrain results to a map area.

lang string No - Content language, for example ar.

Occupancies array of object, required

One entry per room. Minimum 1.

Name	Type	Required	Description
`AdultCount`	integer	Yes	Adults in the room, 1 to 8.
`ChildCount`	integer	No	Children in the room, 0 to 6.
`ChildAges`	array of integer	No	Age of each child at check-out, 0 to 17. One age per child.

Filters

Send filters as arrays of ids under named keys, for example { "class": [4,5], "mealplan": ["breakfast_included"] }. Conditions combine with AND. Each search returns the full set of available filter keys and their selectable ids under Meta.AvailableFilters, each with a live result count, so read that to build the filter UI for the current results.

Request: list a city

curl -X POST https://api.hermeseus.com/api/v2/Hotel/HotelAvailability \
  -H "Content-Type: application/json" \
  -d '{
    "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
    "CheckIn": "2026-10-15",
    "CheckOut": "2026-10-16",
    "CityId": 11111111456928,
    "Occupancies": [ { "AdultCount": 2, "ChildCount": 0 } ],
    "Filters": { "class": [4, 5], "mealplan": ["breakfast_included"] },
    "Sort": "price",
    "Page": 1
  }'

const res = await fetch("https://api.hermeseus.com/api/v2/Hotel/HotelAvailability", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    SessionId: "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
    CheckIn: "2026-10-15",
    CheckOut: "2026-10-16",
    CityId: 11111111456928,
    Occupancies: [ { AdultCount: 2, ChildCount: 0 } ],
    Filters: { class: [4, 5], mealplan: ["breakfast_included"] },
    Sort: "price",
    Page: 1
  })
});

const data = await res.json();

import requests

res = requests.post(
    "https://api.hermeseus.com/api/v2/Hotel/HotelAvailability",
    json={
        "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
        "CheckIn": "2026-10-15",
        "CheckOut": "2026-10-16",
        "CityId": 11111111456928,
        "Occupancies": [{"AdultCount": 2, "ChildCount": 0}],
        "Filters": {"class": [4, 5], "mealplan": ["breakfast_included"]},
        "Sort": "price",
        "Page": 1,
    },
)

data = res.json()

Request: open one hotel

Set CityId to null and pass HotelId. The response switches from a list of properties to the room rates for that hotel.

POST /api/v2/Hotel/HotelAvailability
{
  "SessionId": "8f3c81d2-4a5b-4c6d-9e0f-1a2b3c4d5e6f",
  "CheckIn": "2026-10-15",
  "CheckOut": "2026-10-16",
  "CityId": null,
  "HotelId": 7825691,
  "Occupancies": [ { "AdultCount": 2 } ]
}

Response

Results come under PricedItineraries. In city mode each entry is a property. In hotel mode each entry is a bookable room rate carrying a FareSourceCode.

Field	Type	Description
`PricedItineraries`	array of object	Properties, or room rates in hotel mode. See below.
`Meta`	object	Pagination, the price range, and the available sorts and filters for this search.

PricedItineraries[] object

Field	Type	Description
`HotelId`	integer	Property id. Open it in hotel mode.
`HotelName`	string	Property name.
`NetRate`	number	Total rate for the stay. USD.
`Currency`	string	Always `USD`.
`NonRefundable`	boolean	Whether the rate is non-refundable.
`FreeCancellation`	boolean	Whether free cancellation applies.
`MealPlan`	string	Board, for example room only or breakfast.
`FareSourceCode`	string	In hotel mode, the code to validate and book with.
`Hotel`	object	Property profile: name, rating, location, images.
`Room`	object	In hotel mode: name, beds, size, description, amenities, and room images.

Keep the FareSourceCode. In hotel mode, the room rate the traveller picks has a FareSourceCode. You validate and book with it.

Errors

Code	Meaning	Fix
`Err0201003`	Not exactly one of `CityId` or `HotelId`.	Send one, set the other to `null`.
`Err0106001`	A date or occupancy field is missing or invalid.	Fix the field named in the message.