1. Destination Search

Mishor 4 Documentation‎ > ‎5. API Methods‎ > ‎1. Hotels‎ > ‎

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>

</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 @default	currency	3 letter ISO code for the default currency
currencies/currency @code	currency	3 letter ISO code for the accepted currency

Notes

Filters are optional, if you wish to get the default content, do not include the filters node.
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.
children are optional. if you are not search for a room with children, do not include the children node.
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"
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 @success	boolean	was the request successful
response @session	string	the search id of the requested search
server	url	the 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 @session	string	the session id of the requested search
hotel-poll @last	int	the 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 @success	boolean	was the request successfull
job @status	string	"working" or "done"
server	node	the server url to call for hotel-rooms poll
results @last	int	keep this number for the next poll (see request)
results @count	int	how many results were returned in this specific poll response
result @id	int	the identifier of the hotel this result belongs to. hotel information can be retreived from the static data
result @providers	string	comma separated string of providers available for this property
result @availableBoards	string	comma separated string of boards available for this property
result @hasPackageRate	boolean	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	double	the minimum commissionable price - appears only if such result is available
result/price @minNonCommissionablePrice	double	the minimum non-commissionable price - appears only if such result is available
result/price @minAllowedPrice	double	minimum price to be displayed for B2C environment (BAR rate)
min-room @board	board code	2 letter board code
min-room @commissionAble	boolean	can a commission be added to this price
min-room @roomCount	int	how many rooms are available
min-room	node	the room name
result/non-billable-price	node	availability coming from direct providers
price/combinations	node	in 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 @price	double	the total price of the combination
combination @currency	currency	3 letter ISO currency code
combination @commissionable	boolean	is the price commissionable
combination @billable	boolean	is the combination coming from your direct providers
combination @count	int	the number of rooms of that specific type. see note #8 for details
combination @pricePerRoom	boolean	is the price shown per room or total. see note #8 for details
special-deal	node	titles of the special deals available for the hotels

Notes

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.
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.
If there are no results from your direct providers, the non-billable-price node will not be returned
it is not allowed to add commission on top of non-commissionable items
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
the combination nodes are optional. in case our system cannot create a valid combination, no combinations will be returned
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"
"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.
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:

showRoomDescriptions - include room descriptions where available
showRoomBedding - include the room approximate bedding configuration (double/twin/triple/etc)
showRoomCategories - include the room approximate category (standard/suite/luxury/etc)

Comments

Resources	Search this site