Using v8 API

Overview

The main feature of our latest version of our API (v8) is to be able to provide a detailed breakdown of taxes and fees including subtypes. If you are not supporting such breakdown, upgrading to the latest version will not bring any benefits for your hotel partners and therefore we would recommend you remain connected on API v7.

The newest version of the TripAdvisor API (v8) is designed to help Partners increase conversions by providing richer availability data to TripAdvisor. The document below highlights key changes and walks you through how you can use the new API. TripAdvisor's v8 API is described as a Swagger/OpenAPI specification file (http://swagger.io/specification/). Swagger comes with tools to autogenerate the model of the API into multiple different languages to make integrations with our API easier. In order to support your API implementation please use and download our v8 API Spec on Swagger. If there are any discrepancies between the documentation and the swagger spec then the swagger spec should be considered accurate.

Major enhancements:

Taxes and fees broken out separately

The new API supports a more detailed breakdown of taxes and fees. This is important because it will allow TripAdvisor to display taxes, fees and base rates in ways that are more relevant to each market. Upgrading to the new API will help you stay competitive and attract bookings from travelers looking for the lowest price. Specifically, we have added new subtypes in “line_items”, found under ‘hotels.available.room_rates’.

Single TripAdvisor endpoint that merges /hotel_availability and /booking_availability calls

We have merged Hotel Availability and Booking Availability by adding request parameters to specify the depth of data and caching strategy that you need to return in your response. This change will allow you to pass different content pieces based on the requested parameters. For example, we know that certain room and rate features – refund and cancellation policies, bed configuration, breakfast options and more –  can influence booking decisions. BBy TripAdvisor requesting this subset of content in addition to the cheapest priced room, hotel shoppers will be able to see these features in the PriceFinder module on TripAdvisor, making them visible earlier and motivating potential guests to book with you. Detailed use-cases covered below. This single API endpoint allows the flexibly to change the information TripAdvisor requests in the future without requiring us to version the API (make breaking changes), and therefore without requiring any effort on the part of Partners. Detailed use-cases covered in section "How to leverage new API" below.

Refactoring RoomType, RatePlan, and RoomRate identifiers and rate features

To align the structure of both the Hotel Availability and Booking Availability calls, we are introducing the following changes to the API:

  • Changed RoomRates from using a list to using a map

  • Added optional Persistent Room Type Code, Persistent Rate Plan Code, and Persistent Room Rate Code fields to identify information that persists between requests. We strongly recommend Partners use a persistent identifier that does not change with each availability request

  • RoomType map, RatePlan map, and RoomRate map keys only need to persist per request

Updated API fields for better alignment

In order to make maintaining, updating, and implementing our API easier for both Partners and TripAdvisor, we have:

  • Removed unused fields and functionality (such as "final_price" and "discount_type", or "adjustment" line items).

  • Elaborated 'cancellation_rules' to allow for start and end time for a cancellation policy

  • Refactored how/where errors are communicated. 

    • Response level - Provided mechanism for Partners to elaborate type of HTTP error (e.g. http 200 error)

    • Location level - In Hotel Availability, added ability to provide errors per-location (e.g. in a multi-hotel availability request. You can now specify which hotels have an error in their response) 

  • Partners can maintain a single set of objects across TripAdvisor API functions (e.g. line_items and customer_support are objects that have been updated in /availability). We want partners to use the same object across the entire API. This provides a consistent experience to partners and lowers maintenance of multiple API versions. We are requesting partners to modify their current calls for Booking Submit, Booking Verify, Booking Cancel, Booking Sync. To reiterate this is not a large change and in fact will streamline your code that uses common objects across API calls.

You can also view our V8 FAQ.

How to use the API

Taxes and Fees

In the line_items object under room_rates the API introduces a new subtype field with enumerated options to break down price information into several categories that are useful for consumers. See new "subtype" field below.

Field

Type

Description

price

Price object

An object containing the price of the line item.

type

string

Describes the charge. Must be one of these values:

  • rate

  • tax

  • fee

subtype

string

Describes the charge in more detail. Must be one of these values. The subtype must agree with the type.

  • tax_city

    • City Tax (Includes Municipality Fee): Tax applied by a local city or municipality, collected from traveler at time of stay

  • fee_resort

    • Resort Fee: Mandatory additional charge for resort-type accommodations, separate from base rate

  • fee_transfer

    • Transfer Fee: Fee to transfer guest to the hotel from their point of arrival

  • tax_environmental

    • Environment Fee (Green Tax) Tax applied at hotel for impact to local environment

  • tax_vat

    • VAT or GST tax

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

 

Definitions for Taxes and Fees

 

Type of Tax or Fee

Definition

Common Examples of Line Items Which Fall Under This Type

City Tax

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

Transfer Fee

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

Environmental Tax

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

Resort Fee

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

VAT / GST

VAT (Value Added Tax) or GST (Goods and Services Tax) are consumption taxes that may be paid at time of booking or time of stay.

  • VAT

  • GST

Other Taxes

Taxes which do not fall into the above categories

 

Other Fees

Fees which do not fall into the above categories

 

 

Single Availability Endpoint

The single endpoint leverages flags/ fields “categories” and “category_modifiers” to request and receive different types of data from Partners. Each of these flags corresponds to particular sets of information in the response.

The categories flags are set to true/ false based on the way TripAdvisor aims to present the data to customers. Whether or not we need these sets of data changes between requests and in particular could change in the future if we cache older responses - for example Room Type data is fairly static. The category_modifiers are particular types of data that can be applied each of the categories in a specific request/response. For example, if "photos" and "room type details" are both set to true, room type details with photos must be returned.  However, if "room type details" is set to true and "photos" is set to false, the room type details returns does not need to include photo urls. The table below lists the categories and category_modifiers flags available in the API.  

Information Groups

Request/ Response Flag

Description

categories

room_type_details

if true, must include room type content such as name, (can be used with above modifiers).

rate_plan_details

if true, must include rate plan content, such as refundability

room_rate_details

if true, must include room rate content, such as rooms remaining

hotel_details

if true, must provide hotel details, such as smoking policy

category_modifiers

partner_booking_data

If true, fields marked as booking_partner_data must be provided to the best of your ability. This flag is only intended for partners that are part of TripAdvisor Instant Booking. Example: accepted credit cards

real_time_pricing

If true, non-cached pricing must be provided. This flag is only intended for requests for 1 hotel. Fields marked as real_time_pricing are affected.

multiple_room_rates

If true, multiple room rate offers must be provided, if available. Fields marked as multiple_room_rates are affected.

photos

When used in combination with data category flags, fields marked additionally with photos must be provided to the best of your ability. Example: room type photos

text

When used in combination with data category flags, fields marked additionally with text must be provided to the best of your ability. Example: cancellation policy text

 

Mapping Flags to Use-Cases

In the request, a requested flag points out which pieces of information are required. In the response, these flags indicate this information has been provided by the Partner to the best of their 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 costs in terms of response time and 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.

(Note: The details shown in the following use-case sample images are subject to change)

Information Groups

Request/Response Flag

Hotel Availability:

multihotelv8

Expanded Availability:

hotelspage

Booking Availability:

roomgrid

categories

room_type_details

N

Y

Y

rate_plan_details

N

Y

Y

room_rate_details

N

Y

Y

hotel_details

N

N

Y

category_modifiers

partner_booking_data

N

N

Y

real_time_pricing

N

N

Y

multiple_room_rates

N

Y

Y

photos

N

Y

Y

text

N

Y

Y