Guests and rooms
How to book multiple rooms, and pass residency, the number of travelers and children ages for hotels.
How a hotel request says who travels: the rooms, the adults, the children and their ages, the residency, and later the names. These rules are specific to hotels. See Flight passengers for the flight equivalent.
The guests array: one object per room
search_advanced and get_rates take a guests array. Each object is one room: the number of rooms is the number of objects. There is no separate room count.
{ "adults": 2, "children": [8] }| Field | Type | Required | Description |
|---|---|---|---|
adults | integer | Yes | Adults in this room, 1 to 6. |
children | array of integers | No | One entry per child in this room: the child's age in years on the check-in day. [] or absent means no children. At most 4. |
A number written as text ("adults": "2", a child age "8") is read as the number, with a coerced_value warning; an integral float such as 2.0 is the same number. A boolean, NaN, a fraction or another text keeps the error of its field (see Values the API reads for you).
{
"guests": [
{ "adults": 2, "children": [] }
]
}{
"guests": [
{ "adults": 2, "children": [8] },
{ "adults": 1, "children": [] }
]
}Room 1: 2 adults and a child aged 8. Room 2: one adult travelling alone.
{
"guests": [
{ "adults": 2, "children": [3, 13, 4] },
{ "adults": 2, "children": [] },
{ "adults": 1, "children": [] }
]
}Room 1: 2 adults and 3 children aged 3, 13 and 4. Room 2: a couple. Room 3: a single traveler. In total 5 adults and 3 children in 3 rooms.
Rates are for exactly this occupancy
The rooms you send decide which rates exist and what they cost. Send the same guests and the same residency to search_advanced and to get_rates, and book with the guest list of the same rooms (see below). If the user changes a room, a child or the residency, ask for the rates again: a book_hash is only good for the occupancy it was priced for.
Children
- The age is an integer from 0 to 17, the age on the check-in day (a child who turns 9 during the stay is 8).
- Hotels set their own child rules: the age up to which a child stays free, whether an extra bed or a cot costs something, the meals for children.
get_hotel_inforeturns them inmetapolicyStruct(children,cot,extraBed,childrenMeal): read them before you tell a traveler that a child is free. - A child is a guest of the room like an adult when you book: one entry per child, flagged with
is_childandage.
Constraints
| Rule | Limit | Error code |
|---|---|---|
guests is a non-empty list of objects | invalid_guests | |
| Rooms in a request | 1 to 9 | too_many_rooms |
| Adults in a room | 1 to 6 (a room cannot hold children only) | invalid_adult_count |
| Children in a room | at most 4 | too_many_children |
| Age of a child | 0 to 17, a whole number | invalid_child_age |
| Guests in a room, adults and children together | at most 10 | too_many_guests |
They answer 400, before the supplier is called. A room can still have no rate because of its real capacity: the supplier only offers the rooms that can take the occupancy, so an empty rates list means that no room fits or that the hotel has no availability.
Residency
residency is the country of residence of the guests, a two-letter ISO 3166-1 code (gb, dz, fr; upper or lower case). It is sent once per request, not per room or per guest. It decides which rates exist, because some rates are for some residencies only (anyResidency: false on the rate), and it can change the price.
get_ratesusesgbwhen you send none.search_advancedhas no default: always send it, and send the same one to both calls.- A code the supplier does not know answers
400 invalid_residency(zz,usa,gbr, an empty text). - The sub-territory values of the website's nationality list (
GB-SCT,USPR,ES-XCI,PT-MA,PT-AZ,CY-NC,GP-MG,BQ-SA,BQ-SE) are read as their country (gb,us,es,pt,cy,gp,bq), with acoerced_valuewarning. Send the 2-letter country. - In the sandbox,
test_hotelcan only be searched withdz,ruorus: see Sandbox testing.
Guest names at booking time
book_hotel takes a rooms array: one object per room, in the same order as the rooms you searched. Each room lists the real guests who sleep in it, one entry per adult and per child:
{
"rooms": [
{
"guests": [
{ "first_name": "Amine", "last_name": "Benali" },
{ "first_name": "Sara", "last_name": "Benali" },
{ "first_name": "Yanis", "last_name": "Benali", "is_child": true, "age": 8 }
]
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
first_name, last_name | string | Yes | Up to 100 characters each. See the rules below. |
is_child | boolean | For a child | true for a child. |
age | integer | For a child | The age in years on the check-in day, 0 to 17. The same age you searched with. A number written as text is read, with a coerced_value warning. |
How names are cleaned
The supplier refuses digits and most symbols in a name, so FX-Port cleans each name before it sends it: letters of any script (Latin with accents, Arabic, Cyrillic, Chinese ...), spaces, hyphens, commas, periods and apostrophes are kept, and anything else (digits, slashes, brackets, underscores ...) is replaced by a space and the spaces are collapsed. Ben2 becomes Ben and Smith/ becomes Smith Jr.
Accented and non-Latin names are accepted: bookings with José Núñez, Zoë O'Brien-Müller and Arabic names were confirmed in the sandbox. Send each name as it is written in the traveler's passport. ASCII letters are not required.
See book_hotel for the whole booking request, including the contact details.