Deprecated API

The Legacy Pull Buyers API, our initial Buyers API launched in 2012, is now deprecated and should not be further developed. Instead, we introduced the Hotel-X Buyers API in 2017, which serves as the sole API for new Buyers looking to integrate and participate in our Marketplace.

Hotel List

The Hotel List method returns a comprehensive hotel list from a supplier's access to the Buyer, granting access to all the properties configured by the Seller for a given set of credentials. The returned fields include: Hotel Code, GiataId, Name, Address, ZipCode, Contact, CategoryCode etc.

caution

The amount of information and content returned might vary between Sellers.

HotelList Request

<soapenv:Envelope xmlns:soapenv = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns = "http://schemas.xmltravelgate.com/hub/2012/06" xmlns:wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <soapenv:Header>
      <wsse:Security>
         <wsse:UsernameToken>
            <wsse:Username>username</wsse:Username>
            <wsse:Password>password</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <ns:HotelList>
         <ns:hotelListRQ>
            <ns:timeoutMilliseconds>20000</ns:timeoutMilliseconds>
            <ns:version>1</ns:version>
            <ns:providerRQ>
               <ns:code>suppliercode</ns:code>
               <ns:id>1</ns:id>
               <ns:rqXML>
                  <HotelListRQ xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
                     <timeoutMilliseconds>19700</timeoutMilliseconds>
                     <source>
                        <languageCode>en</languageCode>
                     </source>
                     <filterAuditData>
                        <registerTransactions>true</registerTransactions>
                     </filterAuditData>
                     <Configuration>
                        <User>user</User>
                        <Password>password</Password>
                        <UrlAvail>www.supplier.com/avail</UrlAvail>
                        <UrlReservation>www.supplier.com/reservation</UrlReservation>
                        <UrlValuation>www.supplier.com/valuation</UrlValuation>
                        <UrlGeneric>www.supplier.com/generic</UrlGeneric>
                        <Parameters>
                           <Parameter key = "UrlListHotels" value = "http://www.supplier.com/ListHotels"></Parameter>
                           <Parameter key = "Access" value = "22334"></Parameter>
                        </Parameters>
                     </Configuration>
                  </HotelListRQ>
               </ns:rqXML>
            </ns:providerRQ>
         </ns:hotelListRQ>
      </ns:HotelList>
   </soapenv:Body>
</soapenv:Envelope>

Request Data Breakdown

info

Check the values you need to add in the header and common elements.

HotelList request does not require any elements.

How to Paginate Responses

The Legacy Pull Buyers API provides paginated responses to handle cases where the number of hotels from the selected supplier exceeds 200.000. The default response page contains a maximum of 200.000 hotels, but you can specify the number of objects returned per page using the ContinuationToken and the attribute expectedRange fields in the request.

To include the ContinuationToken in your request, all you need to do is:

1. Add the ContinuationToken and expectedRange fields to the request.

2. After receiving a response, you will only receive a portion of the full list. To access the next page, simply copy the ContinuationToken tag from the response and include it in your next request. This will allow you to obtain a new set of objects in the following response.

3. Repeat these steps until the token is no longer included in the response.

note

If the client requests 1000 hotels, the response may contain a range between 1000 to 1999 hotels.

1. Indicate the ContinuationToken and expectedRange in the Request

First, in your hotel list request you will add ContinuationTokentoken field and specify in expectedRange field the number of hotels expected to receive in the response:

<HotelListRQ xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">                
  <ContinuationToken expectedRange = "1000"></ContinuationToken>
</HotelListRQ>

2. You will recieve the Response

You will obtain a response with 1000 hotels per page:

<HotelListRS xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">                
  <ContinuationToken expectedRange = "1000">&lt;?xml version="1.0" encoding="utf-16"?&gt;&lt;ContinuationToken&gt;&lt;ContinuationToken&gt;&lt;Version&gt;2.0&lt;/Version&gt;&lt;Type&gt;Table&lt;/Type&gt;&lt;NextPartitionKey&gt;1!24!bG93Y29zdGhvbGlkYXlfWk1U&lt;/NextPartitionKey&gt;&lt;NextRowKey&gt;1!40!bG93Y29zdGhvbGlkYXlfWk1UXzBoNFIlMjNvcXBr&lt;/NextRowKey&gt;&lt;TargetLocation&gt;Primary&lt;/TargetLocation&gt;&lt;/ContinuationToken&gt;&lt;/ContinuationToken&gt;</ContinuationToken>
</HotelListRS>

3. Add the Token in the Request

This token should be used as input in your next hotel list request, inside the ContinuationToken field:

<HotelListRQ xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">                
  <ContinuationToken>&lt;?xml version="1.0" encoding="utf-16"?&gt;&lt;ContinuationToken&gt;&lt;ContinuationToken&gt;&lt;Version&gt;2.0&lt;/Version&gt;&lt;Type&gt;Table&lt;/Type&gt;&lt;NextPartitionKey&gt;1!24!bG93Y29zdGhvbGlkYXlfWk1U&lt;/NextPartitionKey&gt;&lt;NextRowKey&gt;1!40!bG93Y29zdGhvbGlkYXlfWk1UXzBoNFIlMjNvcXBr&lt;/NextRowKey&gt;&lt;TargetLocation&gt;Primary&lt;/TargetLocation&gt;&lt;/ContinuationToken&gt;&lt;/ContinuationToken&gt;</ContinuationToken>
</HotelListRQ>

HotelList Response

The response to the previous request is a list of hotels from our database that corresponds to the supplier specified in the request.

<HotelListRS xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
   <UpgradeUTCDate>2016-10-18T13:18:03+02:00</UpgradeUTCDate>
   <Hotels>
      <Hotel>
         <Code>5</Code>  
         <ProviderCode>27</ProviderCode>                          
         <GiataId source = "http://urlGiata">1200</GiataId>
         <Name>BADAJOZ</Name>
         <Address>CTRA.NACIONAL V, KM 393</Address>
         <Airports>
            <Airport>
               <IATACode>BJZ</IATACode>
            </Airport>
         </Airports>
         <Town>BADAJOZ</Town>
         <ZipCode>06002</ZipCode>
         <CountryISOCode>ES</CountryISOCode>
         <AvailDestination code = "06" name = "BADAJOZ"/>
         <GeographicDestination code = "06" name = "BADAJOZ" avail = "true"/>
         <Latitude>38.893839</Latitude>
         <Longitude>-7.014112</Longitude>
         <Contact>
            <Email>badajoz@xxx.com</Email>
            <Telephone>91425891</Telephone>
            <Fax>910200200</Fax>
         </Contact>
         <CategoryCode>4 Estrellas</CategoryCode>
         <PaymentOptions cash="false" bankAcct="false">
            <Cards>
               <Card code="VI"/>
               <Card code="AX"/>
               <Card code="CA"/>  
            </Cards> 
         </PaymentOptions>               
         <ExclusiveDeal>true</ExclusiveDeal>     
         <PropertyCategory>
            <Code>1</Code>
            <Name>Hotel</Name>             
         </PropertyCategory>                 
      </Hotel>
   </Hotels>
</HotelListRS>

Response Data Breakdown

Element	Rel	Type	Description
HotelListRS/UpgradeUTCDate	1	DateTime	Indicates the update date of the information in UTC format.
HotelListRS/Hotels	0..n
Hotels/Hotel	0..n
Hotel/Code	1	String	Internal code to perform availability and/or supplier code.
Hotel/ProviderCode	0..1	String	Internal code established by the supplier (see MetaData).
Hotel/GiataId	0..1	String	Giata code
@source	0..1	String	Giata url
Hotel/Name	1	String	Hotel name
Hotel/Address	1	String	Hotel address
Hotel/Airports	0..1
Airports/Airport	1..n
Airport/IATACode	1	String	IATA airport Code (airport near the hotel).
Hotel/Town	1	String	Town
Hotel/ZipCode	0..1	String	ZipCode
Hotel/CountryISOCode	1	String	CountryISOCode
Hotel/AvailDestination	0..1
@code	1	String	Avail destination code (lowest destination level).
@name	1	String	Avail destination name (lowest destination level).
Hotel/GeographicDestination	1
@code	1	String	Geographic Destination code (lowest destination level).
@name	1	String	Geographic Destination name (lowest destination level).
@avail	1	Boolean	Indicates if it is allowed in availability.
Hotel/Latitude	0..1	String	Latitude. Format is Decimal Degrees (e.g. 37.207295).
Hotel/Longitude	0..1	String	Longitude. Format is Decimal Degrees (e.g. -7.23768).
Hotel/Contact	0..1
Contact/Email	0..1	String	Contact email
Contact/Telephone	0..1	String	Contact telephone
Contact/Fax	0..1	String	Contact fax
Hotel/CategoryCode	1	String	Hotel category code.
Hotel/Type	0..1	String	Hotel Type codes Code Name H Hotel A Apartment AH Apartment Hotel C Club AT Agrotourism HS Hostel CA House V Ville B Bungalows D Disco Club
Hotel/PaymentOptions	0..1		Type of cards allowed by the supplier. This tag is only mandatory if payment type is different than MerchantPay.
@cash	1	Boolean	Cash indicates whether payment will be made in cash (true) or by card (false).
@bankAcct	1	Boolean	BankAcct specifies whether payment will be made via bank transfer (true) or not (false).
PaymentOptions/Cards	1
Cards/Card	1..n		Type of card allowed.
@code	1	String	Credit Card codes Code Name VI Visa AX American Express BC BC Card CA MasterCard CB Carte Blanche CU China Union Pay DS Discover DC Diners Club T Carta Si R Carte Bleue N Dankort L Delta E Electron JC Japan Credit Bureau TO Maestro S Switch EC Electronic Cash EU EuroCard TP Universal air travel card OP optima ER Air Canada/RnRoute XS access O others
Hotel/ExclusiveDeal	0..1	Boolean	Indicates that the Hotel has an Exclusive Deal.
Hotel/PropertyCategory	0..1		Hotels property type. Similar to Type, but on supplier’s side.
PropertyCategory/Code	1	String	Supplier’s property code.
PropertyCategory/Name	1	String	Supplier’s property name.