| Date | Description |
|---|---|
| 23 June 2022 | Added attractionId to filtering options in /products/search endpoint |
| 22 June 2022 | Updated string length specifications in VoucherInfo schema and partnerBookingRef in /bookings/book request object |
| 20 June 2022 | Updated maximum string length specifications for /bookings/book request object (BookerInfo and CommunicationInfo schemata) |
| 3 June 2022 | Added new supplier search endpoint: /suppliers/search/product-codes |
| 1 June 2022 | Added links to various articles on the Viator Partner Resource Center throughout document |
| 26 May 2022 | Added advice about review authenticity: Key concepts - Review authenticity |
| 23 May 2022 | Added partnerNetFromPrice property to ProductSearchPricing schema spec in response from /products/search endpoint |
| 20 May 2022 | Added advice regarding whether or not an endpoint should be used to ingest details about the entire product catalog to /products/{product-code}, /products/bulk, /availability/schedules/{product-code} and /availability/schedules/modified-since endpoint descriptions. |
| 17 May 2022 | Added note about extra validation requirements for communication.phone field in request to /bookings/book endpoint |
| 11 May 2022 | Modified update frequency recommendation for /locations/bulk endpoint from 'weekly' to 'monthly' due to the relatively changeless nature of locations data. |
| 10 May 2022 | Modified description of /exchange-rates endpoint to include additional currencies (ARS, CLP, COP, ILS, PEN, PHP) available for conversion |
| 1 Apr 2022 | Modified note to Booking questions – Conditional booking questions (third bullet in 'Extra notes') |
| 22 Mar 2022 | Added note to Booking questions – Conditional booking questions (third bullet in 'Extra notes') |
| 8 Mar 2022 | Corrected "OTHER_HEALTH" to "HEALTH_OTHER" in AdditionalInfo schema used in the product response |
| 11 Feb 2022 | Removed note about no-index policy from /v1/attraction/products endpoint |
| 9 Feb 2022 | Added Booking concepts – Low-margin products section |
| 1 Feb 2022 | Added Conventions - Endpoint timeout settings section |
| 5 Jan 2022 | Corrected response schema details in /bookings/{booking-reference}/cancel and /bookings/{booking-reference}/cancel-quote to indicate that status and bookingId are required properties |
| 15 Nov 2021 | Added Basic-access Affiliate postman collection to Testing section |
| 5 Nov 2021 | Clarified description of exp-demo header parameter |
| 2 Nov 2021 | Added "LOCATION" as option for logistics.travelerPickup.locations[].pickupType in product content response |
If you require help or technical advice while you are carrying out your integration, please contact the onboarding team via email at: affiliateapi@tripadvisor.com
Our onboarding specialists have put together in-depth guides covering various topics to help you during your integration.
If you are a merchant partner, once your API integration has been completed, it must pass certification prior to going live in order to ensure data integrity and the appropriate use of API services. Please peruse and bear in mind our certification requirements prior to and during development.
If are a merchant partner, have completed your integration and your site is operational, please see the Partner Help Center - Merchant partner support page for information about what to do if you encounter a problem and require support.
The Viator Partner API v2 comprises a set of endpoints that can support the operation of a fully-featured tours and experiences booking website or application; or, it can be integrated with your existing travel-booking software.
The API exposes a variety of services that allow the retrieval of all product details, such as descriptive text and structured metadata, pricing, terms and conditions, photos and reviews. This data can either be ingested and managed on your local system, or calls can be made in real time to retrieve content in response to your users' activity on your systems.
The API allows product content, pricing and availability data to be retrieved in bulk or queried in real-time, it can perform pricing calculations according to the number and type of traveler and product option combinations available, and it supports availability and pricing holds as part of its booking and booking-cancellation functionality.
The Viator Partner-API is a designed for use by organizations partnered with Viator as Affiliate partners or Merchant partners.
Affiliate partners have full access to the areas of the API relating to content, but sales of Viator products must be carried out on the Viator site itself.
When a customer wishes to book a product from an affiliate's site, they are instead redirected to the relevant product page on viator.com via a unique URL in order to complete the purchase. Once on the Viator site, a cookie is set such that all transactions will accrue a commission for that partner until the cookie expires.
Purchases of products originating from the affiliate's site are recorded and a commission on these sales is paid periodically.
For more information on this partner type, see: Viator's Affiliate API Solution
The merchant partner relationship is one in which the partner is the merchant of record; i.e., the partner takes full responsibility for all financial records and transactions carried out by their users, as well as providing customer support with regard to providing general assistance, processing cancellations and refunds, and liaising between suppliers and customers when the need to communicate arises.
For more information on this partner type, see: Viator's Merchant API Solution
The Viator Partner-API v2.0 is a fully-redesigned system with regard to our previous API products. It includes all key fuctionality available in previous versions, but now provides nearly fully-structured data elements, and a more modern, concise and easily-understandable interface.
In addition, we have made significant improvements to performance across all functions of the API, and particularly in the area of product content and availability data ingestion.
Data ingestion has been greatly improved over previous versions of this API. Now, partners need only perform a single initial ingestion of data; then, only new and updated product content, availability and pricing information is retrieved as a 'delta update' as it becomes available.
In addition:
Improvements to availability schedule ingestion performance and usability have been achieved:
Availability is now communicated by providing an overall schedule season and specifying unavailable dates instead of available dates, a significantly more compact format that improves transfer speeds and minimizes storage needs
Availability and pricing information is given on a days-of-the-week basis, which can help with filtering and improving visibility of product availability for customers.
Information about special pricing periods that may be running throughout a product's seasons is included and is easy to interpret, allowing partners to surface promotions to customers.
Accurate pricing and applicability information for products that have 'per unit' (group) pricing is now included in the availability & pricing response; whereas support for this pricing model was limited in previous versions of this API. This allows partners to improve pricing exposure for these products.
Providing structured content is a major focus of this API. Product information that was previously stored as natural-language descriptions in a single, lengthy field is now represented in intuitively-structured, machine-interpretable schemata that empowers partners to apply finely-grained merchandising control, including:
The real-time availability check endpoint:
The booking workflow now includes an optional booking-hold step, which allows you greater predictability of a successful booking, thereby increasing conversion rates by decreasing friction in the booking flow.
The booking hold endpoint supports two kinds of hold:
The real-time availability and pricing endpoint also delivers ~5% faster performance than previous versions of this API.
The API endpoints accessible to you depend on which kind of partner you are; affiliate or merchant.
Basic-access Affiliate partners have access to a limited subset of the non-transactional endpoints of the Viator Partner API. The basic-access tier allows affiliates to quickly get started building their site with fewer complexities. The following step-by-step guide explains how to do it: Golden Path – Basic Access Affiliate Partners
Full-access Affiliate partners have access to all non-transactional endpoints; i.e., everything except booking, booking hold and booking cancellation endpoints. In addition, full-access affiliates have access to additional legacy endpoints that provide functionality that helps to support attractions.
Merchant partners have access to all endpoints apart from the attraction endpoints designed for use by affiliate partners.
The following table describes which partner types have access to which endpoints:
| Endpoint | Basic-access Affiliate | Full-access Affiliate | Merchant |
|---|---|---|---|
| /products/search | ✅ | ✅ | ✅ |
| /products/modified-since | ❌ | ✅ | ✅ |
| /v1/taxonomy/destinations | ✅ | ✅ | ✅ |
| /locations/bulk | ✅ | ✅ | ✅ |
| /products/tags | ✅ | ✅ | ✅ |
| /products/booking-questions | ❌ | ❌ | ✅ |
| /v1/taxonomy/attractions | ✅ | ✅ | ✅ |
| /v1/search/attractions | ❌ | ✅ | ❌ |
| /exchange-rates | ✅ | ✅ | ✅ |
| /v1/support/customercare | ❌ | ✅ | ❌ |
| /products/{product-code} | ✅ | ✅ | ✅ |
| /products/bulk | ❌ | ✅ | ✅ |
| /reviews/product | ❌ | ✅ | ✅ |
| /v1/product/photos | ❌ | ✅ | ✅ |
| /v1/attraction | ❌ | ✅ | ❌ |
| /v1/attraction/reviews | ❌ | ✅ | ❌ |
| /v1/attraction/photos | ❌ | ✅ | ❌ |
| /v1/attraction/products | ✅ | ✅ | ❌ |
| /availability/check | ❌ | ✅ | ✅ |
| /availability/schedules/{product-code} | ✅ | ✅ | ✅ |
| /availability/schedules/modified-since | ❌ | ✅ | ✅ |
| /availability/schedules/bulk | ❌ | ✅ | ✅ |
| /bookings/hold | ❌ | ❌ | ✅ |
| /bookings/book | ❌ | ❌ | ✅ |
| /bookings/status | ❌ | ❌ | ✅ |
| /bookings/cancel-reasons | ❌ | ❌ | ✅ |
| /bookings/{booking-reference}/cancel-quote | ❌ | ❌ | ✅ |
| /bookings/{booking-reference}/cancel | ❌ | ❌ | ✅ |
Access to the API is managed using an API key that is included as a header parameter to every call made to all API endpoints described in this document.
| Header parameter name | Example value |
|---|---|
| exp-api-key | bcac8986-4c33-4fa0-ad3f-75409487026c |
If you do not know the API key for your organization, please contact your business development account manager for these details.
Please note that language localization is now controlled on a per-call basis. Previously, localization settings were configured per API-key; whereas, under the present scheme, organizations have a single API key.
Language localization is accomplished by specifying the desired language as a header parameter (Accept-Language). See Accept-Language header for available langage codes.
The Accept-Language header parameter controls the language into which the natural language fields in the response from each endpoint will be translated.
Note: You can only specify languages that have been configured for your API-key. Therefore, if you wish to access additional languages, you will need to contact your business development account manager.
| Language | Accept-Language parameter value |
|---|---|
| English | en, en-US |
| Danish | da, da-DK |
| Dutch | nl, nl-NL |
| Norwegian | no, no-NO |
| Spanish | es, es-ES |
| Swedish | sv, sv-SE |
| French | fr, fr-FR |
| Italian | it, it-IT |
| German | de, de-DE |
| Portuguese | pt, pt-PT |
| Japanese | ja, ja-JP |
| Chinese (traditional) | zh-TW |
| Chinese (simplified) | zh-CN |
| Korean | ko, ko-KR |
In order to ensure the predictability of the behavior of this software, we have implemented a versioning strategy to handle updates to the API contract, as well as a mechanism to specify which version of the API you wish to access.
When we release a new version of this API, partners have the option of continuing to use the existing version or migrating to the updated version when they are ready.
The approach to versioning for this API is as follows:
The following types of change are considered backward-compatible, and will not result in a version release when introduced. Therefore, partners must ensure their implementation can handle such changes gracefully.
These changes comprise:
The following types of change are considered breaking changes and will result in the release of an incremented version of this software:
It is mandatory to specify which version of the API you wish to use via the 'Accept' header parameter in the request to each API endpoint; e.g., Accept: application/json;version=2.0. Omitting the version parameter will result in a 400 Bad Request response.
Example valid request:
curl --location --request GET 'https://api.sandbox.viator.com/partner/products/modified-since?cursor=MTU5MjM1NTM0MXwxMTM5ODZQNA==' \
--header 'exp-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx' \
--header 'Accept-Language: en-US' \
--header 'Accept: application/json;version=2.0'Example error response:
{
"code":"INVALID_HEADER_VALUE",
"message":"Accept header is missing or has invalid version information",
"timestamp":"2020-09-02T03:43:23.303946Z",
"trackingId":"3D45567E:2D25_0A5D03AB:01BB_5F4F14A5_394639:3DB7"
}This API supports gzip compression. Therefore, if you include gzip in the Accept-Encoding header parameter in the request, the API will respond with a gzip-compressed response.
If you wish to implement internal timeout settings for calls to this API, we recommend a setting of 120s.
This is due to the fact that some of the products in our inventory rely on the operation of external supplier systems, which we do not control. Because of that, it may take up to 120s to receive a response when making a booking. In rare cases, booking response times in excess of 120s can sometimes occur.
This means that a booking may have actually succeeded even if the bookings/book service times-out or responds with a HTTP 500 error.
Therefore, it is strongly recommended that you check the status of the booking using the /bookings/status endpoint to make sure the booking was not created before you attempt to make the booking again.
Furthermore, you can avoid creating duplicate bookings by making sure that you supply the same value for partnerBookingRef in the request to /bookings/book as you did for the booking you believe may have failed. The partnerBookingRef value must be unique; therefore, a duplicate booking will not be created.
You can retrieve the core product-content details from the following endpoints:
You can retrieve the availability schedules for products using the following endpoints:
There are nine endpoints necessary for the seamless operation of this API that have not yet been updated to the 'v2-style' functionality of the other endpoints.
V1 endpoints available to both partner types:
destinationIdattractionIdV1 endpoints for affiliate partners only:
These nine v1 endpoints operate differently to the v2 endpoints.
In particular:
data elementsuccess element being true or false, not the HTTP status code, which will be 200 in every case in which a response was able to be returned, regardless of any error(s)Example V1 error response:
{
"errorReference": "C0AA8A15:ED5E_0A2806D6:01BB_5F755F7F_54AA9:03D6",
"data": null,
"dateStamp": "2020-09-30T21:47:59+0000",
"errorType": "EXCEPTION",
"errorCodes": [
"UNKNOWN_ERROR"
],
"errorMessage": [
null
],
"errorName": "NullPointerException",
"extraInfo": {},
"extraObject": null,
"success": false,
"totalCount": 1,
"errorMessageText": [],
"vmid": "331009"
}This following diagram shows the different data element names in the responses from the v1 and v2 product content endpoints from which the sections of the product display page for product 114491P5 on Viator.com are sourced.
treatAsAdult flagIn v1 of this API, the requirement (or lack thereof) for an adult to be included in a booking was communicated via the treatAsAdult flag in the items of the ageBands[] array in the response from the /product endpoint. The default assumption in the v1 API was that at least one adult is required per booking unless the treatAsAdult flag is set to true for a non-adult age-band, in which case the inclusion of one traveler from that age-band is sufficient to fulfil the requirement.
See: Key concepts – Working with age-bands (Partner API v1) for more information.
In v2 of this API, whether an adult traveler is required in order to make a booking is communicated via the bookingRequirements.requiresAdultForBooking flag in the response from any of the product content endpoints.
If this flag is true, at least one traveler from one of the 'ADULT', 'SENIOR' or 'TRAVELER' age-bands must be included when making the booking.
In version 2 of the Viator API, the concept of 'product categories' that was utilized in version 1 has been replaced by tags.
To learn more about tags, see this article: Viator tags, explained
In version 1, the list of categories and subcategories was available on a per-destination basis using v1's /taxonomy/cateogories endpoint. This list could be used to construct a category tree for display to the user; or, to aid in search.
In version 2, tags can be used to replicate this functionality simply by mapping the original v1 subcategory to its v2 tag equivalent. Tag information is available from the /products/tags endpoint.
These mappings are detailed in this Excel spreadsheet: v1 category and subcategory mappings to v2 tags.
All v2 tags that correspond to categories or subcategories in v1 are listed in the spreadsheet, which can be interpreted as per this example:
| v2 tag display name | v2 tagId | v1 subcategoryId | v1 subcategoryName | v1 categoryId | v1 groupName |
|---|---|---|---|---|---|
| Hot Air Balloon Rides | 12027 | 3 | Balloon Rides | 1 | Air, Helicopter & Balloon Tours |
The example above shows that the v2 tag "Hot Air Balloon Rides", which has a tagId of 12027, corresponds to v1's "Balloon Rides" (subcategory 3), which falls under "Air, Helicopter & Balloon Tours" (category 1).
In the response from the v2 endpoint /products/tags, "Hot Air Balloon Rides" (tagId: 12027) is shown here:
{
"tagId": 12027,
"parentTagIds": [
21715,
21913,
21436,
21909
],
"allNamesByLocale": {
"de": "Heißluftballonfahrten",
"no": "Turer i varmluftballong",
"sv": "Flygturer i varmluftsballong",
"pt": "Passeios de balão",
"ko": "열기구 타기",
"en_AU": "Hot Air Balloon Rides",
"en": "Hot Air Balloon Rides",
"it": "Giri in mongolfiera",
"fr": "Vols en montgolfière",
"en_UK": "Hot Air Balloon Rides",
"es": "Paseos en globo aerostático",
"zh": "热气球之旅",
"zh_HK": "熱氣球之旅",
"zh_TW": "熱氣球之旅",
"ja": "熱気球での飛行体験",
"zh_CN": "热气球之旅",
"da": "Varmluftballonture",
"nl": "Ballonvaarten"
}
} This corresponds to the following result (Balloon-rides; category 1, subcategory 3) in the response from the v1 endpoint /taxonomy/categories:
{
"sortOrder": 1,
"thumbnailURL": "https://hare-media-cdn.tripadvisor.com/media/attractions-splice-spp-154x109/06/75/b7/96.jpg",
"subcategories": [
{
"sortOrder": 1,
"subcategoryUrlName": "Balloon-Rides",
"subcategoryId": 3,
"subcategoryName": "Balloon Rides",
"categoryId": 1
},
{