Availability search

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.

Children only

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.

"Big rooms"

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.

Evaluate

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:

  1. run an availability search with multiple hotel IDs or destination (results may come from a cache)
  2. choose the hotel to book
  3. run a new search on the chosen hotel (evaluate, with fresh data)

This particular single-hotel search (evaluate) must have (in addition to all other data) a "search" tag with the following attributes:

  • number: search number of the previous availability search
  • agreement: chosen agreement id from previous availability search
  • price: agreement price from previous availability search (attribute "total" of the "agreement" tag)

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>
Query
  • distributor
    • Optional.It can be added in the header; it contains the id of the distributor to use
  • nationality
  • filters
    • The value of this field is a sequence defined the constraints applied to all the availability results:
      • AVAILONLY: returns only the hotel agreements on immediate confirmation (.../agreement[@available]=true)
      • AVLHEAVY: in the price comparison the system gives higher weight to the hotel agreements on immediate confirmation. On reques results will be returned only if the rate is much more convenient.
      • BESTPRICE: returns only the contract with the best price for each hotel (.../agreement[@total]=min per hotel).
      • BESTCONTRACT: returns the best price for each contract type of the hotels (.../agreement[@total]=min per .../agreement[@c_type]). Dynamic inventory (.../agreement[@is_dynamic]=true) is excluded from this comparison
      • BESTROOMBASIS: returns the best price for each room basis (.../agreement[@total]=min per .../agreement[@room_basis]), regardless of the contract types. WARNING: right now this filter is available only in live environment.
      • EXCLUDENONREF: the system will remove from the response all the contract typologies - statically mapped or dynamically achieved - containing the typical "non refundable" wording in their description (.../agreement[@room_type]). Actually this method is not 100% safe as you can imagine so you'd better check before performing the reservation if the cancellation policies are in full charge and the created reservation would already be in cancellation deadline in order to avoid the last few cases
      • EXCLUDEDYNAMIC: the system will remove from the response all the dynamic contracts (.../agreement[@is_dynamic]=true).
      • REDUCED: the system will remove from the output a number of fields for hotel details and agreements which are not mandatory for the correct performing of a availability/booking procedure. In order to know which fields are returned and which not we suggest to perform a REDUCED availability call and compare the result with a complete one.
      • BESTARRANGMENT (default): returns the best price for each different arrangement type (unique pairs of.../agreement[@c_type] and .../agreement[@room_basis] ) of the hotels.
  • checkin
    • It's the check-in date. It has to be inserted as date attribute using the format YYYY-MM-GG as previously described for the timestamp.
  • checkout
    • It's the check-out date. See checkin for further details.
  • city
    • Destination city. The city code has to be passed in the code attribute. City codes are unique. In order to perform a multi-city search you just need to include more city codes (max 5 city codes), for example
<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.

  • category
    • Hotel's category. This field is optional and is useful only for big cities with dozen of hotels. The code attribute may contain one of the following values:
      • T touristic;
      • ST superior touristic;
      • F first category;
      • SF superior first category;
      • D deluxe
  • stars
    • With this tag it is possible to search hotels with a determined number of star, defined in a star tag. Filter for 0 stars to obtain only extra-hotel product (i.e. apartments, villas...)
  • hotel
    • With this tag it is possible to check availability of a particular hotel through id, or of a series of hotels through a part of their name. Attribute c_type, reports the numeric ID of the contract type (i.e. 1=STANDARD, 2=DELUXE, ecc). See the specific section of the documentation to retrieve the bindings between ctype codes and contract type descriptions.
  • latitude
    • Optional. Latitude (in degrees) where to search availability (must be used with longitude and distance)
  • longitude
    • Optional. Longitude (in degrees) where to search availability (must be used with latitude and distance)
  • distance
    • Optional. Search radius (in meter) where to search availability (must be used with longitude and latitude)
  • currency
    • Optional. You can provide a currency to be used for the availability search if you need to. If you request a currency in availability, you need to provide the same also in the booking request.
  • details
    • Contains all the requested rooms'details. For every room type requested, there has to be a room element, as shown by the example above.
  • 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:

      • SGL single room
      • TSU twin for sole use room
      • TWN twin room
      • DBL double room
      • TRP triple room
      • QUD quadruple room
      • FAM Family Room (2 adult + 2 extrabed)
      • STR rooms for more than 4 people (see specific section "Big rooms" above)

      On your expicit request, we can configure your account to return two additional room typologies:

      • 1px room for 1 passenger
      • 2px room for 2 people

      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.

Response

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.

  • search
    • Number of availability search, reported in its number attribute. We strongly suggest you to treat search number as a STRING instead of a number. Some languages may silently change number value if you rely on integer type.
  • 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:

    • code: evaluate status code. Possible values:
      • ok: evaluate performed successfully. Our feed has granted the availability as this conditions
      • price_changed: evaluate performed successfully, but the price is changed compared to the one seen during the previous availability search
      • cxl_policy_changed: evaluate performed successfully, but cancellation policies have changed
      • availability_type_changed: evaluate performed successfully, but availability type is changed (i.e. was "immediately available" and now is "on request")
      • not_available evaluate performed successfully, but the requested contract is not available anymore. It is not possible to perform a booking on this contract.
        N.B. In this case, "evaluate" will be the only tag in the "response" node.

    • option_blocked: can be true or false. Tells if our feed have "blocked" the option for you. Please, note that the option can be blocked only for a limited time.

    See examples

    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.

  • nights
    • Number of requested nights, its reported in its number attribute.
  • hotels
    • Collects all the returned hotels.
  • hotel
    • Reports a single hotel and contains the following attributes:
      • code, unique identifier of the hotel in the TOWeRS system.
      • name, hotel's name.
      • stars, number of stars in hotel classification.
      • location, hotel position.
        • 01 City center
        • 02 Airport
        • 03 Railway station
        • 04 Port
        • 05 Sea/Beach
        • 06 Open country
        • 07 Mountains
        • 08 Periferals
        • 09 Close to city centre
  • agreement

    • Points out a single contract for the hotel. It contains the following attributes:
      • id, tariff code to be used for the booking. Same hotel could have more different codes. An agreement should be treated by the client as an opaque element to pass back and forth but they should not try to "use" it as its logic pertains to specific parts of our code. The idea is that as long as our system returns to the customer a contract having the same room typology, meal basis and rate then it is the one they're looking for and they should use this last agreement to perform the booking. Agreements may change or remain unmodified but the client should not apply any logic on them.
      • available, points out if a hotel is immediately available (true) or on request (false).
      • c_type, reports the numeric ID of the contract type (i.e. 1=STANDARD, 2=DELUXE, ecc). See the specific section of the documentation to retrieve the bindings between c_type codes and contract type descriptions.
      • room_basis, points out the agreed treatment:
        • RB Overnight and breakfast
        • RL Overnight and lunch
        • RD Overnight and dinner
        • RO Overnight only
        • FB Full board
      • meal_basis, points out the kind of breakfast:
        • H Hot Buffet
        • C Continental
        • B Cold Buffet
        • A American
        • V V
        • R Irish
        • I Israeli
        • O Room Service(Continental)
        • S Scandinavian
        • E English
        • T Scottish
        • X No breakfast
      • currency, points out the reference currency.
      • deadline, points out the time limit for cancellation without any charges.
      • total, points out the total amount of the query as per the particular hotel contract.
      • special, is worth true or false depending on the contract is a special offer.
      • is_dynamic, in case is_dynamic is true, the real ctype of the offer can be found in the room_type attribute, or in the remarks if not available.
      • room_type, contains the ctype in form of text (standard rooms, deluxe rooms, etc) and contains the real ctype in case of dynamic offers.
      • rsp: Recommended Selling Price. It is an optional field which shows the minimum selling price required by the hotel.
      • rsp_currency: currency of the Recommended Selling Price. Also this attribute is optional.
    • It can contain also the following tags:
      • deadline, policies, deadline_remarks, remarks: even before using the evaluate method, you can retrieve the actual cancellation policies already in the availability stage (for searches aimed at a whole city or at hotel IDs or at a single property) for the contracts provided by suppliers who can share this information already in the availability phase. In this case you will obtain the actual structured policies (with tags deadline, policies and remarks, such as in the get_deadline response).
        You can refer to get deadline documentation response section to fully understand cancellation policies meaning and to get the correct way to iterpret them.
        If you don't get this kind of structured policies (with tags deadline, policies and remarks), it means the deadline shown within the tag agreement may be just indicative (and so wrong) and so that you need to use the get_deadline method.
  • room
    • Collects all the data of a room. Same attributes of the request plus the following attributes:
      • occupancy, the number of adults accomodated for the selected room typology.
      • occupancyChild, the number of children (extrabeds) accomodated for the selected room typology.
      • occupancyInfant, the number of infants (cots) accomodated for the selected room typology.
  • remarks
    • Contains additional informations regarding the selected offer. In case of dynamic offer (is_dynamic=true) there will be a remark with code SYS_CONTRACT_TYPE that contains, in the text attribute, the real ctype of the offer.
  • price
    • Tariff of the period. The attributes from and to reports the period of the tariff. Contains prices divided by type.
  • roomprice
    • The price of the room. The price has to be meant per room, for the whole tariff period. The price, in €, is reported in the nett attribute.
  • extrabedprice
    • Price of the extrabed. Like roomprice
  • cotprice
    • Price of the cot. Like roomprice and extrabedprice