1. Destination Search

The destination search is used to get availability for all hotels in a specific destination id. The destination can be either a city or a specific property. By default it returns an Asynchronous  response allowing the user to control the search flow:

Initiate Request:

<request version="4.0">
  <auth>
    <username>example</username>
    <password>example</password>
    <agent>example</agent>
    <clientIp>1.2.3.4</clientIp>
    <clientUserAgent>example user agent</clientUserAgent>
  </auth>
  <hotel-search entityType="location" entityID="4223">
    <dates from="2014-08-01" to="2014-08-02"/>
    <filters>
     <filter type="payAtTheHotel">1</filter>
        <filter type="onRequest">0</filter>
        <filter type="showSpecialDeals">1</filter>
        <filter type="getPackageRates">1</filter>
    </filters>
    <pax-group customerCountryCode="DE">
      <pax>
        <adults count="2" />
        <children count="2">
          <age>11</age>
          <age>12</age>
        </children>
      </pax>
       </pax-group>
    <currencies default="EUR">
      <currency code="EUR"/>
      <currency code="GBP"/>
      <currency code="USD"/>
    </currencies>
  </hotel-search>
</request>
Request Parameters:

 Parameter Type Comments
 entityType location/hotel location=city search, hotel=individual property
 entityId int the identifier of the desired entity
 dates @from YYYY-mm-dd the check-in date
 dates @to YYYY-mm-dd the check-out date
 filters @type="payAtTheHotel" boolean to include or not to include pay at the hotel content
 filters @type="onRequest" boolean to include or not to include on request content
 filters @type="showSpecialDeals" boolean     to include or not to include special deals information
 filters @type="getPackageRate" boolean  to include or not to include package (opaque) rates 
 pax-group @customerCountryCode country code 2 letter ISO code for the customer country
 pax node each required "room" is defined by a "pax" node to describe the persons staying in that room
 pax/adults @count int the number of adults
 pax/children @count int the number of children
 pax/children/age int the age of each child
 currencies @defaultcurrency  3 letter ISO code for the default currency
 currencies/currency @code currency 3 letter ISO code for the accepted currency

Notes

  1. Filters are optional, if you wish to get the default content, do not include the filters node.
  2. customerCountryCode is mandatory, and the same code should be used for the entire session flow. i.e. when searching for a specific country code, you must use the same country code for booking.
  3. children are optional. if you are not search for a room with children, do not include the children node.
  4. currencies are returned according to the list in the request. properties that use a currency that does not appear on the list will be converted to the "default" currency. to remove restrictions and return all currencies, add an attribute to the currencies node: all="true"
  5. the clientIp and clientUserAgent values are not mandatory, but may help getting better rates. note that if you do send them here, you must send them on each request including the booking request, otherwise the rates may vary between the search and booking.

Asynchronous Response:
<response success="1" session="dv.Uw8IU6CsA">
  <search status="working">
    <server>http://mishor.example.com/</server>
  </search>
</response>

The Asynchronous response consists of the following elements:
Parameter Type Comments
response @successboolean was the request successful
response @sessionstring the search id of the requested search
serverurlthe url  of the search server to use for polling and booking

Synchronous work:

In order to work in a synchronous flow, you can include the following node in your request as a child node of the "hotel-search" node:
<nopolls-timeout>20</nopolls-timeout>

This will skip the Asynchronous response above and the poll request step below and return the poll-response after X seconds mentioned in the node value. in the example above you will get a response after 20 seconds.

NOTE: it is highly encouraged NOT to use this method and work in an Asynchronous flow, as you and your customers will be missing on many prices, rooms, and deals.

Initiate Poll

With the search response session id, it is now possible to start polling the results. For a description of the flow, please revert to section 3: Search Flow
Poll Request
<request version="4.0">
  <auth>
    <username>example</username>
    <password>example</password>
    <agent>example</agent>
  </auth>
  <hotel-poll session="dv.Uw8IU6CsA" last="0"/>
</request>

Parameter Type Comments
hotel-poll @sessionstringthe session id of the requested search
hotel-poll @lastintthe last @last attribute received from the previous poll
Poll Response
<response success="1" session="dv.Uw8IU6CsA">
  <job status="working"/>
  <server>http://mishor.example.com/</server>
  <results last="19494" count="406">
    <result id="4762" providers="innstant.travel" availableBoards="RO" hasPackageRate="0">
      <price currency="EUR" final="1" minCommissionablePrice="317.724" minAllowedPrice="861.17">
        <min-rooms>
          <min-room board="RO" commissionAble="1" roomCount="2">Tower Room, 1 King Bed</min-room>
        </min-rooms>
      </price>
      <combinations>
        <combination price="469.4" currency="EUR" commissionable="1" billable="1"/>
      </combinations>
    </result>
    <result id="21917" providers="innstant.travel" availableBoards="RO,BB" hasPackageRate="1">
      <price currency="EUR" final="1" minCommissionablePrice="557.425" minAllowedPrice="0">
        <min-rooms>
          <min-room board="RO" commissionAble="1" roomCount="1">Superior Room NON-REFUNDABLE</min-room>
        </min-rooms>
      </price>
      <non-billable-price currency="EUR" final="1" minCommissionablePrice="956.56">
        <min-rooms>
          <min-room board="RO" commissionAble="1" roomCount="1">Double Superior</min-room>
        </min-rooms>
      </non-billable-price>
      <combinations>
        <combination price="1284.69" currency="EUR" commissionable="1" billable="1" pricePerRoom="0"/>
      </combinations>
      <special-deals>
        <special-deal><![CDATA[1 Night Free]]></special-deal>
        <special-deal><![CDATA[Special Discount]]></special-deal>
      </special-deals>
    </result>
    ...
  </results>
</response>

Parameter Type Comments
response @successbooleanwas the request successfull
job @statusstring"working" or "done"

servernode the server url to call for hotel-rooms poll 
results @last intkeep this number for the next poll (see request)
results @count inthow many results were returned in this specific poll response
result @id intthe identifier of the hotel this result belongs to. hotel information can be retreived from the static data
result @providers stringcomma separated string of providers available for this property
result @availableBoards stringcomma separated string of boards available for this property
result @hasPackageRateboolean if true (1) - it means that there are results that should only be sold as part of a package 
result/price node availablity coming from innstant.travel
result/price @currency currency 3 letter ISO currency code
result/price @minCommissionablePrice doublethe minimum commissionable price - appears only if such result is available
result/price @minNonCommissionablePrice doublethe minimum non-commissionable price - appears only if such result is available
result/price @minAllowedPrice doubleminimum price to be displayed for B2C environment (BAR rate)
min-room @board board code2 letter board code
min-room @commissionAble booleancan a commission be added to this price
min-room @roomCountint how many rooms are available 
min-room nodethe room name
result/non-billable-price node availability coming from direct providers 
price/combinations nodein case of more than 1 room, this node will show the combined prices for multiple combinations for all rooms in the search. see note #5  
combination @pricedoublethe total price of the combination
combination @currencycurrency 3 letter ISO currency code
combination @commissionableboolean  is the price commissionable  
combination @billableboolean is the combination coming from your direct providers 
combination @countint the number of rooms of that specific type. see note #8 for details 
combination @pricePerRoomboolean is the price shown per room or total. see note #8 for details
special-dealnode titles of the special deals available for the hotels 

Notes

  1. The first poll request should be sent at least 3 seconds after the search response. You also need to wait at least 3 seconds between poll requests.
  2. It is up to the user to decide when they received enough results. after the attribute @status is returned as "done" there is no point in running additional polls.
  3. If there are no results from your direct providers, the non-billable-price node will not be returned
  4. it is not allowed to add commission on top of non-commissionable items
  5. B2C platforms MUST make sure that they never show prices that are lower than the minAllowedPrice attribute value. if the minAllowedPrice is not returned, or returned as 0, it means that there is no restriction on the sale price and you can sell it at whatever rate you like
  6. the combination nodes are optional. in case our system cannot create a valid combination, no combinations will be returned
  7. In order to get the room category on the min-room node you will need to send a special filter in the search request. the attribute name that will be returned will be "category"
  8. "Special deals" are only returned in case the appropriate filter is sent. In case there are no "Special deals" no special-deals node will be returned.
  9. In case the combination @count attribute is more than 1, and the @pricePerRoom attribute equals 0 (zero), then the price shown is the total price for the @count rooms. in case the  @pricePerRoom attribute equals 1, then the price is per room and not the total price for all rooms of that type.

Optional Filters

The following optional filters can be added to the destination search under the "Filters" node:
  1. showRoomDescriptions - include room descriptions where available
  2. showRoomBedding - include the room approximate bedding configuration (double/twin/triple/etc)
  3. showRoomCategories - include the room approximate category (standard/suite/luxury/etc)


Comments