/hotel_availability_v7

Availability requests are sent by adding /hotel_availability to your endpoint and sending the parameters explained below in a POST request.

Request

http://partner-site.com/api_implementation/hotel_availability

ContentType: application/x-www-form-urlencoded

api_version=7
&hotels=[{"ta_id":97497,"partner_id":"229547","partner_url":"http://partner.com/deeplink/to/229547"},{"ta_id":97832,"partner_id":"id34234","partner_url":"http://partner.com/deeplink/to/id34234"}]
&start_date=2013-07-01
&end_date=2013-07-03
&party=[{“adults": 2}]
&lang=en_US
&currency=USD
&user_country=US
&device_type=d
&query_key=6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2

Parameters

Name Type Description
api_version number
The version of the API that this request is using.
hotels array
Array of JSON serializable hashes representing requested hotels.
 
key description type
ta_id Tripadvisor hotel IDs integer
partner_id Partner hotel ID string
partner_url Deeplink for this property. string

 

Example: hotels=[{"ta_id": 1128635, "partner_id": "1191", "partner_url": "http://partner.com/deeplink/to/1191"}]

Note: You must do all your availability lookups using your partner_id. The Tripadvisor ID can change as the site changes. The partner_url is mostly use for internal purposes. Partners implementing the API may ignore this parameter.
start_date string The check-in date of the traveler. The date will be in the form YYYY-MM-DD.
end_date string The check-out date of the traveler. The date will be in the form YYYY-MM-DD.
 
party array
Array of JSON objects representing number of adults and children traveling.
 
 
key description type
adults The number of adults staying in the room. integer
children [Optional] The ages of any children staying in the room. integer array

 

Each Party object represents a request for a separate room. For example, "party":[{"adults": 2}] is a request for 1 room that accommodates 2 adults, or "party":[{"adults": 3},{“adults": 2, "children": [9,5]}] is a request for 1 room for 3 adults and 1 room for 2 adults and 2 child for a total of 2 rooms.
lang string Language code (see Supported Languages). The language that Tripadvisor would prefer that the partner return with. If the partner does not have the language of the request, they can return a less specific language. e.g. If the request is asking for de_AT, then the response can be de. If the partner does not have the language, they may return a response with any language.
query_key string String useful for debugging. It is recommended for this value to be logged.
currency string [Not always present] ISO 4217 currency code. All prices, taxes, fees, and discount amounts should be returned in this requested currency. If this is not possible, the currency should match the one seen by a user from the given user_country if present (see below).
user_country string [Not always present] ISO 3166-1 alpha-2 country code corresponding to the user making this request. If present local taxes and fees must be included and the currency must match the one seen by a user from this country visiting your website. If this is not possible, return the local currency of the hotel. This parameter is required to be supported if pricing differs based on the country where the user makes the request.
device_type string [Not always present] Identifies the user’s device type. Takes values “d”, “m” or “t” corresponding to DESKTOP, MOBILE, or TABLET, respectively. This value is required if pricing differs by device type.

Response

ContentType: application/json

{
    "api_version" : 7,
    "hotel_ids" : [97497],
    "start_date" : "2013-07-01",
    "end_date" : "2013-07-03",
    "party" : [{“adults": 2}],
    "currency" : "USD",
    "user_country" : "US",
    "device_type" : "d",
    "query_key" : "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "lang" : "en_US",
    "num_hotels" : 1,
    "hotels" :
        [
            {
                "hotel_id": 97497,
                "room_types":
                    {
                        "Fenway Room":
                            {
                                "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room?start_date=2013-07-01&end_date=2013-07-05&num_adults=2",
                                "price": 178.50,
                                "fees": 80,
                                "fees_at_checkout": 0,
                                "taxes": 20,
                                "taxes_at_checkout": 0,
                                "final_price": 278.50,
                                "discounts":
                                    [
                                        {
                                            "marketing_text": "10% off entire stay during July",
                                            "is_percent": true,
                                            "amount": 10,
                                            "price": 20,
                                            "fees": 0,
                                            "fees_at_checkout": 0,
                                            "taxes": 0,
                                            "taxes_at_checkout": 0,
                                            "final_price": 20
                                        },
                                        {
                                            "marketing_text": "1% off web special",
                                            "is_percent": true,
                                            "amount": 1,
                                            "price": 2,
                                            "fees": 0,
                                            "fees_at_checkout": 0,
                                            "taxes": 0,
                                            "taxes_at_checkout": 0,
                                            "final_price": 2
                                        },
                                        {
                                            "marketing_text": "Waive property fee",
                                            "is_percent": false,
                                            "amount": 25,
                                            "price": 0,
                                            "fees": 25,
                                            "fees_at_checkout": 0,
                                            "taxes": 0,
                                            "taxes_at_checkout": 0,
                                            "final_price": 25
                                        }
                                    ],
                                "currency": "USD",
                                "num_rooms": 1,
                                "room_code": "SINGLE",
                                "room_amenities":
                                    [
                                        "BREAKFAST_AND_LUNCH_INCLUDED",
                                        "ROOM_WITH_A_VIEW"
                                    ]
                            }
                    }
            }
        ]
}

Properties

Name Type Description
api_version number
The version of the API that this request is using.
hotel_ids number array

Echo the ta_ids (not partner_ids) requested by Tripadvisor in the 'hotels' object.
start_date string
Echo the start date requested by Tripadvisor. Use the same format as described in request.
end_date string
Echo the end date requested by Tripadvisor. Use the same format as described in request.
party array
Echo the party array requested by Tripadvisor. Use the same format as described in request.
lang string
Language code. The language of the response. See supported Languages.
query_key string
Echo the query key in the request by Tripadvisor.
currency string
Echo the currency in the request by Tripadvisor.
user_country string
Echo the user country in the request by Tripadvisor.
device_type string
Echo the device type in the request by Tripadvisor.
num_hotels number
Number of hotels that had availability. This should equal the length of the hotels array.
hotels AvailabilityHotel array
Array of availability hotel objects. Include only hotels with availability. If no hotels available, return an empty array. This field cannot be ommitted.
errors Error array
[Optional] Array of errors.

No availability response for multi-hotel request

A sample response when there is a multi-hotel request and there is no availability for one of the hotels. When a requested hotel is not available for booking, it is simply not included in the hotels field of the response but just in the hotel_ids array. There is no need to return any errors, messages, or availability_hotel objects with empty room_types. The absence of a hotel in the response is interpreted as having no availability for the parameters requested.

In this case 2 hotels are requested. One has availability and the other has none.

 {
    "api_version" : 7,
    "hotel_ids" : [
           97497, 
           114134
    ],
    "start_date" : "2013-07-01",
    "end_date" : "2013-07-03",
    "party" : [{“adults": 2}],
    "currency" : "USD",
    "user_country" : "US",
    "device_type" : "d",
    "query_key" : "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "lang" : "en_US",
    "num_hotels" : 1,
    "hotels" :
        [
            {
                "hotel_id": 97497,
                "room_types":
                    {
                        "Fenway Room":
                            {
                                "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room?start_date=2013-07-01&end_date=2013-07-05&num_adults=2",
                                "price": 178.50,
                                "fees": 80,
                                "fees_at_checkout": 0,
                                "taxes": 20,
                                "taxes_at_checkout": 0,
                                "final_price": 278.50,
                                "discounts":
                                    [
                                        {
                                            "marketing_text": "10% off entire stay during July",
                                            "is_percent": true,
                                            "amount": 10,
                                            "price": 20,
                                            "fees": 0,
                                            "fees_at_checkout": 0,
                                            "taxes": 0,
                                            "taxes_at_checkout": 0,
                                            "final_price": 20
                                        },
                                        {
                                            "marketing_text": "1% off web special",
                                            "is_percent": true,
                                            "amount": 1,
                                            "price": 2,
                                            "fees": 0,
                                            "fees_at_checkout": 0,
                                            "taxes": 0,
                                            "taxes_at_checkout": 0,
                                            "final_price": 2
                                        },
                                        {
                                            "marketing_text": "Waive property fee",
                                            "is_percent": false,
                                            "amount": 25,
                                            "price": 0,
                                            "fees": 25,
                                            "fees_at_checkout": 0,
                                            "taxes": 0,
                                            "taxes_at_checkout": 0,
                                            "final_price": 25
                                        }
                                    ],
                                "currency": "USD",
                                "num_rooms": 1,
                                "room_code": "SINGLE",
                                "room_amenities":
                                    [
                                        "BREAKFAST_AND_LUNCH_INCLUDED",
                                        "ROOM_WITH_A_VIEW"
                                    ]
                            }
                    }
            }
        ]
}

No availability response for a single hotel request

A sample response when there is just a request for a single hotel's availability and there is no availability for that hotel. When a requested hotel is not available for booking, it is simply not included in the hotels field of the response but just in the hotel_ids array. There is no need to return any errors, messages, or availability_hotel objects with empty room_types. The absence of a hotel in the response is interpreted as having no availability for the parameters requested.

In this case 1 hotel is requested. It doesn't have availability

{
  "api_version": 7,
  "hotel_ids": [
       258705
  ],
  "start_date": "2013-07-01",
  "end_date": "2013-07-05",
  "party" : [{“adults": 2}],
  "lang": "en_US"
  "currency" : "USD",
  "user_country" : "US",
  "device_type" : "d",
  "query_key" : "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
  "num_hotels": 0,
  "hotels": []
}