/hotel_availability_v7

Availability requests are made by sending the parameters explained below in a POST request to the /hotel_availability path on your endpoint.
 
When the hotel availability results are returned, they are presented to the traveler. With this information, travelers can then proceed to the next step where they can find more room details.
 
(Note: The details shown in the following sample image are subject to change)
 
 

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: All your availability lookups must use your partner_id. The TripAdvisor ID can change as the site changes. The partner_url is mostly used 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.


This date corresponds with the timezone of the hotel/property.

If a request is sent with a date value that appears to be "in the past," then the correct response is the same as for "No availability" — returning '"num_hotels": 0, "hotels": []' in the reponse instead of returning an error.
end_date string The check-out date of the traveler. The date will be in the form YYYY-MM-DD.

This date corresponds with the timezone of the hotel/property.

If a request is sent with a date value that appears to be "in the past," then the correct response is the same as for "No availability" — returning '"num_hotels": 0, "hotels": []' in the reponse instead of returning an error.
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 specified by lang, they will not show up in Instant Booking.
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). If the currency the user will be charged in differs to the requested currency, always send the currency of charge. For example TripAdvisor requests USD but hotel is based in UK and charges in GBP, in that instance send GBP, currency conversion will be handled by TripAdvisor.
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" : "2015-07-01",
    "end_date" : "2015-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=2015-07-01&end_date=2015-07-03&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 (see appendix A). The language of the response.
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 are available, return an empty array. This field cannot be omitted.
errors Error array
[Optional] Array of errors.

 

Example Responses

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" : "2015-07-01",
    "end_date" : "2015-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=2015-07-01&end_date=2015-07-03&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",
  "lang": "en_US",
  "party" : [{“adults": 2}],
  "hotels": [],
}
 

Response for multiple availability including error

A sample response when 2 hotels are requested, and the first has availability while the second is for an invalid hotel ID. The details for both, successful and error, should be included in the response.

In this case 2 hotels are requested. One has availability and the second produces an error:

{
    "api_version": 7,
    "hotel_ids": [
        258705,
        114134
    ],
    "start_date": "2013-07-01",
    "end_date": "2013-07-05",
    "lang": "en_US",
    "party": [
        {
            "adults": 2
        }
    ],
    "currency": "USD",
    "user_country": "US",
    "device_type": "d",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "num_hotels": 1,
    "hotels": [
        {
            "hotel_id": 258705,
            "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.5,
                    "fees": 80
                }
            }
        }
    ],
    "errors": [
        {
            "error_code": 3,
            "message": "Hotel code 114134 is no longer used.",
            "hotel_ids": [
                114134
            ]
        }
    ]
}
 

Note 

Please note that TripAdvisor will always expect a response with "api_version": 7 in it, with the respective fields required in a v7 response. In order to transition from our current v5 to v7 (new) API, TripAdvisor may send you a request with the "api_version": 5 and transition these to "api_version": 7 in the near future. Please ensure that your v7 endpoint accepts the TripAdvisor request with variant "api_version" (both 5 and 7).