/room_information_v7

The /room_information function provides physical room inventory information for properties supported by a Connectivity Partner. Add /room_information to your endpoint and send the parameters explained below in a POST request. TripAdvisor will poll your endpoint on a weekly basis to gather information on room inventory.
 
Please note that this is separate from the /booking_availability call that is made at the time of a booking, and is not meant to replace the /booking_availability call. The /room_information is agnostic to dates and prices, and is only meant to capture descriptive room and rate information. Adding this optional function to your endpoint is recommended. It provides TripAdvisor with relevant room and rate details, and will allow TripAdvisor to optimize the descriptive room information presented to travelers in the booking flow. 
 
Also, 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).

Request

http://partner-site.com/api_implementation/room_information

ContentType: application/x-www-form-urlencoded

api_version=7
&hotel={
  "ta_id": 730099, 
  "partner_hotel_code": "1191",
  "partner_url": "http://www.partner-site.com/deeplink/to/1191"
}
&language_request=en_US
&unique_query_key=6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_1_200

Parameters

Name Type Description
api_version number The version of the API that this request is using.
hotel object JSON serializable hash representing requested hotel. 
key description type
ta_id TripAdvisor hotel IDs integer
partner_hotel_code Partner hotel ID string
partner_url Deeplink for this property. string
Example: hotel={"ta_id": 1128635, "partner_hotel_code": "1191", "partner_url": "http://partner.com/deeplink/to/1191"}. Note: You must implement all your availability lookups using your partner_hotel_code. The TripAdvisor ID can change as the site changes. The partner_url is mostly use for internal purposes. Partners implementing the API may ignore this parameter.
language_request string

Language code (see Supported Languages). The inventory requested in a single call will be for this language specified, i.e. there can only be one language returned. If the partner cannot provide the exact language in the request, they can return a closely matched language — for example, if the request is asking for "de_AT", a response in "de" is also acceptable. If the partner cannot provide the language requested, abort response and return an "error_log" within "language_response"
unique_query_key string String useful for debugging. It is recommended for this value to be logged.

Response

ContentType: application/json

{
 "api_version": 7,
 "hotel_id": 730099,
 "language_response": {
    "code_str":"en_US",
    "error_log": ""
  }
 "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_1_200",
 "hotel_room_types": {
   "KNGDL": {
     "code": "KNGDL",
     "name": "Deluxe King Room",
     "description": "Plush King bed, deluxe beddings, recently renovated bath",
     "photos": [{
       "url":"http://www.partnersite.com/FenwayRoomBed.jpg",
       "width":200,
       "height":300,
       "caption":"Image of King Bed"
     }],
     "room_amenities": {
       "standard": [ 20, 900118],
       "custom": [ "My custom chair", "Wolf appliances" ]
     },
     "room_size": "500",
     "room_size_units": "square_feet",
     "bed_type": {
       "standard": [ 3 ],
       "custom": [ ]
     },
     "extra_bed_type": { 
       "standard": [ 2 ],
       "custom": [ ]
     },
     "room_view_type": {
       "standard": [ 21 ],
       "custom": [ "Parking Lot" ]
     },
     "accessibility": "ada_compliant",
     "max_occupancy": {
       "number_of_adults": 2,
       "number_of_children": 2
     },
     "room_smoking_policy": "non_smoking",
   }
   "DBLBED": {
     "code": "DBLBED",
     "name": "Double Bed Standard Room",
     "description": "Comfortable double bed with a view of downtown.",
     "photos": [{
       "url":"http://www.partnersite.com/DoubleStdRoomBed.jpg",
       "width":200,
       "height":300,
       "caption":"Image of King Bed"
     }],    
     "room_amenities": {
       "standard": [ 20, 900118]
       },
     "room_size": "400",
     "room_size_units": "square_feet",
     "bed_type": {
       "standard": [ 3 ]
     },
     "extra_bed_type": { 
       "standard": [ 2 ]
     },
     "room_view_type": {
       "standard": [ 2 ],
       "custom": [ "Parking Lot" ]
     },
     "accessibility": "ada_compliant",
     "max_occupancy": {
       "number_of_adults": 2,
       "number_of_children": 2
     },
     "room_smoking_policy": "non_smoking"
   }
 },
 "hotel_rate_plans": {
   "BAR1": {
     "name": "Best Available Rate",
     "code": "BAR1",
     "description": "This is the best available rate available in March, suitable for family stays under 7 days",
     "photos": [ ],
     "rate_amenities": {
       "standard": [ 75 ],
       "custom": [ "Complimentary jetskis", "Kayak rentals" ]
     },
     "refundable": "unknown",
     "cancellation_rules": {
       "policy_info": "Partially refundable rate", ]
     },
     "meal_plan": {
       "standard": [ 22 ],
       "custom": [ "Hot Pockets" ]
     },
     "discount_type": {
       "standard": [ 9 ],
       "custom": [ "My hotel discount" ]
     }
   }
 },
}

Properties

Field Type Description
api_version number
The version of the API that this request is using.
hotel_id number Echo the ta_id (not partner_hotel_code) requested by TripAdvisor in the 'hotel' object.
language_response string

 

Name Type Description
code_str string Language code (see Supported Languages). The language of the response.
error_log string If you cannot respond in the language requested by “language_request” or any closely related language, send a custom string indicating list of available languages and/or reasons for aborting response.
unique_query_key string Echo the unique query key in the request by TripAdvisor.
hotel_room_types  HotelRoomTypeCode map Map object that maps codes to objects.
The codes are the hotel room type codes.
The objects provide the details for the hotel room type.
hotel_rate_plans HotelRatePlanCode map
Map object that maps codes to objects.
The codes are the hotel rate plan codes.
The objects provide the details for the hotel rate plan.


Note that hotel_room_types and hotel_rate_plans are containers for an array of rooms and rateplans. Elements of each container are the same as that in /booking_availabiltiy. The only caveat is that RatePlan information requested in this periodic call will only require descriptive content to be present and you can omit any information related to dates.

HotelRoomTypes

The "hotel_room_types" map consists of the following fields, with their respective types and descriptions.

HotelRoomTypes

Field

 Type Description
hotel_room_types HotelRoomTypeCode map
Map object that maps codes to objects.
The codes are the hotel room type codes.
The objects provide the details for the hotel room type.

 

HotelRoomTypeCode
Field Type Description
"<hotel_room_type_code>"

HotelRoomType
The hotel_room_type_code is itself a string. This value of the string is determined by the Connectivity Partner.
 
The hotel_room_type_code maps to a HotelRoomType object.

 

HotelRoomType
Field Type Description
code

string
The code must have the same value as the HotelRoomTypeCode. 
The hotel_room_type_code is itself a string. This value of the string is determined by the Connectivity Partner. The room type code must be unique for each room available in the hotel
name string
The name of this room type.
For example, "Fenway Room"
description string
Longer room description. This will be displayed to end users, and should be in the language indicated by the 'lang' parameter.
Max length 1000 characters.
See supported HTML tags.
photos Photo array
An array of photo objects for the room.
room_amenities object

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.

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, 20, 60,], "custom": ["myamenity1", "myamenity2"] }
max_occupancy map of string:int

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 string [Optional] How large is the room area. Specify the unit of measurement in room_size_units
room_size_units string

[Optional] Must be specified if room_size is provided. Pick one of the two options (derived from OTA’s UOM):

  • square_feet
  • square_meters
bed_type  object 

The type of bed provided. 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

 

The standard bed_type will be returned as an integer array. If a bed_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,5], "custom": ["California King", "Plush Queen"]}
 extra_bed_type object

Provide information on additional beds and configurations available. 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 Extra Beds Available on Request

 

The standard extra_bed_type will be returned as an integer array.

If an extra_bed_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,5], "custom": ["Extra bed not available", "My custom extra bed type"] }
room_view_type object [Optional] 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 extra_bed_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": ["extra bed not available", "myextratype"] }
accessibility string

[Optional] Choose from the following options:

  • ada_compliant
  • compliant_with_local_laws_for_disabled
room_smoking_policy string
  • smoking
  • non_smoking

We also capture hotel_smoking_policy in HotelDetails and require that the options specified here do not invalidate information at the Hotel level. In the case of a mismatch, TripAdvisor will not display this information.
 rooms_remaining integer The number of rooms remaining / available at a given hotel for this given roomtype

 

HotelRatePlans

"hotel_rate_plans" map consists of the following fields, with their respective types and descriptions.

HotelRatePlans

Field

 Type Description
hotel_rate_plans HotelRatePlanCode map
An map object, which maps codes to objects.
The codes are the hotel rate plan codes.
The objects provide the details for the hotel rate plan.

 

HotelRatePlanCode
Field Type Description
"<hotel_rate_plan_code>"

HotelRatePlan
The hotel_rate_plan_code is itself a string. This value of the string is determined by the Connectivity Partner.
 
The hotel_rate_plan_code maps to a HotelRatePlan object.

 

HotelRatePlan
Field Type Description
code

string
The code must have the same value as the HotelRatePlanCode. 
The hotel_rate_plan_code is itself a string. This value of the string is determined by the Connectivity Partner. The rate plan code must be unique for each rate plan available in the hotel
name string
The name of this rate plan.
For example, "Best Available Rate"
description string
Longer rate description. This will be displayed to end users, and should be in the language indicated by the 'lang' parameter.
Max length 1000 characters.
See supported HTML tags.
photos Photo array
[Optional] An array of photo objects for the rate plan.
rate_amenities object

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".

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"] }
refundable  string

We strongly encourage the use of cancellation_rules as this will enable TripAdvisor to display useful information to your customers. This field can be omitted if you are already providing cancllation_rules.

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"
  • unknown - “cannot provide a refund policy” (Default)
cancellation_rules  object

Container for cancellation rules and policies. We encourage you to provide only the descriptive fields within cancellation_rules (unlike the /booking_availability call). Contains the following fields: 

Name Type Description
policy_info string Text describing the cancellation policy for the room. Should be in the language indicated by the 'lang' parameter. Max length 1000 characters. 

 
meal_plan object

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"] }
discount_type  object

[Optional] Choose from available codes for Discount Types when available, based on OpenTravel Discount Types: 

1 AAA
2 AARP
3 Convention
4 Corporate
5 Family
6 Government
7 Group
8 Military
9 Promotional
10 Senior citizen
11 Tour
12 Weekday
13 Weekend
900001 Resident
900002 Non resident
900003 Out of state
900004 Attraction package

 

The standard discount_type will be returned as an integer array. If a discount_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,10], "custom": ["Florida resident discount", "Buy with sea world tickets and save"] }