The availability search allow the client system to retrieve the list of all the available hotels with their prices on city basis, dates basis or on the basis of the type of rooms requested.
The list of the hotels reports the name of the hotel, the number of stars and their position (city center, close to the center and so on).
If you want to search only for extra-hotel structures (apartments, villas...), set star filter to 0.
Here is an example of an availability search:
<?xml version="1.0" encoding="UTF-8"?>
<envelope>
<header>
<actor>test</actor>
<user>test</user>
<password>test</password>
<version>1.6.1</version>
<timestamp>20030423170000</timestamp>
<distributor>5</distributor>
</header>
<query type="availability" product="hotel">
<nationality>IT</nationality>
<filters>
<filter>AVAILONLY</filter>
<filter>BESTARRANGMENT</filter>
</filters>
<checkin date="2003-09-05"/>
<checkout date="2003-09-13"/>
<city code="vce"/>
<category code="st"/>
<hotel id="1234">CARLTON GRAN CANAL</hotel>
<details>
<room type="sgl" required="3"/>
<room type="dbl" required="1" extrabed="true" age="5"/>
<room type="trp" required="1" cot="true"/>
</details>
<stars>
<star>1</star>
<star>2</star>
<star>3</star>
<star>4</star>
<star>5</star>
</stars>
</query>
</envelope>This availability query contains all the available fields: the type attribute is set to availability. Let's explore in deeper detail the meaning of every field.
You can also perform a multiple hotel search without city ID (max 200 hotels per search). In case a city tax is applicable to the destination the hotel ID is associated, if the city tag is empty, the presence of the city tax will not be notified.
<?xml version="1.0" encoding="UTF-8"?>
<envelope>
<header>
<actor>ACTOR</actor>
<user>USER</user>
<password>PASSWORD</password>
<version>1.6.0</version>
<timestamp>20140522105400</timestamp>
</header>
<query type="availability" product="hotel">
<checkin date="2014-09-15"/>
<checkout date="2014-09-16"/>
<hotel id="25846"/>
<hotel id="12296"/>
<filters>
<filter>AVLHEAVY</filter>
<filter>AVAILONLY</filter>
<filter>BESTARRANGMENT</filter>
</filters>
<details>
<room type="dbl" required="1"/>
</details>
<longitude value="12.433462230000000"/>
<latitude value="41.933914270000000"/>
<distance value="1000"/>
</query>
</envelope>You have the chance to communicate a specific client timeout in the availability request. You just have to add the tag timeout within the query, for example:
<query>
...
<timeout>5.5</timeout>
...
</query>For what concerns rooms mapping, you can use the attribute "occupancy" in the instead of the "type" attribute, an example would be the following:
<query type="availability" product="hotel">
<filters>
<filter>AVAILONLY</filter>
</filters>
<checkin date="2014-12-12"/>
<checkout date="2014-12-13"/>
<city code="ROM"/>
<details>
<room occupancy="2" required="1" extrabed="false"/>
</details>
</query>With this, the system will return all the rooms available for the selected occupancy. You can ask for more than one room by changing the "required" number, or ask for extrabeds by changing the proper field to "true". Please notice thay you can ask for more than one occupancy, for example
<room occupancy="2" required="1" extrabed="false" />
<room occupancy="1" required="2" extrabed="false" />this will return all the combinations of double/single/twin/tsu rooms. For performance purposes you cannot ask for more than two kinds of occupancy at the same time.
Please note that you can use "type" or "occupancy" but not both of them in the same request.
For performance reasons, we suggest to use room types instead of occupancy.
Of course you can use occupancy if you are not able to handle room types.
The response is similar to a normal availability request with multi hotel ID in the same city.
ATTENTION: evaluate step is mandatory for agreements that come from occupancy searches. If you obtain an agreement from an occupancy search, you must run and evaluate call before the booking request, otherwise the booking will result in an error.
If you want to search for children-only rooms (a room to accommodate only children without any adult) you can do it by requesting occupancy="0". The following tag requests a room to accommodate two children (6 and 8 y.o.) and no adults:
<room occupancy="0" required="1" extrabed="true" age="6-8"/>In response you will receive the attribute occupancyChild in the room tag that you have to pass through the whole booking flow (every time you use a <room> tag) in order to correctly book a children only room.
If you want to accommodate more than 4 adults in the same room, you can use the "str" room type.
"str" is a special room type that must be used together with the "occupancy" attribute and allows you to request more than 4 people.
Example:
<room type="str" occupancy="6" required="1"/>When searching/booking for a "str" room (and only in this case), you have to provide both type and occupancy during the whole booking flow.
Before proceeding with the reservation request, it is compulsory to perform an availability search to the single hotel ID you choose, as per the below process:
This particular single-hotel search (evaluate) must have (in addition to all other data) a "search" tag with the following attributes:
EVALUATE is the pre-book step of our boking flow. Its purpose is to verify the conditions of a single contract (agreement tag) before booking it.
Please note: evaluate requests without type attribute will result in an error.
The room type of an evaluate request must match the room type of the contract in the availability response.
Example:
<query type="availability" product="hotel">
<search number="1238" agreement="LCL.3186" price="95.00"/>
<checkin date="2019-12-12"/>
<checkout date="2019-12-13"/>
<hotel id="25846"/>
<details>
<room type="dbl" required="1" extrabed="false"/>
</details>
</query><city code="LON" />
<city code="PAR" />and you'll get results for both cities. Please notice that there's no limit to the number of cities you can provide, but we recomment not to ask for more than 3-4 cities together in order not to influence search performances.
room
Describe the requested room. The number of rooms of this type is reported in required attribute while the room type is reported by the type attribute. The type attribute may contains the following values:
On your expicit request, we can configure your account to return two additional room typologies:
These two typologies will be used instead of SGL/TSU and DBL/TWN when our feed cannot guarantee the correct room type.
The extrabed attribute, if present and set to true, requires an extrabed. In case of extrabed, the attribute age must be set to the age of the child (or, in case of FAM, the ages of the children separated by a "-". Example: age="5-7").
Please notice that not all suppliers handle extrabeds properly, hence sometimes a extrabed request could lead to unpredictable results (i.e. a double + extrabed request could return a simple triple room in response.) Please be aware of that when booking. The cot attribute, if present and set to true, requires a cot.
The only kind of room to which you can add a cot are twin, double and triple. The total number of required room must not be more than 5; the total number of passengers (adults or extrabed) must be not more than 9.
Please note that sending the age tag witout extrabed=true is meaningless and consequently the age attributes will not be considered.
The response to an availability query has its type attribute set to availability and follows that form:
<?xml version="1.0" encoding="UTF-8"?>
<envelope>
<header>
<version>1.6.3</version>
<timestamp>20200129154400</timestamp>
</header>
<response type="availability" product="hotel">
<search number="20240212597437988" time="2.51" />
<nights number="18" />
<checkin date="2020-09-05" />
<checkout date="2020-09-23" />
<hotels total="2">
<hotel code="43016" name="UNIVERSO" stars="3" location="01" address="Piazza Santa Maria Novella, 20, 50123" promo="false" city="FLR">
<agreement id="0xbd.43016.7.RB.C.Y2JhYTkw.0.BB.MGFjMDRk" available="true" room_basis="RB" meal_basis="C" ctype="7" c_type="7" room_type="Standard Room" is_dynamic="false" currency="EUR" deadline="2020-09-01" total="4248.00" total_gross="4248.00" original_total="4248.00" special="false">
<deadline date="2020-09-01 18:00:00" value="2020-09-01 18:00:00"/>
<policies>
<policy from="2020-09-01 18:00:00" percentage="5.56" />
</policies>
<deadline_remarks />
<remarks>
<remark text="Supplier Rooms description: 1 x QUADRUPLE"/>
<remark text="From 2015-12-13 to 2039-12-13: CITY TAX: Hotel prices do not include room taxes established by local entities. These room taxes vary according to the city and hotel category and are charged directly by the hotel upon client’s arrival."/>
</remarks>
<room type="qud" required="1" occupancy="4">
<price from="2020-09-05" to="2020-09-23">
<roomprice nett="4248.00" gross="4248.00"/>
</price>
</room>
</agreement>
<agreement id="0xa8.43016.7.RB.C.YjE0NjA2.MzMyMTg4.Zjc1YzNh" available="true" room_basis="RB" meal_basis="C" ctype="7" c_type="7" room_type="Quadruple Room" is_dynamic="true" currency="EUR" deadline="2020-01-28" total="4464.00" total_gross="4464.00" original_total="4464.00" special="false">
<remarks>
<remark code="SYS_CONTRACT_TYPE" text="Quadruple room"/>
</remarks>
<room type="qud" required="1" occupancy="4">
<price from="2020-09-05" to="2020-09-23">
<roomprice nett="4464.00" gross="4464.00"/>
</price>
</room>
</agreement>
</hotel>
<hotel code="103945" name="MORANDI ALLA CROCETTA" stars="3" location="09" address="Via Laura, 50, 50121" promo="false" city="FLR">
<agreement id="0x62.103945.7.RO.X.YzBhN2Fl.NDlhNGYw.FLR" available="true" room_basis="RO" meal_basis="X" ctype="7" c_type="7" room_type="Classic Quadruple Room" is_dynamic="true" currency="EUR" deadline="2020-01-28" total="4734.00" total_gross="4734.00" original_total="4734.00" special="false">
<remarks>
<remark text="NON REFUNDABLE"/>
<remark code="SYS_CONTRACT_TYPE" text="Classic Quadruple Room"/>
</remarks>
<room type="qud" required="1" occupancy="4">
<price from="2020-09-05" to="2020-09-23">
<roomprice nett="4734.00" gross="4734.00"/>
</price>
</room>
</agreement>
</hotel>
</hotels>
</response>
</envelope>Some of the previous fields share the same name and meaning of the fields seen in request so let's take into account only the new fields.
evaluate If you passed the search tag in the availability request and the request is on a single hotel id, you will receive this tag. It will contain a result tag with following attributes:
If the client uses the evaluate, we show also a deadline tag in the availability response. This deadline (like all other data in this response) is accurate, so you don't need to perform a new get_deadline before book.
agreement