Viator Partner API (2.0)

Download OpenAPI specification:Download

Updates

Latest updates:

Date Description
9 June 2021 Added Booking concepts – supplier communications
9 June 2021 Added Booking concepts – working with age bands section
4 June 2021 Added premium viatorUniqueContent element to ActiveProduct
27 May 2021 Added Booking-concepts – Per-person and unit pricing section
21 May 2021 Added reviews element to responses of product content endpoints
14 May 2021 Added Age-bands section to Booking concepts - Booking questions section
5 May 2021 Updated Conditional booking questions table in Booking concepts - Booking questions section
25 Mar 2021 Added v1 endpoints for affiliate partners

Previous updates: See Update log

About

Viator Parter-API v2

What is it?

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.

Who is it for?

The Viator Partner-API is a designed for use by organizations partnered with Viator as Affiliate partners or Merchant partners.

Affiliate 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

Merchant partners

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

New features in this version

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.

Simplified and optimized 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:

  • A single end-point allows both bulk ingestion and delta updates, which can be controlled using a pagination cursor or with a time-stamp parameter to allow for point-in-time ingestion of any new updates and easy recovery from ingestion failure
  • The structure of a product's pricing and availability schedules has been simplified to reduce response size

Product content

  • All pricing is standardized to the supplier's currency, avoiding the need to update on account of exchange rate fluctuations
  • Structured location, tag, booking question, review and photo data is available from separate endpoints to allow for parallel ingestion, and resusable data can be ingested once and applied globally

Availability schedule information

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.

Structure-rich content

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:

  • Tour itineraries with comprehensive location data to allow for graphical display and advanced search
  • Tour details, inclusions and dynamic health & safety information to support changing requirements due to global pandemic response initiatives
  • Machine-parseable booking questions and answers

Improved real-time availability and pricing checking

The real-time availability check endpoint:

  • Allows you to check availability and pricing in real-time for a specific product / product-option / date / starting time / pax mix combination
  • Returns the ticket availability status along with a pricing breakdown (by age band) and total price (all age bands) in a simplified format to reduce response size
  • Pricing components are stated explicitly, including the Recommended Retail Price (RRP), partner net price, special-offer pricing and booking fee component details

Improved booking workflow

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:

  • Inventory/availability hold (increased likelihood of receiving a booking confirmation)
  • Pricing hold (mitigates against pricing changes at the time of booking)

The real-time availability and pricing endpoint also delivers ~5% faster performance than previous versions of this API.

Access to endpoints

The API endpoints accessible to you depend on which kind of partner you are; affiliate or merchant.

Affiliate partners have access to all non-transactional endpoints of the Viator Partner API. I.e., everything except booking, booking hold and booking cancellation endpoints. In addition, 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 Affiliate partners Merchant partners
/products/{product-code}
/products/modified-since
/products/bulk
/products/tags
/availability/check
/availability/schedules/{product-code}
/availability/schedules/modified-since
/availability/schedules/bulk
/bookings/hold
/bookings/book
/bookings/cancel-reasons
/bookings/{booking-reference}/cancel-quote
/bookings/{booking-reference}/cancel
/locations/bulk
/exchange-rates
/v1/taxonomy/destinations
/v1/taxonomy/attractions
/v1/product/reviews
/v1/product/photos
/v1/search/attractions
/v1/attraction
/v1/attraction/reviews
/v1/attraction/photos
/v1/attraction/products
/v1/support/customercare

Authentication

API-key

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.

Localization

Accept-Language header parameter

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

Conventions

API versioning strategy

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.

  • Note: The version of this API that this document pertains to is that indicated in the title of this document.

The approach to versioning for this API is as follows:

Global versioning

  • Version numbers are global across all endpoints. When a new version of this API is released, all endpoints will increment to the latest version. Viator does not support a heterogenous implementation with calls being made to different endpoints with different version numbers.

Version release and deprecation

  • New versions of this software are released on an ad-hoc basis. Breaking changes will always result in a version increment.
  • Viator will inform partners about all version releases, including details about the new features available and any breaking changes that have been introduced.
  • Once a version of the API is deprecated, you will have a minimum of 12 months from the date of receiving notice of the change in which to modify your systems. Requests made to deprecated endpoint versions may result in a 400 Bad Request response after 12 months.

Release candidates

  • Release candidate (RC) versions of this API may be made available to allow partners to preview changes in a non-production (sandbox) environment. When available, RC versions will be announced in this documentation, however these will not be subject to version control and breaking changes may be introduced prior to official release.

Release criteria

Backward-compatible changes

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:

  • Introduction of new API endpoints
  • Addition of any properties to an endpoint's response schema
  • Addition of non-required properties to an endpoint's request schema
  • Unexpected receipt of an HTTP redirect response code (301 Moved Permanently or 302 Found)
  • Addition of new HTTP methods (POST, GET, PUT, PATCH, DELETE, etc.)
  • Addition of new key values to existing fields that represent a set, insofar as no operating logic is likely to be affected

Breaking changes

The following types of change are considered breaking changes and will result in the release of an incremented version of this software:

  • Addition of required properties to an endpoint's request schema
  • Removal of required properties from an endpoint's request or response schemata
  • Changing the data-type or format (e.g., date format) of an existing field in an endpoint's request or response schemata
  • Adding, removing or changing the meaning of the HTTP status codes in an endpoint's response
  • Removing or modifying the Content-Type on existing endpoints
  • Modifying or removing field key values in a set
  • Modifying the operationId of an endpoint

Version specification mechanism

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

Accept-Encoding

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.

Key concepts

Content ingestion endpoints

Product content endpoints

You can retrieve the core product-content details from the following endpoints:

Availability schedules endpoints

You can retrieve the availability schedules for products using the following endpoints:

V1 endpoint conventions

There are ten 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:

V1 endpoints for affiliate partners only:

These ten v1 endpoints operate differently to the v2 endpoints.

In particular:

  • Standard error information is included at the top level of the response object
  • Response payload is contained in the data element
  • Success or failure is represented by the success 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)
  • Naming and other conventions may be different to what is expected – please review the specification carefully
  • It is not necessary to include version information in the request header when calling these endpoints (see: Version specification mechanism)

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

V1 to V2 migration reference

Product display page

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.

Operational differences

v1's treatAsAdult flag

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

Review count and average rating

In this version of the Viator Partner API (v2), product review information is not supplied via the product content endpoints, as it was in version 1. Instead, product reviews can be retrieved via the /v1/product/reviews endpoint.

For more information see: Determining ratings

Product options

Any particular product may consist of a number of variants, each of which is referred to as a 'product option'. In previous versions of this API, and in the tours and activities sector in general, product options are also referred to as 'tour grades'.

For example, product options might represent different departure times, tour routes, or packaged extras like additional meals, transport and so forth.

The product options available for a product can be found in the productOptions array in the responses from any of the product content endpoints.

An example productOptions array for the product 5010SYDNEY is as follows:

"productOptions": [
    {
        "productOptionCode": "48HOUR",
        "description": "Duration: 2 days: FREE BONUS ENTRY to Sydney Tower with every Deluxe ticket end 31st March<br/>48 Hour Premium Ticket: Unlimited use on Big Bus Sydney & Bondi Tour for 48 hours from time of first use PLUS a guided walking tour of The Rocks, Syd",
        "title": "48 Hour Premium Ticket ",
        "languageGuides": [...]
    },
    {
    "productOptionCode": "TG1",
        "description": "Hop-on Hop-Off and Attractions: 48hr Big Bus Tours, 1-day Hop-On Hop-Off Harbour Cruise, 4 Attractions: Tower Eye, Madame Tussauds, Wildlife Zoo, Aquarium<br/>Duration: 2 days<br/>Complimentary Walking Tours: Complimentary English-speaking guided walking tour of “The Rocks” historic and harbourside precinct.",
        "title": "48Hour Deluxe PLUS Attractions",
        "languageGuides": [...]
    },
    {
        "productOptionCode": "24HOUR",
        "description": "Unlimited use on Big Bus Sydney & Bondi Hop-on Hop-off Tour for 24 hours from time of first use",
        "title": "24 Hour Classic Ticket ",
        "languageGuides": [...]
    },
    {
        "productOptionCode": "DELUXE",
        "description": "Big Bus and Habour Cruise: Combine two great Sydney experiences into one with a hop-on hop off Big Bus Tours and a hop-on hop-off Sydney Harbour cruise <br/>Duration: 2 days: FREE BONUS ENTRY to Sydney Tower with every Deluxe ticket end 31st March<br/>Complimentary Walking Tour: Complimentary English-speaking 90-minute guided walking tour of “The Rocks” historic and harbourside precinct.",
        "title": "48 Hour Deluxe Bus and Cruise",
        "languageGuides": [...]
    }
]

This product has four product options, each with an identifying code given in the productOptionCode field:

  • "48HOUR"
  • "TG1"
  • "24HOUR"
  • "DELUXE"

Not all products have multiple product options. Products with no variations will not include a productOptions element in the response.

Product options are essentially a subcategory of the tour or activity. You will need to specify the product option you wish to book when making a booking.

Availability schedules

The availability schedules endpoints provide information about the availability of a product (along with its various product options and starting times, if they exist) and its pricing.

This section explains how to interpret the response from the availability schedules endpoints.

Example response snippet from /availability/schedules/10212P2 (some starting times were removed for brevity):

{
    "productCode": "10212P2",
    "bookableItems": [
        {
            "productOptionCode": "TG45",
            "seasons": [
                {
                    "startDate": "2019-05-01",
                    "endDate": "2021-12-31",
                    "pricingRecords": [
                        {
                            "daysOfWeek": [
                                "MONDAY",
                                "TUESDAY",
                                "WEDNESDAY",
                                "THURSDAY",
                                "FRIDAY",
                                "SATURDAY",
                                "SUNDAY"
                            ],
                            "timedEntries": [
                                {
                                    "startTime": "11:00",
                                    "unavailableDates": [
                                        {
                                            "date": "2020-09-16",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-23",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-22",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-27",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-29",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-30",
                                            "reason": "SOLD_OUT"
                                        }
                                    ]
                                },
                                {
                                    "startTime": "10:00",
                                    "unavailableDates": [
                                        {
                                            "date": "2020-09-25",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-26",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-28",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-27",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-30",
                                            "reason": "SOLD_OUT"
                                        },
                                        {
                                            "date": "2020-09-29",
                                            "reason": "SOLD_OUT"
                                        }
                                    ]
                                },
                                {...}
                            ],
                            "pricingDetails": [
                                {
                                    "pricingPackageType": "PER_PERSON",
                                    "minTravelers": 1,
                                    "ageBand": "INFANT",
                                    "price": {
                                        "original": {
                                            "recommendedRetailPrice": 0.00,
                                            "partnerNetPrice": 0.00,
                                            "bookingFee": 0.00,
                                            "partnerTotalPrice": 0.00
                                        }
                                    }
                                },
                                {
                                    "pricingPackageType": "PER_PERSON",
                                    "minTravelers": 1,
                                    "ageBand": "ADULT",
                                    "price": {
                                        "original": {