Support

API v8 FAQ

Why has Tripadvisor merged /hotel_availability and /booking_availability? 

Why - Allows greater flexibility for Partners to adapt to new revisions of the API. If Tripadvisor adds new items to it’s requests in the future, using a single API allows for such changes to be non-breaking in nature (Partner can choose to adopt changes when ready) therefore requiring minimal to no effort on the part of Partners.  Additionally, the single API allows for consistency of data across different requests and lets us optimize the load on Partner servers. 

How - The single endpoint leverages flags named “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 category_modifiers are particular types of data that can be applied to each of the categories in a specific request/response.  We don’t have an exhaustive list of combinations, but expect that when we ask for a certain combination we receive those data pieces in the response. Both ‘categories’  and ‘category_modifiers’ are required.

How to differentiate a CPC call from an Instant Booking one?

• With respect to CPC vs IB there’s no change from v7 to v8, and partners should work exactly the same way as they do for V7. In the event this doesn’t work, partners should contact their Account Manager explaining how V8 behavior differs from V7 so that we can look at their specific case.

• Submitting different endpoints for CPC and IB both supporting V8 could be an option however - meaning that partner needs both endpoints to go through the certification process and both be maintained.

What is an example of response flags when a partner can responds TRUE when asked for FALSE?

• In a single hotel availability request when TA is only requesting for the cheapest room rate available, we expect all category / flags requested to be set to FALSE (i.e. TA is not requesting for any additional room/rate/hotel details). There are two acceptable responses:

  • At minimum we expect to receive a single room-rate with the response flags set to all be false.

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

What are the request parameters and content data that Tripadvisor will  be asking for?

• In the UI, we will likely use room names, bed configuration, breakfast, free cancellation, pay at stay, rooms remaining, etc in Expanded Availability. We would like partners to send us exactly what we are asking for.  However, partner is allowed to pass Tripadvisor other info fields (e.g. “hotel_details”), and Tripadvisor will drop the items we don’t need from the response. 

With the merging of Hotel Availability and booking availability call will partners have to submit new endpoints?

• Partners do not have to submit new endpoints.  We can use existing endpoint and test in partner’s test environment first before we move to production to validate responses.

• If a partner submits new endpoints, we would need to whitelist it before starting any testing. (Whitelisting is a weekly process)

Will combining the calls increase the traffic volume to our system significantly?

• We expect the traffic to be similar to what it is now.  But partners can optimize the call and decrease traffic volume by only returning certain flags rather than returning all of the 9 different flags we are requesting. 

Persistent Codes: These are unique codes that are meant to remain the same across multiple requests/responses. This will allow us to distinctly identify rooms/ rates and cache information in order to reduce load on Partner servers. For example, we expect the physical room type to remain fairly static.

What is the meaning of "Persistent Room Type Code / Rate Plan Code / Room Rate Code"?

• Persistent codes, i.e. Unique codes that persist between multiple requests that TripAdvsior will make, help us identify a roomtype / rate easily and accumulate this data. Given that the physical room does not change, we are asking this room to be identified with a persistent code.

Taxes and Fees breakdown: This functionality will allow Partners to be able to display taxes, fees and base rates in ways that are more relevant to each market on Tripadvisor’s platform. The new API will help Partners and Hotels stay competitive and attract bookings from travelers looking for the lowest price.

What happens if a property is unable or does not provide all the taxes / fees?

• Not every destination or hotels will charge every tax and fee we list in the documentation.  For example in NYC hotels will have a city tax, a hotel tax, and an occupancy fee but they may not have a resort fee or any of the other taxes we list in the documentation.  If a hotel does not provide a breakdown of their taxes then their displayed prices will appear less competitive in certain points of sale as we are unable to display the price minus certain taxes to show the customer the lowest price in the price finder

Not all of our properties have both taxes and fees broken down into the exact categories that Tripadvisor has listed.  What shall we do in this case? Pass the 2 taxes separately or send a calculated sum number to Tripadvisor?

• In general, if a property cannot break up the taxes and fees into the categories we provided (as in they have a tax/fee that does not match any of the ones we have), they can use the “other_tax/ fee” field.  If they have a VAT and GST as separate items, it is okay to combine the two.

Other frequently asked questions:

We are currently on older versions of the API for CPC. Will this have to be upgraded to V8 as well?

• Yes, all CPC and IB endpoints will have to be upgraded to V8 since the changes to the hotel availability call are significant.

How should we return a "no availability" response?

In response_type there can be three values; if the hotel has availability ("available"), if the hotel has no availability ("unavailable") and if the hotel has an error ("error").

So for no availability, Tripadvisor would expect to see:

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

General FAQ

Can GET requests be used instead of POST requests for hotel_availability?

We require the support of POST requests due to the large string size of each hotel object which, when including multiple hotels in a request, will easily exceed the maximum size of the query string for a GET request.

How many hotels are included in a single hotel_availability request?

This is configured with the partner according to their needs or preferences. We use a default of a maximum 50 hotels per request, but this can be reduced or increased to adjust any specific requirements. Note that reducing the number of hotels per request will translate in an increase in traffic to the API. Increasing this number will reduce traffic but will produce larger response sizes.

Why are both ta_id and partner_id values sent with each hotel object in the hotel_availability requests?

The partner_id is a unique string used by the Connectivity Partner to identify a hotel in their system. The partner_id should be used in both their hotel_inventory responses and when handling hotel_availability requests. The ta_id is Tripadvisor’s internal identification number for the hotel that was matched to the partner hotel. The ta_id is provided for debugging purposes and should not be used for any decision making.

What is the partner_url in the request hotel object and what is it used for?

This is present to maintain backwards compatibility with previous versions of the API specification and can be ignored.

How is a hotel with no availability reported in the responses?

When a requested hotel is not available for booking, it is simply not included in the response. There is no need to return any errors, messages, or availability_hotel objects with empty room_types. The absence of a hotel in the response is interpreted as having no availability for the parameters requested.

Why are all request parameters echoed in the responses?

Having the requested parameters included in the response makes it easier to interpret the results and it helps in debugging and/or identifying any problems.

Do errors in some hotels preclude returning any availability information for other hotels?

No. Response may contain both available hotels and errors. Errors, if possible, should identify which hotel IDs are affected by the given error.

What if taxes and/or fees are not available or cannot be separated from room prices?

Final prices returned for available rooms MUST always include taxes and fees. When possible, these values should be reported separately. If this is not possible then they should be left as zero. Final prices should always match the sum of base prices plus taxes and fees. If the amount of taxes and fees is available separately from the final price but it is not possible to differentiate between how much the taxes are and how much the fees are, then the total amount of taxes and fees should be returned in the fees attribute leavingtaxes as zero. Note: all prices, taxes and fees should reflect totals after all available discounts are applied.

What if there are no discounts available?

Discounts in the responses are optional. If there are no discounts available, this array can be omitted.

Should discounts be applied to the room prices returned in the responses?

Yes. Room prices should already reflect the amounts for the discounts. The room discount information will be used for display purposes to show the partners’ promotions. So it is important to already include the discounted totals in the room prices and to properly include the discount.

Can any currency be provided for prices, taxes, fees, and discounts in the response?

No. The currency returned in all responses should respect the following criteria:

• - If the currency parameter is present in the request, all values returned in the responses should be in that currency.
• - If the above is not possible, and the user_country is present in the request, then the returned currency must match the one seen by a user from this country visiting your website.
• - If the above is not possible, then the currency should be the local currency of the hotel.

Can the currency for local taxes and/or fees be different than that of the room prices?

No. It is imperative that all values for prices, taxes, fees, and discounts be provided in the same currency.

Do I need to provide credentials for Tripadvisor to access my API?

No. But you can setup basic auth on your end and provide credentials for Tripadvisor if you would like to have some access control.

Can I allowlist your IP address for security reasons?

Please contact Tripadvisor for a list of IP addresses.

What are some common issues with conversion tracking implementations?

Common issues with Conversion Tracking implementations include the following:

• calling the pixel tag from within an iframe,
• sending the gbv as a non-integer or not in cents (e.g. in dollars instead of dollar cents),
• omitting the referrer of each impression, and
• not calling the pixel.js on the page at all.

I can only add pixels to the booking widget that I provide to my hotel clients who embed it in their hotel pages. Can I enable conversion tracking for my clients?

Unfortunately, if the user is taken to a page that does not include the pixel tag in the main page (only in an iframe), then Conversion Tracking will not work correctly.

In order to work around this, you will have to place the pixel tag on the top page or outside of the iframe.

How can we use a username and password for our API?

If the partner would like to verify that Tripadvisor is the requestor, Tripadvisor can optionally send a username and password to the partner using HTTP basic access authentication. This option should be used in conjunction with HTTP over SSL (HTTPS) to ensure that the username and password cannot be stolen. Using HTTPS requires a certificate from an audited certificate authority.