API Objects_v7

Configuration

Field Type Description
emergency_contacts

ContactInfo array
Array of Technical Contact Info objects. Must be present. Must include technical contacts to be notified in case of urgent API issues.
info_contacts ContactInfo array Array of Contact Info objects. Must be present.
languages string array [Optional] Array of strings. This is a list of languages that the partner supports. Use the least specific language possible. e.g. If the partner supports all English regardless of country, list only “en”. Do not list all the currently supported variants of English. Tripadvisor may still send requests that do not use one of the partner’s supported languages. If this happens, the response can be any language the partner wants.
pref_hotels number [Optional] Preferred number of hotels per availability request. Tripadvisor may still request a different number of hotels in one request. This is a suggestion to Tripadvisor.
five_min_rate_limit number [Optional] Preferred rate limit, number of requests over 5 minutes. This is a suggestion to Tripadvisor.

ContactInfo

Field Type Description
full_name string
The full name of the contact
email string
The email address for the contact. Maximum of 256 characters.
phone_number string
The phone number for the contact. maximum of 50 characters.

InventoryHotel

Object used in required hotels array containing information about a particular hotel. 

Used in: hotel_inventory

Field Type Description
ta_id number [Optional] The Tripadvisor identification number for this hotel. This is used to aid our automated matching process but does not guarantee that a match will be found.
partner_id string The unique string that the parter uses to identify this hotel. Maximum length 30 characters. Required for mapping purposes and availability requests. Each hotel must have a unique partner_id.
name string
Name of the hotel, in English. Maximum 300 characters. Required for automated matching. May not be blank.
street string
Street address, in English. Maximum 300 characters. Field required for automated matching. May not be blank.
city string
City of the hotel, in English. Maximum 100 characters. Required for automated matching. May not be blank.
postal_code string
[Optional] Postal Code for the hotel. Maximum 20 characters. Highly suggested to assist automated matching.
state string
U.S. Properties: Required
Other Properties: Optional (Strongly recommended. Used to assist automated matching.)
 
State, province, or other mid-level geographic region of the hotel, in English. Maximum 100 characters.
country string
Country of the hotel, in English. Maximum 100 characters. Required for automated matching. May not be blank.
latitude number
[Optional] Latitude of the hotel.
longitude number
[Optional] Longitude of the hotel.
desc string
[Optional] Description of the hotel. Maximum 1000 characters.
amenities string
[Optional] Array of Strings. Each String corresponds to an amenity. See Hotel Amenities table at end of this document for all supported examples.
url string
The URL of the hotel on the partner site. Make this URL as specific as possible for the hotel and it must be unique in your inventory. Duplicate URLs in the Hotel Inventory will cause the feed import to fail. This URL must be accessible with a GET request. Maximum 2000 characters. Required for availability requests.
email string
[Optional] Email address of the hotel. Maximum 256 characters.
phone string
[Optional] Phone number of the hotel. Maximum 50 characters.
fax string
[Optional] Fax number of the hotel. Maximum 50 characters.
room_types Map of InventoryRoomType objects
[Optional] Map that use a short description as the key and an inventory room type object as the value. The maximum length of the short description is 100 characters. The room type short descriptions listed for a hotel must be distinct.

InventoryRoomType

Field Type Description
url string
[Optional] The URL of the hotel on the partner site. Make this URL as specific as possible. This URL must be accessible with a GET request. Maximum 2000 characters.
desc string
[Optional] Description of the room type. Maximum 1000 characters.

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 the 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 Discount array
[Optional] Array of Room Discount 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

An array of errors can be returned in any response. If the errors array is present, please include as many complete attributes in the response as available. The api_version is required.
 
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": 5,
    "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