Guests & rooms

How to book multiple rooms, pass residency, number of travelers, and children ages for hotels.

These rules are specific to hotels. See Flight passengers & ages for the flight equivalent.

The `guests` array — one element per room

search_advanced and get_rates both take a guests array. Each object in the array represents one room. The number of rooms you request is the number of objects you send — there is no separate "room count" field.

{
  "adults": 2,
  "children": []
}

Field	Type	Required	Description
`adults`	integer	Yes	Number of adults in this room. Minimum 1.
`children`	array of integers	Yes (can be empty)	One entry per child in this room — the child's age in years at check-in. `[]` means no children.

Multi-room examples

{
  "guests": [
    { "adults": 2, "children": [] }
  ]
}

Children age rules

Children ages are integers, the child's age at check-in:

Age	Category
0–1	Infant
2–5	Young child
6–11	Child
12–17	Teenager (some hotels treat 12+ as an adult for pricing/capacity)

Hotel child policies vary by property. get_hotel_info returns metapolicyStruct.children (and .cot for infant cot/extra-bed policy) with that hotel's exact rules — check it before assuming a child age is free or requires an extra bed.

Constraints

Every room needs at least 1 adult — a room cannot be children-only.
Children ages must be integers 0–17.
There's no hard maximum guests per room in the request itself, but the supplier can reject a room/rate combination that exceeds that room's real capacity — check room.capacity on the returned rate.

Residency

residency is a guest nationality/residency country code (ISO 3166-1 alpha-2, e.g. "DZ", "gb", "fr"), sent once per request — not per room or per guest. It affects which rates are shown, since some rates are residency-restricted (anyResidency: false on the rate). Default is "gb" when omitted.

{ "residency": "DZ" }

Guest names at booking time

book_hotel takes a rooms array — again, one object per room, matching the same room order you searched/priced with. Each room has a guests array of the actual travelers staying in it:

{
  "rooms": [
    {
      "guests": [
        { "first_name": "Amine", "last_name": "Benali" },
        { "first_name": "Sara", "last_name": "Benali" }
      ]
    }
  ]
}

Name encoding: Use plain Latin (ASCII) letters only for first_name / last_name — no diacritics (Jose not José), no non-Latin scripts (transliterate Arabic/Cyrillic/Chinese/etc.). Allowed characters: A–Z, a–z, spaces, hyphens, commas, periods, apostrophes. The supplier rejects digits and other symbols in guest names.

See book_hotel for the full booking request shape, including contact details.