/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).
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
            ]
        }
    ]
}
 

AvailabilityHotel

Field Type Description
hotel_id number
The Tripadvisor (ta_id) hotel id.
room_types Map of AvailabilityRoomType objects
Map that uses a short description as the key and an availability room type object as the value. The maximum length of the short description is 100 characters. The short description must be unique for each room type available in the hotel.

AvailabilityRoomType

Field Type Description
url string
The URL of the hotel on the partner site. This URL should go to a page that will show the price quoted and allow a user to book the room. Make this URL as specific as possible. This URL must be accessible with a GET request. The maximum length of the URL is 2000 characters. If possible, the URL should go to a webpage in the language specified by the lang parameter in the availability request.
price number
This price must be the total price of all rooms (or all beds if in a hostel) for the entire stay, all discounts applied.
 
This price will be divided by the number of rooms requested to present to the traveler.
 
In other words, this price can be calculated as the total of the "base-rate" (the Hotel-room-rate excluding all taxes and fees) for each room requested.
taxes number
All taxes paid at time of booking for the entire stay, all discounts applied. If the parter cannot separate the taxes from the fees, include the taxes in the fees attribute. Includes, but not limited to:
 
  • National Taxes (including VAT)
  • Local Taxes including state or city taxes
  • Nightly occupancy fees levied by a jurisdiction and paid in advance
  • Any other mandatory taxes that are collected at time of booking for any authority.
taxes_at_checkout number
All taxes paid at the location for the entire stay (between check in and checkout), all discounts applied. Any other mandatory taxes that are collected at time of booking for any authority and paid at checkout. Includes, but not limited to:
 
  • National Taxes (including VAT) paid at checkout
  • Local Taxes including state or city taxes paid at checkout
  • Nightly occupancy fees levied by a jurisdiction and paid at checkout
fees number
Mandatory fees paid at time of booking for the entire stay, all discounts applied. If taxes are not listed separately, this is the taxes and fees. Includes, but not limited to:
 
  • Booking fees charged by the booking agent paid at time of booking
  • Mandatory resort fees paid at time of booking
  • Mandatory service fees (e.g. gratuity) paid at time of booking
  • Any other fees not listed above and charged at time of booking
fees_at_checkout number
Mandatory fees for the entire stay paid at time of stay from check-in to check-out, all discounts applied. Includes, but not limited to:
 
  • Mandatory resort fees paid at checkout
  • Mandatory service fees (e.g. gratuity) paid at checkout
  • Any other required fees not included above and charged at checkout
final_price number
The price of the entire stay including taxes and fees, all discounts applied.
currency string
ISO 4217 currency code of the quoted price. All currencies codes must be in all caps to conform with the standard.
num_rooms number
Number of rooms of this exact room type required to fulfill the availability request.
discounts RoomDiscount array
[Optional] Array of RoomDiscount objects. See Room Discount section for structure. 0 or more Room Discounts may be included.
room_code string
[Optional] Generic room code representing the type of room. See Room Codes section for examples.
room_amenities string array
[Optional] Array of strings. See Hotel Amenities table at end of this document for all supported examples.

RoomCodes

Key Description Type
SINGLE Single (non-queen-sized bed in private room) string
QUEEN Queen (or equivalent) string
2_QUEEN 2 Queen (or equivalent) string
KING King (or equivalent) string
SUITE Suite string
SHARED Shared or dorm string
OTHER Other

string

RoomDiscount

Object that contains discount information for an available room. Values must be in the same currency as the parent AvailabilityRoomType object.
 
Field Type Description
marketing_text string
[Optional] Alphanumeric up to 50 characters. If not included default marketing text for this offer will be used. Language for marketing text should match the language indicated by the request (and response) in the core API.
is_percent boolean
Indicates whether the discount is a percent or value based discount.
amount number
Value of the discount. If is_percent is true, then this is the percent amount, otherwise it is the actual discount amount. Tripadvisor may truncate or round these values to the nearest integer (in the case of is_percent true, it means that 10.5% may be rounded to 11%) for display purposes.
price number
Positive value of the discount applied to price for the entire stay.
taxes number
Positive value of the discount applied to taxes for the entire stay.
taxes_at_checkout number
Positive value of the discount applied to taxes_at_checkout for the entire stay.
fees number
Positive value of the discount applied to fees for the entire stay.
fees_at_checkout number
Positive value of the discount applied to fees_at_checkout for the entire stay.
final_price number
Positive value of the discount applied to final_price for the entire stay.

Error

Object contained in an errors array. If the errors array is present, please include as many complete attributes in the response as available.
 
Field Type Description
error_code number
One of the error codes described below:
 
   
1 Unknown Error
2 Cannot Parse Request
3 Invalid Hotel ID. If partner_id is unknown, return this.
4 Timeout requested. Stops requests for the specified time.
5 Recoverable Error. Equivalent to http 503.
message string
[Optional] String describing the error. Used for debugging. Maximum length is 1000 characters.
timeout number
[Optional] Number of seconds we should stop sending requests for use with Error Code 4
hotel_ids number array
[Optional] Array of Hotels that this error applies to.
 
 

Example

In this case 2 hotels are requested. One has no availability and the other is for an invalid hotel ID.

{
    "api_version": 7,
    "hotel_ids": [
        258705,
        114134
    ],
    "start_date": "2013-07-01",
    "end_date": "2013-07-05",
    "lang": "en_US",
    "party": [{“adults": 2}],
    "errors": [
        {
            "error_code": 3,
            "message": "Hotel code 114134 is no longer used.",
            "hotel_ids": [
                114134
            ]
        }
    ]
}

Hotel Amenities

Here is the list of hotel amenity types that Tripadvisor supports:

  • ACTIVITIES_OLDER_CHILDREN
  • ACTIVITIES_YOUNG_CHILDREN
  • ADJOINING_ROOMS
  • ALL_INCLUSIVE
  • ALL_SUITES
  • APARTMENTS
  • BAR_LOUNGE
  • BATHROOMS
  • BEACH
  • BED_AND_BREAKFAST
  • BUSINESS_SERVICES
  • CAR_RENTAL_DESK
  • CASTLE
  • CONVENTIONS
  • CREDIT_CARDS_ACCEPTED
  • DATA_PORT
  • DINING
  • DRY_CLEANING
  • EARLY_ARRIVAL
  • ECONOMY
  • ELDER_ACCESS
  • EXTENDED_STAY
  • FAMILY_ROOMS
  • FARM_RANCH
  • FIRST_CLASS
  • FITNESS_CENTER
  • FOOD_AVAILABLE
  • FREE_BREAKFAST
  • FREE_CANCELATION
  • FREE_INTERNET
  • FREE_LOCAL_CALLS
  • FREE_PARKING
  • FREE_WIFI
  • GAME_ROOM
  • GOLF
  • HOT_TUB
  • KIDS_ACTIVITIES
  • KITCHEN_KITCHENETTE
  • KITCHENETTE
  • LATE_ARRIVAL
  • LATE_CHECK_OUT
  • LOCKERS_STORAGE
  • LOYALTY_REWARDS_AVAILABLE
  • LUXURY
  • MEALS_INCLUDED
  • MEETING_ROOM
  • MOTEL
  • NON_SMOKING
  • PARKING_AVAILABLE
  • PAID_PARKING
  • PETS_ALLOWED
  • PRIVATE_BATH
  • RESORT
  • RESTAURANT
  • ROOM_SERVICE
  • ROOM_WITH_A_VIEW
  • SHARED_BATH
  • SHUTTLE
  • STAIRS_ELEVATOR
  • STROLLER_PARKING
  • SUITES
  • SWIMMING_POOL
  • TENNIS_COURT
  • VALET_PARKING
  • WHEELCHAIR_ACCESS

Example: Multiple Rooms

This example demonstrates how to work with multiple parties and multiple rooms.

The hotel_availability response is exactly the same whether a single room (single object in the 'party' array) or multiple rooms (multiple objects in the 'party' array) are in the hotel_availability request.

There are, however, some considerations as follows.

Using this as an example party array in the request: [{"adults": 3},{"adults": 2}], you can follow these guidelines when constructing the response:

  1. When we request multiple rooms you should send all rooms that can accommodate the largest party.
  2. In this case, you should respond with all available rooms that can accommodate 3 adults or more. 
  3. You should not send rooms that can accommodate only 2 adults or less. 
  4. You should also send only the room types that have available a number of rooms equal or greater than the number of parties. In this case there are two parties.
  5. The prices should be the total for the number of days and party. We will then divide it and come up with the price per night and per guest. 

Another example party array might look as follows: [{"adults": 1},{"adults": 2},{"adults": 4}]
You should return all the room types that can accommodate the maximum number of adults (in this case 4) and have available at least the same number as the number of rooms requested (in this case 3).

Suppose that a hotel has a room type called “Double suite” that can accommodate 4 adults and a room type called “Large Double suite” that can accommodate 6. Both these room types could be returned in the response if the hotel has at least 3 rooms available of each.

All room types that can accommodate 1 or 2 adults maximum have to be excluded, and all room types that have less than 3 rooms available also have to be excluded.