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 chooses; however, TripAdvisor will not allow this property to be displayed in Instant Booking for that particular locale.
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	State is required for all addresses from the United States (US), Australia (AU), Canada (CA), Malaysia (MY) and Philippines (PH). For addresses from the United Kingdom (GB), New Zealand (NZ), Ireland (IE), Singapore (SG), South Africa (ZA), France (FR) and others the state is optional. 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 array	[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 Inventory 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 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.

Used in: hotel_inventory, hotel_availability, booking_availability

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 in the InventoryHotel object as part of the /hotel_inventory call. Please do not use this list in the /booking_availability call, as these will be rejected. For the /booking_availability call, use the Supported Amenity codes.

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

HotelDetails

Required object containing information about the hotel in general, such as address. This information will be presented to customer during booking. Used in: booking_availability, booking_submit (Reservation) and booking_verify (Reservation)

Field

Type

Description

name

string

The name of this hotel

address1

string

Street Address

address2

string

[Optional] Additional address information

city

string

Town or city

state

string

[Optional] State or province

postal_code

string

[Optional] Zip code or postal code

country

string

ISO 3166 country code

latitude

number

[Optional] Latitude coordinate

longitude

number

[Optional] Longitude coordinate

phone

string

Telephone number of the hotel

url

string

URL for general hotel contact, not a booking page.

hotel_amenities

object

Array of integer codes where each code corresponds to a hotel level amenity. These amenities are not tied to a specific room but are applicable to the hotel, e.g. “24 hour airport shuttle.” Relevant amenity codes are listed in Appendix B and were derived from from the OpenTravel Hotel Amenity Code List.

Standard amenities are an integer array. Custom amenities specified via string array

photos

Photo array

URLs for photos of the hotel to be displayed during the booking process. Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.

If no photos are availabile, an empty array should be returned.

checkinout_policy

string

Text describing the check-in/check-out policy for the hotel. Include items needed at check-in, e.g. “Please present valid identification and credit or debit card used for booking.” Should be in the language indicated by the 'lang' parameter. Max length 1000 characters.

checkin_time

string

HH:MM Specified in local time zone.

checkout_time

string

HH:MM Specified in local time zone.

hotel_smoking_policy

object

Use one of the following options (derived from HAC, GRI tables of OTA):

47	All rooms non-smoking
198	Non-smoking room (generic)
268	All public areas non-smoking
900201	Smoking permitted in designated areas and rooms

Allow for custom smoking_policy info (similar to all the custom fields above)

child_policy

string

[Optional] Text to indicate special considerations for children. For example “Adult only resort” or “Children over 5 years.” If no information is provided, default to null.

pet_policy

string

[Optional] Based on OTA code table (PET), added a “900401 - Pets not allowed” to the list. Omit from response if you cannot provide this information:

1	Cats only
2	Dogs only
3	Large domestic animals
4	Midsize domestic animals
5	Small domestic animals only
6	Working animals only
7	All pets
8	Small domestic animals
9	Working animals
10	Domestic pets
900401	Pets not allowed

parking_shuttle

object

[Optional] Derived from OTAs code list of HAC (hotel amenities) describing parking and/or shuttle availability options to major transportation

41	Free airport shuttle
42	Free parking
53	Indoor parking
63	Off-site parking
64	Outdoor parking
68	Parking
75	Recreational vehicle parking
94	Truck parking
97	Valet parking
116	Accessible parking
171	Parking fee managed by hotel
184	Parking lot
185	Parking deck
186	Street side parking
189	Motorcycle parking
192	Bus parking
216	Long term parking
230	Secured parking
282	Airport shuttle service
293	Parking - controlled access gates to enter parking area
305	Shuttle to local businesses
306	Shuttle to local attractions
329	Limited parking
331	No parking available

extra_bed_policy_hotel

string

[Optional] Provide information on additional beds and configurations available.

Example: “Rollaway bed available”, “Crib”, “Extra beds available on request”

extra_fields

object array

[Optional] An array of extra fields the partner wants to display.

Photo

Field	Type	Description
url	string	URL for the photo. Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.
thumbnail_url	string	[Optional] URL for thumbnail of photo.
caption	string	[Optional] Caption for the photo. Should be in the language indicated by the 'lang' parameter in the request.
width	number	[Optional] Width in pixels of full size photo.
height	number	[Optional] Height in pixels of full size photo.

Customer

Field	Type	Description
first_name	string	First name of the user booking the reservation.
last_name	string	Last name of the user booking the reservation.
phone_number	string	Phone number of the user booking the reservation.
email	string	Email of the user booking the reservation.
country	string	ISO 3166 country code of the user booking the reservation.

RoomStay

Object to describe details of the primary traveler and party for a room.

Used in: Reservation

Field	Type	Description
party	Party object	An object containing the number of adults and children staying in this room.
traveler_first_name	string	First name of the primary traveler staying in this room.
traveler_last_name	string	Last name of the primary traveler staying in this room.

PaymentMethod

Request object describing the payment method of the booking.

Used in: booking_submit

Field	Type	Description
card_type	string	The type of credit or debit card used. Must be one of the following: Visa MasterCard AmericanExpress Discover TripAdvisor requires a credit or debit card at time of booking not only to support a hotel’s guarantee policy but also to reduce fraud. In the case where a hotel does not require a credit or debit card guarantee, it will be up to the partner to either pass or not pass the card details to the hotel.
card_number	string	The credit or debit card number.
cardholder_name	string	The name on the credit or debit card.
expiration_month	string	The expiration month as a two-digit string (e.g. 01, 02, .. 12)
expiration_year	string	The expiration year as four digit string.
cvv	string	The cvv number.
billing_address	Address object	The billing address of the card.

Address

Field	Type	Description
address1	string	Street address
address2	string	[Optional] Additional address information
city	string	Town or city
state	string	State or province State is required for all addresses from the United States (US), Australia (AU), Canada (CA), Malaysia (MY) and Philippines (PH). For addresses from the United Kingdom (GB), New Zealand (NZ), Ireland (IE), Singapore (SG), South Africa (ZA), France (FR) and others the state is optional.
postal_code	string	U.S. Address: Required Other Address: Optional Zip code or postal code
country	string	ISO 3166 country code

Reservation

Used in: booking_submit, booking_verify

Field	Type	Description
reservation_id	string	Unique partner identifier for the reservation.
status	string	The status of the reservation, must be one of: Booked Cancelled CheckedIn CheckedOut
confirmation_url	string	Deep link to the reservation confirmation page. The confirmation URL is displayed to the traveler after a booking has been confirmed. In addition, it is also displayed in the "My Bookings" page of the TripAdvisor account for the traveler. Because this URL is displayed to the traveler, it therefore must be a link to a page owned by the booked property which: 1. displays any relevant confirmation codes, and, 2. confirms the dates, rooms and final price for the booking. Example: "confirmation_url": "http://bookings.bookingengine.com/Channels/BestHotel/confirm.jsp?mode=show&bid=8507809&bCode=9914&lang=en&currency=USD"
checkin_date	string	The check-in date of the traveler. The date will be in the form YYYY-MM-DD.
checkout_date	string	The check-out date of the traveler. The date will be in the form YYYY-MM-DD.
partner_hotel_code	string	The partner specific code for this hotel. In a /booking_submit request this should be the same as in the request.
hotel	HotelDetails object	An object containing information about the hotel booked.
customer	Customer object	An object containing the customer booking the reservation.
rooms	RoomStay array	An array of RoomStay objects.
legal_text	string	Optional. Text describing any legal requirements for the hotel. If a partner has a single policy across all bookings, return the partner's legal text here. For example: Terms of Service and Privacy Policy.
comments	string	Optional. Generic reservation comments field.
receipt	Receipt object	Pricing information on the reservation.

Receipt

Field	Type	Description
line_items	LineItem array	An array containing line items detailing each charge. An array of LineItem objects will contain a separate LineItem for each of rate, tax, and fee types.
final_price_at_booking	Price object	An object containing the entire price to be paid at time of booking, including taxes and fees. This will be used to validate the line items.
final_price_at_checkout	Price object	An object containing the entire price to be paid at time of stay, including taxes and fees. This will be used to validate the line items. If the full price is paid at the time of booking, this element must still be included, with an amount of 0 or 0.00.

Problem

Response object that is optional for a successful booking but required when there is an issue with the booking.

Used in: booking_submit, booking_verify

Field	Required	Type	Description	Example
problem	Required	string	One of the supported problem types.	"problem" : "MissingEmail"
explanation	Required	string	Partner-specific message to be displayed to the user providing details of the problem, and should be in the language of the 'lang' parameter of the request.	"explanation" : "The e-mail address is missing"
detail	Optional	string	Partner-specific message providing details of the problem that will not be displayed to the user. Intended for logging purposes.	"detail" : "E-mail address missing"

Problem Types

Used in: Problem

Here is the list of problem types that TripAdvisor supports:

CreditCardDeclined
CreditCardTypeNotSupported
MissingTravelerFirstName
MissingTravelerLastName
MissingEmail
MissingReservationFirstName
MissingReservationLastName
MissingWorkPhone
MissingHomePhone
MissingAddress
MissingCity
MissingStateProvince
MissingCountry
MissingPostalCode
MissingCardholderName
InvalidTravelerFirstName
InvalidTravelerLastName
InvalidEmail
InvalidReservationFirstName
InvalidReservationLastName
InvalidWorkPhone
InvalidHomePhone
InvalidAddress
InvalidCity
InvalidStateProvince
InvalidCountry
InvalidPostalCode
InvalidCardholderName
UnknownUserProblem
RoomNotAvailable
PartnerDown
PartnerTimeout
AgentAttention
PropertyNotSupported
PriceMismatch
UnknownReference
UnknownPartnerProblem

Example

This table illustrates different problem situations and how they map to the listed Problem Types.

Example	Problem Type	Note
Missing required values:
first_name	MissingTravelerFirstName
last_name	MissingTravelerLastName
card_type	CreditCardDeclined	The explanation field must note this value is missing.
card_number	CreditCardDeclined	The explanation field must note this value is missing.
expiration_month	CreditCardDeclined	The explanation field must note this value is missing.
expiration_year	CreditCardDeclined	The explanation field must note this value is missing.
cvv	CreditCardDeclined	The explanation field must note this value is missing.
country	MissingCountry
partner_data	UnknownReference	The explanation field must note this value is missing.
Invalid values:
email	InvalidEmail
country	InvalidCountry	This applies if the country code is incorrect.
expiration_month	CreditCardDeclined	The explanation field must note this value is invalid. Note that the required format is 'MM', where the allowed range of values is for 'MM' is 01-12.
expiration_year	CreditCardDeclined	The explanation field must note this value is invalid. Note that the required format is '20YY', where the allowed range of values is from the current year to 2099.
(expiration_month && expiration_year) < Today	CreditCardDeclined	The explanation field must note this value is invalid. The date represented by the combination of Expiry Month and Expiry Year must not be in the past.
card_number	CreditCardDeclined	The explanation field must note this value is invalid. The credit or debit card number must pass the Luhn algorithm.
cvv	CreditCardDeclined	The explanation field must note this value is invalid. For AmEx the CVV is a four digit number. For Visa, MasterCard, and Discovery the CVV is a three digit number. No alphabetic characters or other symbols allowed.
partner_hotel_code	UnknownReference	The explanation field must note this value is invalid.
reservation_id	UnknownReference	The explanation field must note this value is invalid.
Incorrect Data Types:
phone_number	InvalidHomePhone	The phone number must be sent as a string containing the allowed characters for phone numbers.
card_number	CreditCardDeclined	This value must be a string containing digits only.
expiration_month	CreditCardDeclined	This value must be a string containing two digits.
expiration_year	CreditCardDeclined	This value must be a string containing four digits.
cvv	CreditCardDeclined	This value must be a string containing four digits if the value of "card_type" is "AmericanExpress". It must be three digits if the value of "card_type" is "Visa","MasterCard", or "Discover".

Customer Support

This object contains details that the customer can contact for support with the booking. This object must be present for successful API responses, in addition to failure state API responses (for example, if a booking_submit call fails this object must be included).

A phone number that the customer can contact for support is required in the phone_numbers array.

Used in: booking_availability, booking_submit, booking_verify, booking_cancel

Field	Type	Description
phone_numbers	Contact array	An array of customer support phone numbers.
emails	Contact array	An array of customer support emails.
urls	Contact array	An array of customer support urls.

Contact

Field	Type	Description
contact	string	The contact detail, e.g. phone number or email address.
description	string	A description for this contact.

LineItem

An array of LineItem objects will contain a separate LineItem for each of rate, tax, and fee types.

Field	Type	Description
price	Price object	An object containing the price of the line item.
type	string	Describes the charge. Must be one of these values: rate tax fee
paid_at_checkout	boolean	true if the charge will be paid at the time of stay. false if it will be paid at time of booking.
description	string	A textual description for the charge. This may be displayed to end users, and should be in the language indicated by the 'lang' parameter in the response.

The following example shows how an array of LineItem objects can be used to represent the various pricing components of a room price. Let's say the following components make up a room price:

Base rate: 75 EUR
Taxes: 20 EUR
Fees: 5 EUR

The hotel requires that these components be paid as follows:

final_price_at_booking: 25 EUR (hotel charges taxes and fees immediately when booking was made)
final_price_at_checkout: 75 EUR (balance is paid at checkout)

Here is what the corresponding line_items for this price would look like:

line_items: [
  {
    "price": {
        "amount": 75,
        "currency": "EUR"
    },
    "type": "rate",
    "paid_at_checkout": true,
    "description": "Base price"
  },
  {
    "price": {
        "amount": 5,
        "currency": "EUR"
    },
    "type": "fee",
    "paid_at_checkout": false,
    "description": "Resort fee"
  },
  {
    "price": {
        "amount": 20,
        "currency": "EUR"
    },
    "type": "tax",
    "paid_at_checkout": false,
    "description": "Total tax amount"
  }
]

Price

Field	Type	Description
amount	number	The value of the price.
currency	string	ISO 4217 currency code for the price.