/availability

 

Availability requests are sent by adding /availability to your endpoint and sending the parameters explained below in a POST request.

Hotel Availability

In the below example three hotels are requested and the response_type for each is different. The first one has availability ("available"), the second has no availability ("unavailable") and the third has an error ("error").

Request

{
  "api_version": 8,
  "start_date": "2017-05-01",
  "end_date": "2017-05-03",
  "party": [
    {
      "adults": 3
    },
    {
      "adults": 2,
      "children": [
        9,
        5
      ]
    }
  ],
  "language": "en_US",
  "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
  "currency": "USD",
  "user_country": "US",
  "device_type": "Desktop",
  "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
  "requested_payload": {
    "categories": {
      "room_type_details": false,
      "rate_plan_details": false,
      "room_rate_details": false,
      "hotel_details": false
    },
    "category_modifiers": {
      "partner_booking_data": false,
      "real_time_pricing": false,
      "multiple_room_rates": false,
      "s": false,
      "text": false
    }
  },
  "hotels": [
    {
      "ta_hotel_id": 258705,
      "partner_hotel_code": "A123"
    },
    {
      "ta_hotel_id": 730099,
      "partner_hotel_code": "B456"
    },
    {
      "ta_hotel_id": 555555,
      "partner_hotel_code": "555"
    },
  ]
}

Parameters

Name Type Description
api_version integer The version of the API of this request.
start_date string The check-in date of the traveler using the hotel's time zone. The date is required to be in ISO8601 full-date format (YYYY-MM-DD).
end_date string The check-out date of the traveler using the hotel's time zone. The date is required to be in ISO8601 full-date format (YYYY-MM-DD).
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. If no children are requested Tripadvisor may send an empty children array. For example: "party":[{“adults": 2}{children:[]}]. Or no children at all. Both variants should be accepted. 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 children for a total of 2 rooms.
language string Language code (see Supported Languages). Language codes are a combination of the ISO 639-1 language codes and the ISO 3166-1 country codes. When used in an AvailabilityRequest, this is the language that Tripadvisor would prefer that the partner return with. When used in an AvailabilityResponse, this is the language that the partner is responding 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.

query_key string String useful for debugging. It is recommended for this value to be logged.
currency string ISO 4217 currency code.
user_country string ISO 3166-1 alpha-2 country code.
device_type string Identifies the user’s device type. Takes values “Desktop”, “Mobile” or “Tablet”. This value is required if pricing differs by device type.
query_key string String useful for debugging. It is recommended for this value to be logged.
availability_id string Identifier primarily used for internal purposes. Partners implementing the API may ignore this parameter.
requested_payload  array

Each of these flags correspond to particular sets of information in the response. Currently Tripadvisor will always set the requested flag as False in Hotel Availability search. You are free to return whichever content you would like however at this time only Free Cancellation and Pay at Stay information is used in Hotel Availability. Additional content beyond that is displayed only for Instant Booking.

In the request, this signifies that these pieces of information are required. In the response, these flags indicate this information has been given to the best of your ability, there is not another call which will provide better information. 

Scenario Requested Flag Acceptable Response Flag Explanation and expectations
1 False False Partner is responding with the exact set of data being requested.
2 False True Partner is capable of responding with more data than what was asked in the request. This may be useful in case a Partner's system does not allow you split content per the Tripadvisor requirements.
3 True True Partner is providing the required pieces of information to the best of their knowledge. Best case, Partner provides all the content requested.
4 True False Partner cannot provide this information at this time, either due to an error in the partner's system / load capabilities. Tripadvisor may be unable to display the rest of your content.

Example: in a single hotel request with all flags set to false - i.e TA is requesting at least one room-rate to be returned (assuming there is availability for that hotel). Potential response options:

  1. At minimum we expect to receive a single room-rate with the response flags set to all be false.
  2. However, for the same request, a Partner is permitted to send TA more information. For example, Partner can potentially send all room-rates (instead of just one) for that hotel. Here a Partner is expected to set the "multiple_room_rates_included" to "true"

Example: the request has flags for "room_type_details" and "photos" set to "true. Acceptable responses where Partner sets "room_type_details" and "photos" flag to "true"

  1. Partner provides photos for each room type
  2. It is possible that the partner just does not have access to / full coverage for the content being requested. It is expected that the response flags for "photos" and "room_type_details" are set to "true" but the payload returned may not contain any photos. Partner is indicating that they understand the requested fields, are trying to provide that data to us, and there is no better content available in a separate call or otherwise

Responses should include as much extra information as they can without incurring significant costs in time the call takes or rate of calls supported. If any of these fields are missing they will be interpreted as false. New flags may be added in the future in which case they should either not be returned or returned as false.

categories array

These flags specify areas of the response that closely matches the object structure of the API.

key
description
type
room_type_details
If true, fields marked as room_type_details in the RoomType object must be provided to the best of your ability.
boolean
rate_plan_details
If true, fields marked as rate_plan_details in the RatePlan object must be provided to the best of your ability.
boolean
room_rate_details
If true, fields marked as room_type_details in the RoomRate object must be provided to the best of your ability.
boolean
hotel_details
If true, fields marked as hotel_details in the HotelDetails object must be provided to the best of your ability.
boolean
 category_modifiers  object

These flags specify pieces of content which Tripadvisor understands may cause a performance impact.

key
description
type
partner_booking_data
If true, fields marked as partner_booking_data must be provided to the best of your ability. This flag is only intended for partners that are part of Tripadvisor Instant Booking.
boolean
real_time_pricing
If true, the most accurate pricing must be provided. This flag is only intended for requests for 1 hotel. Fields marked as real_time_pricing are affected.
boolean
multiple_room_rates
If true, multiple room rate offers must be provided, if available. Fields marked as multiple_room_rates are affected.
boolean
photos
When used in combination with data category flags, fields marked additionally with photos must be provided to the best of your ability.
boolean
text
When used in combination with data category flags, fields marked additionally with text must be provided to the best of your ability.
boolean
 hotel object

JSON serializable hash representing requested hotel. 

key description type
ta_hotel_id Tripadvisor hotel IDs integer
partner_hotel_code Partner hotel ID string

Note: All your availability lookups must use your partner_hotel_code. The Tripadvisor ID can change as the site changes.

Response

The below represents the minimum amount of information you can provide in order to be displayed in Tripadvisor's Hotel Availability search.

Currently Tripadvisor will always set the requested flag as False in Hotel Availability search. You are free to return whichever content you would like however at this time only Free Cancellation and Pay at Stay information is used in Hotel Availability. Additional content beyond that is displayed only for Instant Booking.

{
  "api_version": 8,
  "language": "en_US",
  "availability_request": {
    "api_version": 8,
    "start_date": "2017-05-01",
    "end_date": "2017-05-03",
    "party": [
      {
        "adults": 3
      },
      {
        "adults": 2,
        "children": [
          9,
          5
        ]
      }
    ],
    "language": "en_US",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "currency": "USD",
    "user_country": "US",
    "device_type": "Desktop",
    "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
    "requested_payload": {
      "categories": {
        "room_type_details": false,
        "rate_plan_details": false,
        "room_rate_details": false,
        "hotel_details": false
      },
      "category_modifiers": {
        "partner_booking_data": false,
        "real_time_pricing": false,
        "multiple_room_rates": false,
        "photos": false,
        "text": false
      }
    },
    "hotels": [
      {
        "ta_hotel_id": 258705,
        "partner_hotel_code": "A123"
      },
      {
        "ta_hotel_id": 730099,
        "partner_hotel_code": "B456"
      },
      {
        "ta_hotel_id": 555555,
        "partner_hotel_code": "555"
      },
    ]
  },
  "response_payload": {
    "categories": {
      "room_type_details": false,
      "rate_plan_details": false,
      "room_rate_details": false,
      "hotel_details": false
    },
    "category_modifiers": {
      "partner_booking_data": false,
      "real_time_pricing": false,
      "multiple_room_rates": false,
      "photos": false,
      "text": false
    }
  },
  "hotels": {
    "A123": {
      "response_type": "available",
      "available": {
        "room_types": {
          "1": {
            "persistent_room_type_code": "king1"
            "name": "Deluxe King Room",
          },
          "2": {
            "persistent_room_type_code": "king2"
            "name": "Deluxe King Room - Non Smoking",
          }
        },
        "rate_plans": {
          "1": {
            "persistent_rate_plan_code": "BR21"
            "name": "Best Available Rate",
          },
          "2": {
            "persistent_rate_plan_code": "OL44"
            "name": "Online Discount",
          }
        },
        "room_rates": {
          "1": {
            "persistent_room_rate_code": "21dr-wi4g-aaa9-kg2np",
            "room_type_key": "1",
            "rate_plan_key": "1",
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 220,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_city",
                "paid_at_checkout": false,
                }
            ]
          },
          "2": {
            "persistent_room_rate_code": "581d-la3n-pg9a-vnr3",
            "room_type_key": "1",
            "rate_plan_key": "2",
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room2?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 200,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_vat",
                "paid_at_checkout": false,
                }
            ]
          },
          "3": {
            "persistent_room_rate_code": "nv3i-lgex-kxx2-ajge",
            "room_type_key": "2",
            "rate_plan_key": "1",
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room3?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 180,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "fee",
                "sub_type": "fee_resort",
                "paid_at_checkout": false,
                }
            ]
          }
        }
      }
    },    
    "B456": {
      "response_type": "unavailable"
    },
    "555": {
      "response_type": "error",
      "error": {
        error_code: 3
        message: "Unknown hotel id was requested."
      }
    }
  }
}

 

The below represents the maximum amount of information you can provide in Tripadvisor's Hotel Availability search. 

Currently Tripadvisor will always set the requested flag as False in Hotel Availability search. You are free to return whichever content you would like however at this time only Free Cancellation and Pay at Stay information is used in Hotel Availability. Additional content beyond that is displayed only for Instant Booking.

Response

{
  "api_version": 8,
  "language": "en_US",
  "availability_request": {
    "api_version": 8,
    "start_date": "2017-05-01",
    "end_date": "2017-05-03",
    "party": [
      {
        "adults": 3
      },
      {
        "adults": 2,
        "children": [
          9,
          5
        ]
      }
    ],
    "language": "en_US",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "currency": "USD",
    "user_country": "US",
    "device_type": "Desktop",
    "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
    "requested_payload": {
      "categories": {
        "room_type_details": false,
        "rate_plan_details": false,
        "room_rate_details": false,
        "hotel_details": false
      },
      "category_modifiers": {
        "partner_booking_data": false,
        "real_time_pricing": false,
        "multiple_room_rates": false,
        "photos": false,
        "text": false
      }
    },
    "hotels": [
      {
        "ta_hotel_id": 258705,
        "partner_hotel_code": "A123"
      }
    ]
  },
  "response_payload": {
    "categories": {
      "room_type_details": false,
      "rate_plan_details": false,
      "room_rate_details": false,
      "hotel_details": false
    },
    "category_modifiers": {
      "partner_booking_data": false,
      "real_time_pricing": false,
      "multiple_room_rates": false,
      "photos": false,
      "text": false
    }
  },
  "hotels": {
    "A123": {
      "response_type": "available",
      "available": {
        "room_types": {
          "1": {
            "persistent_room_type_code": "king1",
            "name": "Deluxe King Room",
            "photos": [
               {
               "url": "https://www.example.com/FenwayRoomBed.jpg",
               "width": 480,
               "height": 270,
               "caption": "Image of King Bed"
              }
            ],
            "room_amenities": {
              "standard": [
                20,
                900118
              ],
              "custom": [
                "My custom chair",
                "Wolf appliances"
              ]
            },
            "room_size": {
              "value": 500,
              "unit": "square_feet"
            },
            "bed_configurations": [
              {
                "standard": [
                  {
                    "code": 3,
                    "count": 1
                  }
                ],
                "custom": [
                  {
                    "name": "Loft",
                    "count": 1
                  }
                ]
              }
            ],
            "extra_bed_configurations": [
              {
                "standard": [
                  {
                    "count": 1,
                    "code": 900302
                  }
                ]
              },
              {
                "custom": [
                  {
                    "count": 2,
                    "name": "Rollaway with wheel locks and adjustable height"
                  }
                ]
              }
            ],
            "room_view_types": {
              "standard": [
                10
              ],
              "custom": [
                "Northern Lights"
              ]
            },
            "accessibility_features": {
              "standard": [
                900501,
                900505
              ]
            },
            "max_occupancy": {
              "number_of_adults": 2,
              "number_of_children": 0
            },
            "room_smoking_policy": "smoking"
          },
          "2": {
            "persistent_room_type_code": "king2",
            "name": "Deluxe King Room - Non Smoking",
            "photos": [
              {
               "url": "https://www.example.com/FenwayRoomBed.jpg",
               "width": 480,
               "height": 270,
               "caption": "Image of King Bed"
              }
            ],
            "room_amenities": {
              "standard": [
                20,
                101,
                900118
              ],
              "custom": [
                "My custom chair",
                "Wolf appliances"
              ]
            },
            "room_size": {
              "value": 400,
              "unit": "square_feet"
            },
            "bed_configurations": [
              {
                "standard": [
                  {
                    "code": 3,
                    "count": 1
                  }
                ]
              },
              {
                "standard": [
                  {
                    "code": 5,
                    "count": 2
                  }
                ]
              }
            ],
            "extra_bed_configurations": [
              {
                "standard": [
                  {
                    "count": 1,
                    "code": 4
                  }
                ]
              },
              {
                "custom": [
                  {
                    "count": 1,
                    "name": "Rollaway with wheel locks and adjustable height"
                  }
                ]
              }
            ],
            "room_view_types": {
              "standard": [
                10
              ],
              "custom": [
                "Northern Lights"
              ]
            },
            "accessibility_features": {
              "standard": [
                900504
              ]
            },
            "max_occupancy": {
              "number_of_adults": 2,
              "number_of_children": 0
            },
            "room_smoking_policy": "non_smoking"
          }
        },
        "rate_plans": {
          "1": {
            "persistent_rate_plan_code": "BR21",
            "name": "Best Available Rate",
            "photos": [
              {
                "url": "https://www.example.com/jetski01.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of complimentary jet skis that are provided."
              },
              {
                "url": "https://www.example.com/kayak01.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of kayak that are available to rent."
              }
            ],
            "rate_amenities": {
              "standard": [
                75
              ],
              "custom": [
                "Complimentary jet skis",
                "Kayak rentals"
              ]
            },
            "cancellation_policy": {
              "cancellation_summary": {
                "refundable": "full",
                "cancellation_deadline": "2017-06-15T00:00:00Z",
                "unstructured_cancellation_text": "Free cancellation until 2017-06-15 GMT. From 2017-06-15 GMT to 2017-06-20 GMT, there is a cancellation fee of 50.00 USD. From 2017-06-20 GMT until date and time of check-in, there is a fee of 25.00% of stay and a fee of one night's stay."
              "cancellation_rules": [
                {
                  "start_datetime": "2017-06-15T00:00:00Z",
                  "end_datetime": "2017-06-20T00:00:00Z",
                  "fixed_fee": {
                    "fee": {
                      "amount": 50,
                      "currency": "USD"
                    },
                    "taxes_included": true
                  }
                },
                {
                  "start_datetime": "2017-06-20T00:00:00Z",
                  "percent_fee": {
                    "amount": 0.25
                  },
                  "night_fee": {
                    "num_nights": 1
                  }
                }
              ]
            },
            "meal_plan": {
              "standard": [
                22
              ],
              "custom": [
                "Brunch on weekend mornings"
              ]
            }
          },
          "2": {
            "persistent_rate_plan_code": "OL44",
            "name": "Online Discount",
            "photos": [
              {
                "url": "https://www.example.com/nfl_cable.jpg",
                "width": 480,
                "height": 270,
                "caption": "Image of cable TV selection."
              }
            ],
            "rate_amenities": {
              "standard": [
                207
              ],
              "custom": [
                "NFL Network"
              ]
            },
            "cancellation_policy": {
              "cancellation_summary": {
                "refundable": "none",
                "unstructured_cancellation_text": "Non-refundable rate. No cancellations permitted, all taxes and fees will need to be paid."
              },
              "cancellation_rules": [
                {
                  "percent_fee": {
                    "amount": 1
                  }
                }
              ]
            },
            "meal_plan": {
              "standard": [
                22
              ],
              "custom": [
                "Brunch on weekend mornings"
              ]
            }
          }
        },
        "room_rates": {
          "1": {
            "persistent_room_rate_code": "21dr-wi4g-aaa9-kg2np",
            "room_type_key": "1",
            "rate_plan_key": "1",
            "rooms_remaining": 2,
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 220,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "fee",
                "sub_type": "fee_transfer",
                "paid_at_checkout": false,
                }
            ]
          },
          "2": {
            "persistent_room_rate_code": "581d-la3n-pg9a-vnr3",
            "room_type_key": "1",
            "rate_plan_key": "2",
            "rooms_remaining": 1,
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room2?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 200,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_city",
                "paid_at_checkout": false,
                }
            ]
          },
          "3": {
            "persistent_room_rate_code": "nv3i-lgex-kxx2-ajge",
            "room_type_key": "2",
            "rate_plan_key": "1",
            "rooms_remaining": 5,
            "url": "http: //www.partner-site.com/hotel_commonwealth/fenway_room3?start_date=2017-05-01&end_date=2017-05-03&num_adults=3&num_child=2",
            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 180,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": false,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_environmental",
                "paid_at_checkout": false,
                }
            ]
          }
        }
      }
    }
  }

 

Properties

Field Type Description
api_version integer
The version of the API of this response.
language string Language code (see Supported Languages). Language codes are a combination of the ISO 639-1 language codes and the ISO 3166-1 country codes. When used in an AvailabilityRequest, this is the language that Tripadvisor would prefer that the partner return with. When used in an AvailabilityResponse, this is the language that the partner is responding 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.

availability_request array The request parameters.
response_payload array The response parameters.
hotels hotels map

Map of partner_hotel_code to SingleHotelResponse entries. See below.

Hotels

Map of partner_hotel_code to SingleHotelResponse entries. Each key must match a corresponding partner_hotel_code in the request's hotel array. Note that each hotel may have a different response_type. This Map must be the same size as the list of the hotels in the request to be considered a valid response.

Field

Type Description
response_type string
The type of response returned for a hotel. Must be one of "available",  "unavailable" or "error" 
available SingleHotel map
Representation of an individual hotel. Only if response_type is "available". 
error Error object
Only if response_type is "error". See Error

RoomTypes

Field

Type Description
room_types RoomType 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.

Example: {"value":500, "unit": "square_feet" }

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_types 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_types will be returned as an integer array. If a room_view_types 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

Provide when all flags below are true:

  • room_type_details

Options:

  • 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 RatePlan 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"
"unstructured_cancellation_text": "Free cancellation until 2017-06-15. 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." }, "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.
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.

 

LineItems

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

 

Example Response:

{
  "api_version": 8,
  "language": "en_US",
  "availability_request": {
    "api_version": 8,
    "start_date": "2017-11-07",
    "end_date": "2017-11-08",
    "party": [
      {
        "adults": 2,
        "children": []
      }
    ],
    "language": "en_US",
    "currency": "USD",
    "user_country": "US",
    "device_type": "Desktop",
    "query_key": "6167a22d1f87d2028bf60a8e5e27afa7_191_1360299600000_2_2",
    "availability_id": "a2fd740a-ad02-476d-b314-925a125509be",
    "requested_payload": {
      "categories": {
        "room_type_details": false,
        "rate_plan_details": false,
        "room_rate_details": false,
        "hotel_details": false
      },
      "category_modifiers": {
        "partner_booking_data": false,
        "real_time_pricing": false,
        "multiple_room_rates": false,
        "photos": false,
        "text": false
      }
    },
    "hotels": [
      {
        "ta_hotel_id": 1,
        "partner_hotel_code": "HotelTest"
      }
    ]
  },
  "response_payload": {
    "categories": {
      "room_type_details": false,
      "rate_plan_details": false,
      "room_rate_details": false,
      "hotel_details": false
    },
    "category_modifiers": {
      "partner_booking_data": false,
      "real_time_pricing": false,
      "multiple_room_rates": false,
      "photos": false,
      "text": false
    }
  },
  "hotels": {
    "HotelTest": {
      "response_type": "error",
      "error": {
        "error_code": "3",
        "message": "Invalid hotel ID",
      }
    }
  }
}

Multiple Rooms

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

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

No availability

So for no availability, Tripadvisor would expect to see:

...
"response_type": "unavailable"
...

Free Cancellation and Pay At Stay

The below describes the implementation of 'Free Cancellation' and 'Pay At Stay' merchandizing shown on Tripadvisor Hotel Availability search. Please note that the information below is only applicable for Hotel Availability response. Merchandizing will only be shown if your cheapest rate is free to cancel and/or pay at stay. There is currently no merchandizing for non-refundable or partially-refundable rates. Information must be correct on the partner's landing page. Partners should only support this feature if it has minimal to no impact on their response time.

Free Cancellation

To be eligible for 'Free Cancellation' merchandizing your Hotel Availability response should return cancellation_policy in RatePlans. Not all objects in cancellation_policy are required, to reduce complexity it is recommended that you only send the following:

cancellation_policy  object

 

"cancellation_policy": {
  "cancellation_summary": {
    "refundable": "full",
    "cancellation_deadline": "2019-06-15T00:00:00Z"
},
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.

Must be one of:

  • none - "no refund provided if cancelled"
  • 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'.

 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.

 

Pay at Stay

To be eligible for 'Pay At Stay' merchandizing your Hotel Availability response should return "paid_at_checkout" : true for all LineItems:

            "line_items": [
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 220,
                    "currency": "USD"
                  }
                },
                "type": "rate",
                "paid_at_checkout": true,
                },
              {
                "price": {
                  "requested_currency_price": {
                    "amount": 20,
                    "currency": "USD"
                  }
                },
                "type": "tax",
                "sub_type": "tax_city",
                "paid_at_checkout": true,
                }
            ]
          },