API Objects

  

RoomTypes

Field

 Type Description
room_types HotelRoomType map

Affected when all flags below are true:

  • multiple_room_rates

A map from room type keys to room types. At minimum, there must exist a room type entry for every unique room_type_key used in room_rates RoomRate objects.

 

Field Type Description
persistent_room_type_code

string
This is optional.
This
code identifies unique room types. We expect that this code persists across future availability calls. The combination of persistent_room_type_code and partner_hotel_code must be unique.
name string
The name of this room type. Room names must summarize 1-2 significant selling points for the room, ideally in less than 50 characters. For example, you can include the bed type configuration information and the room view in the name (e.g. “One Bedroom Suite, One King Bed”, “Courtyard King”, “Garden View Room, King”, “King Studio”); or simply match the room name to brand.com
 
If a room name consists of only numbers and symbols, or is shorter than 4 characters, it will be blocked from Instant Booking.
description string

Provide when all flags below are true:

  • room_type_details
  • text
Longer room description. This will be displayed to end users, and should be in the language indicated by the lang parameter. Ideal room descriptions are 250-400 characters in length. They are written in third person voice and highlight selling point for the room. For example, "This one-bedroom suite has a king bed. This corner suite also features a separate living room with a sofa bed, a well-equipped kitchen with complimentary grocery delivery services, and Paul Mitchell bath products."

Language specific requirements will be applied. For example, if a room description in English consists of only numbers and symbols, or is shorter than 4 characters, it may be blocked. See supported HTML tags.
photos Photo array

Provide when all flags below are true:

  • room_type_details
  • photos

List of photos of the room.

Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.
room_amenities object

Provide when all flags below are true:

  • room_type_details

Array of number codes. Each code corresponds to an amenity for the OpenTravel Hotel Amenity Code List.  A map of the standard room amenities is listed under the Supported Amenities section. Hotel and room amenities are provided in separate parts of the response, and should not overlap. For example, amenities that have no bearing on the room (e.g. “free parking”) should not be included as a room amenity, but rather as a hotel amenity.  We recommend rooms offer a minimum of 10 amenities.

The standard amenities will be returned as an integer array. If an amenity does not exist in the Supported Amenities list, then the Connectivity Partner may provide their own values. Return "custom":[ ] if no custom list exists.

Example: 
{ "standard": [1 ,2, 5, 20, 60,], "custom": ["myamenity1", "myamenity2"] }
max_occupancy map of string:int

Provide when all flags below are true:

  • room_type_details

Maximum number of guests permitted in the room. {"number_of_adults": <num_adult>, "number_of_children": <num_child>}.

Example: {"number_of_adults": 3, "number_of_children": 2 }.  
room_size map of string:int

Provide when all flags below are true:

  • room_type_details

 Area of room in given units. If given, both value and unit are required.
bed_configurations object

Provide when all flags below are true:

  • room_type_details 

A list of one or more possible configurations. 

In order for a bed configuration to be valid, at least one element must exist in either the standard array or custom array. 
Two or more configurations mean that the room could be configured to contain either (any) of these set ups. 

For example, the following snippet illustrates how to represent two bed configurations, either one king bed OR two double beds:

"bed_configurations": [
  { "standard": [ { "count": 1, "code": 3 } ] },
  { "standard": [ { "count": 2, "code": 1 } ] }
]

The following snippet illustrates how to represent one bed configuration, with a crib AND a custom bunk bed:

"bed_configurations": [
  { "standard": [ { "count": 1, "code": 900302 } ],
    "custom": [ { "count": 1, "name": "Bunk bed"} ] }
]

 

Specify the bed types for a room, and if needed multiple bed configurations available. The type of bed provided is based on OpenTravel BED code table: 

1 Double
2 Futon
3 King
4 Murphy Bed
5 Queen
6 Sofa Bed
7 Tatami Mats
8 Twin
9 Single
10 Full
11 Run of the House
12 Dorm Bed
900301  Roll-Away Bed
900302  Crib
900303  Unspecified Bed

 
extra_bed_configurations object

Provide when all flags below are true:

  • room_type_details

A list of one or more possible extra bed configurations. 
Extra bed configurations are configurations of extra beds that can physically be added to the RoomType for the guest on request. This service may or may not be included in the price of this room. 

In order for an extra bed configuration to be valid, at least one element must exist in either the standard array or custom array. 
Two or more configurations mean that the room could be configured to contain either (any) of these set ups.

For examples, see bed_configurations.
room_view_type object

Provide when all flags below are true:

  • room_type_details

Choose from available OpenTravel codes for Room View Type when available: 

1 Airport view
2 Bay view
3 City view
4 Courtyard view
5 Golf view
6 Harbor view
7 Intercoastal view
8 Lake view
9 Marina view
10 Mountain view
11 Ocean view
12 Pool view
13 River view
14 Water view
15 Beach view
16 Garden view
17 Park view
18 Forest view
19 Rain forest view 
20 Various views 
21 Limited view 
22 Slope view 
23 Strip view
24 Countryside view
25 Sea view

 

The standard room_view_type will be returned as an integer array. If a room_view_type does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists.

Example: { "standard": [1,2,25], "custom": ["my own view of the dunes"] }

Example: {"standard": [2, 25], "custom": [ ]}
accessibility_features object

Provide when all flags below are true:

  • room_type_details

Choose from available codes for accessibility features below:

900501 ADA compliant
900502 Compliant with local laws for disabled
900503 Accessible
900504 Mobility accessible
900505 In-room accessibility
900506 Accessible for blind
900507 Hearing accessible
900508 Roll-in shower
900509 Grab bars in bathroom

 

The standard accessibility features will be returned as an integer array. If an accessibility feature does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists. We encourage you to avoid custom accesibility features, as this may hinder international rollout, and not allow display of standard accessibility icons for travelers. 

Example: {"standard": [900504, 900505], "custom": [ ]}
room_smoking_policy string
  • smoking
  • non_smoking

We also capture hotel_smoking_policy in HotelDetails. The options specified here should not invalidate information at the Hotel level. In the case of a mismatch, Tripadvisor will not display this information.

 

RatePlans

Field

 Type Description
rate_plans HotelRatePlanCode map

Affected when all flags below are true:

  • multiple_room_rates

A map from rate plan keys to rate plans. At minimum, there must exist a rate plan entry for every unique rate_plan_key used in room_rates RoomRate objects.

 

Field Type Description
persistent_rate_plan_code string This is optional.
This code identifies unique rate plans. We expect that this code persists across future availability calls. The combination of persistent_rate_plan_code and partner_hotel_code must be unique.
name  string
The name of this rate plan. For example, "Best Available Rate".
 description  string Provide when all flags below are true:
  • rate_plan_details
  • text

Longer rate description. This will be displayed to end users, and should be in the language indicated by the language parameter.

Language specific requirements will be applied. For example, if a room description in English consists of only numbers and symbols, or is shorter than 4 characters, it may be blocked. See supported HTML tags.
photos Photo array

Provide when all flags below are true:

  • rate_plan_details
  • photos

List of photos representing the rate plan.

Image file type should be able to render on modern web browsers (JPG, PNG, GIF) (TIFF is not supported). Photos should support https.
 rate_amenities  object Provide when all flags below are true:
  • rate_plan_details

Array of number codes where each code corresponds to a rate amenity. Each code corresponds to an amenity for the OpenTravel Hotel Amenity Code List. A map of the standard room amenities is listed under the Supported Amenities section. Use this list to specify amenities that are specific to the rate plan, such as "Executive Club Lounge Access", "English Breakfast Included," etc.

The standard amenities will be returned as an integer array. If an amenity does not exist in the Supported Amenities list, then the Connectivity Partner may provide their own values.

Example: 
{ "standard": [1,2,5], "custom": ["myamenity1", "myamenity2"] }
cancellation_policy  object

Provide when all flags below are true:

  • rate_plan_details

The cancellation policy:

  • Free cancellation until 2017-06-15 00:00:00Z.
  • From 2017-06-15 00:00:00 GMT to 2017-06-20 00:00:00 GMT, there is a cancellation fee of 50.00 USD.
  • After 2017-06-20 00:00:00 GMT, there is a fee of 25.00% of stay and a fee of one night's stay.

is represented in the API as:

"cancellation_policy": {
  "cancellation_summary": {
    "refundable": "full",
    "cancellation_deadline": "2017-06-15T00:00:00Z",
  },
  "cancellation_rules": [
    {
      "start_datetime": "2017-06-15T00:00:00Z",
      "end_datetime": "2017-06-20T00:00:00Z",
      "fixed_fee": {
        "fee": {
          "amount": 50.00,
          "currency": "USD"
        },
        "taxes_included": true
      }
    },
    {
      "start_datetime": "2017-06-20T00:00:00Z",
      "percent_fee": {
        "amount": 0.25
      },
      "night_fee": {
        "num_nights": 1.0
      }
    }
  ]
}
Name Type Description
cancellation_summary array of objects

A summary of the fee schedule associated with cancellation.

refundable string

This field is mandatory. Must be treated as dynamic and change over time according to the cancellation policy and deadline. In addition to this refundable information, cancellation_rules will enable Tripadvisor to display useful information to your customers, including "policy_info" text that is currently displayed to travelers. 

Must be one of:

  • none - "no refund provided if cancelled"
  • partial - "After time of booking there is a charge less than the total reservation amount required for cancellation--the difference is then refunded"
  • full -  "There exists a time between time of booking and time of arrival where the reservation may be cancelled without any charge to the user. Reservations whose free cancellation expires within N days of time of arrival may still be marked fully refundable unless time of booking is within N days of time of arrival"

Note: These fields are case sensitive and should be set as displayed above, they should not be for example 'Full' or 'None'.

Use cases can be found here.
 cancellation_deadline  string Required if refundable is set to full. The date and time after which it is not free to cancel a reservation. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.
unstructured_cancellation_text string

Provide when all flags below are true:

  • rate_plan_details (Same as parent)
  • text

Text describing the cancellation policy for the room. Should be in the language indicated by the language parameter.
cancellation_rules array of objects

A detailed fee schedule associated with cancellation represented as rules. For each rule, At least one of 'fixed_fee', 'percent_fee', or 'night_fee' must be non-null. If more than one is non-null, it will be interpreted as multiple fees with different types taking effect at the same time.

An empty cancellation rule array will be interpreted as no information provided.

Name Type Description
start_datetime string The time which the cancellation rule takes effect. If null, no start time will be used. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.
end_datetime string

The time which the cancellation rule is no longer in effect. If null, no end time will be used. Must be in ISO8601 date-time format, which includes time zone, e.g. YYYY-MM-DDT00:00:00+00:00.
fixed_fee number

Fixed fee charged in the given currency

Name Type Description
fee number Value in a given currency.
amount number The numeric value.
currency string ISO 4217 currency code.
taxes_included boolean If true, taxes are included in given amount. (Note, if there are no taxes charged, this should also be set to true)
percent_fee number

Percent of booking that will be charged as a fee.

Name Type Description
amount number Percent value.
night_fee boolean

Number of nights of booking that will be charged as a fee using the average nightly rate.

Name Type Description
num_nights number Number of nights

 

 

 
meal_plan object

Provide when all flags below are true:

  • rate_plan_details

Choose from available OpenTravel codes for meal plans (MPT):

1 All inclusive
2 American
3 Bed & breakfast
4 Buffet breakfast
5 Caribbean breakfast
6 Continental breakfast
7 English breakfast
8 European plan
9 Family plan
10 Full board
11 Full breakfast
12 Half board / modified American plan
14 Room only
15 Self catering
17 Dinner bed and breakfast plan
18 Family American
19 Breakfast
20 Modified
21 Lunch
22 Dinner
23 Breakfast & lunch

 

The standard meal_plan will be returned as an integer array. If a meal_plan does not exist in the table above, then the Connectivity Partner may provide their own values in the "custom" field as a string array. Return "custom":[ ] if no custom list exists.

Example: { "standard": [1,2], "custom": ["All you can eat", "Special breakfast"] }

Example: {"standard": [2, 4], "custom": [ ]}

 

RoomRates

Field

 Type Description
room_rates RoomRates map

Affected when all flags below are true:

  • multiple_room_rates

A map from room rate keys to room rates.

 

Field Type Description
persistent_room_rate_code string
This is optional.
This code identifies unique room rates. We expect that this code persists across future availability calls. The combination of persistent_room_rate_code and partner_hotel_code must be unique.
room_type_key string
Key referencing the applicable RoomType. This key must exist in the response's room_types map in order for this to be considered a valid response.
rate_plan_key Price object
Key referencing the applicable RatePlan. This key must exist in the response's rate_plan map in order for this to be considered a valid response.
rate_qualification string
Default: "public"
Valid values:
  • "public"
  • "mobile"
  • "member"

The type of qualification required for the room rate.
Any room rate that is returned without this field populated will default to public. A room rate should only be tagged with a mobile rate qualification if the price is exclusive to mobile devices. When member rates are available, partners should return at least one public rate and one member rate in the API response. This feature will only display for qualified partners and has specific UI rules, please check with your Tripadvisor account manager for more information.

Code Value
public Public rate, viewable by any user
mobile Mobile only rate, viewable only by mobile users
member Member only rate, reduced rates offered to members of a loyalty program
line_items LineItem array

Affected when all flags below are true:

  • real_time_pricing
An object containing the detailed breakdown of charges. See below.
payment_policy string

Provide when all flags below are true:

  • room_rate_details
  • text
How will the partner use the credit or debit card information, e.g. charged immediately or hold. Large text field.
rooms_remaining integer

Provide when all flags below are true:

  • room_rate_details

The number of rooms remaining / available at a given hotel for a given roomtype at a given price. This number should be >0.
other_policy string

Provide when all flags below are true:

  • room_rate_details
  • text
Miscellaneous policies.
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. If possible, the URL should go to a webpage in the language specified by the language parameter in the availability request.
partner_data number, string or object

This data will not be interpreted by Tripadvisor, but will be sent back to the partner as-is when we attempt a booking. For example, this field might be used to store a partner 'rate key,’ ‘room key,’ and/or ‘product key.’ It can consist of arbitrary nested JSON, or a single string or number.

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.
caption string
Caption for the photo. Should be in the language indicated by the 'lang' parameter in the request.
width number
Width in pixels of full size photo.
height number
Height in pixels of full size photo.

LineItem

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

Field Type Description
price Price object

When partner_booking_data is set to false (hotel or expanded availability), at least one of requested_currency_price or currency_of_charge_price should be populated. When partner_booking_data is set to true (booking availability) and in /booking_submit, currency_of_charge_price should also be populated. requested_currency_price should also be returned if this was included in previous calls.

Field Type
Description
requested_currency_price string
Value in a given currency. requested_currency_price - Should be populated with the price in the currency sent in the request. You may also populated this field if you cannot determine that the price you have is in the currency of charge.
 
Field Description
amount The numeric value.
currency ISO 4217 currency code
currency_of_charge_price  string
Value in a given currency. currency_of_charge_price - Should be populated with the price in the currency of charge. If you cannot determine the currency of charge, do not populate this field.
 
Field Description
amount The numeric value.
currency ISO 4217 currency code
type string
Describes the charge. Must be one of these values:
 
  • rate
  • tax
  • fee
sub_type string
Describes the sub type of charge. Must be one of these values:
 
Code Value Common Examples of Line Items Which Fall Under This Type
tax_city City taxes are defined as taxes applied by a local city or municipality, collected from the traveler at the time of their stay. These taxes may be flat rate or % based.

  • City Tax

  • Tourism Tax

  • Municipality Tax
fee_resort Resort fees are mandatory additional charges (separate from the base rate) collected by the hotel at time of stay for resort-type accommodations

  • Resort Fee

  • Amenity Fee
fee_transfer Transfer fees are mandatory fees charged by the hotel for transportation from the guest's point of arrival to the hotel itself.

  • Transfer Fee

  • Transfer Charge

  • Connection Fee
tax_environmental Environmental tax (sometimes called a green tax) are taxes or fees paid at the hotel at time of stay for impact to the local environment.  

  • Environmental Tax

  • Environmental Fee

  • Green Tax
tax_vat VAT or GST tax  

  • VAT

  • GST
tax_other Other Taxes: Inclusive of any taxes or fees that do not fall into any of the above five subtypes  
fee_other Other Fees: Inclusive of any fees that do not fall into any of the above five subtypes  
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.

 

Error

If the error object is present, please include as many complete attributes in the response as available.

 Field  Type  Description
error Error object
error_code number
One of these error codes:
1 Unknown Error
2 Cannot Parse Request
3 Invalid Hotel ID. If partner_hotel_code is unknown, return this.
4 Timeout requested. Stops requests for the specified time.
5 Recoverable Error. Equivalent to http 503.
message string
String describing the error. Used for debugging. Maximum length is 1000 characters.
timeout number Number of seconds we should stop sending requests for use with Error Code 4