Viator Partner API v1 to v2 Upgrade Path

Quick find

1

Preparing for the migration project

2

Migrating product content ingestion

3

Migrating ingestion of product-availability schedules

4

Migrating booking endpoints

5

Migrating the search endpoint

6

Migrating the reviews endpoint

7

Summary and next steps

1. Preparing for the migration project

Before you begin any actual integration work, there are a few steps you will need to complete in order to be granted access to the version 2 sandbox/development API.

You will need to:

Create an account for your organization on the Viator Partner Platform

If you know in which way you are partnering with Viator, you can:

Otherwise, you should first learn about the differences between the partner types.

Generate and obtain an API-key that will allow you to access the v2 sandbox server.

In contrast with version 1 of the API, you will only need to use one API-key for all interactions with the v2 API, even if you are operating a multi-lingual/multi-locale site. Bear in mind that during the migration process, while your system is in a hybrid state, you will still need to use your v1 API-key(s) to access the v1 endpoints that you are yet to migrate.

↑ Back to top

2. Migrating product content ingestion

The content ingestion workflows in v2 differ substantially from those in v1. Improving these processes has been a major focus in the development of v2, yielding a far more robust and intuitive approach to this important component of the system’s operation.

What we describe here is intended to be an efficient, step-by-step method of migrating your content ingestion workflow such that it no longer relies on any v1 endpoints, but without requiring a full refactorization of your code to support the final recommended v2 approach.

Product content ingestion strategy

Partners are able to decide whether they intend to expose and sell either all – or, a subset – of the products available in the Viator catalog. v1’s content ingestion workflow implied that the subset approach was preferred given that ingesting the entire catalog required multiple steps to ensure all products were included.

Whereas, in v2, inclusive, full-catalog ingestion is considered the best-practice approach, and any efforts to curate the catalog should focus on which products or product categories that you might, for some reason, wish to exclude.

Specifically, v1-integrated partners ingested all or a subset of the Viator product catalog by:

  1. Retrieving all destination identifiers (destId) from /taxonomy/destinations/
  2. Calling /search/products for each desired destination
  3. Collating all unique product codes
  4. Call /product using the code for each product to get its full details

If this describes your strategy, be assured you will be able to continue your operations in this way.

If your strategy was to ‘sell only certain products’, we suggest considering whether ‘selling all but certain products’ might be a more effective approach; i.e., taking advantage of the /products/modified-since endpoint to receive delta-updates on any changes that have occurred across the full product catalog almost as soon as the supplier publishes them. Nonetheless, the choice remains yours. However please note that only this endpoint may be used for ingestion of the product catalog.

If you don’t ingest product details into your database, you would need to make real-time requests to the /products/{product-code} endpoint only for one product selected by the customer from the search.
Please check two models for API data management in this article.

Ultimately, a full implementation of the v2 API allows you to stay updated regarding all product changes in near-real-time and apply your own filters to curate your product catalog according to any of the product’s properties you desire. However, you will already have a convention for which products you include.

See:

Mapping v2 product data to a v1 implementation

Creating the logic that pieces together all the product-content data points that you need for your v1-oriented implementation from where and in which format they appear in v2 will comprise the bulk of the effort in this part of the v1-v2 upgrade project.

Sometimes, this will be as simple as directly mapping one variable to another, but due to (in particular) the rearrangement and structuring of previously unstructured data, a number of items will require some extra effort to accommodate.

While v2’s product content endpoints – i.e., /products/modified-since, /products/bulk and /products/{product-code} – provide most of the elements necessary to fulfill what had been provided by v1’s /product endpoint, you will need to call the following v2 endpoints to obtain the data needed to replicate some of the elements in the v1 product response:

 

Standard v2 endpoints:

v1-v2 bridging endpoints:

There are three kinds of mapping you will need to undertake in order to obtain everything you would presently be getting from v1’s /product endpoint:

1

Fields that have a direct plug-n-play relationship with a corresponding field from v2's /products/; i.e.:

  • supplierName → supplier.name
  • supplierCode → supplier.reference
  • webURL → productUrl (only visible to the affiliate partner types)
  • rating → reviews.combinedAverageRating
  • shortDescription → description
  • reviewCount → reviews.totalReviews
  • code → productCode
  • title → title

Note: v1 → v2, respectively

2

Fields that are fulfilled in a different way (e.g., with structured data) but are still within the scope of /products/:

Note: v1 → v2, respectively

ageBands[].treatAsAdult
This field’s purpose in v1 was to accommodate products for which an adult traveler was not specifically required. Under v2, the system is slightly different. If a product can be booked without a traveler in the ADULT age-band, bookingRequirements.requiresAdultForBooking will be false in the product content response, implying that travelers of any age-band may book the tour. If true, at least one traveler must be from the ADULT or SENIOR age-band category.

merchantTermsAndConditions → cancellationPolicy

There are a number of differences in the syntax and structure of the cancellation policy information provided by the respective APIs. Please consult and compare the following manual sections for further information:

Version 1:

Version 2:

3

Fields that require information from another v2 endpoint in order to fulfill:

From the /availability/schedules/ endpoint:

 

From /upgrade/categories:

In v2, the duality that was v1’s category (catIds[]) and subcategory (subCatIds[]) arrays has been unified under the singular concept “tags”. There are significant differences in these systems, and a bridging endpoint (/upgrade/categories) has been created to convert between the two taxonomies.

Information about how tags work is available from the following resources:

 

From /upgrade/tourgrades/{product-code}:

Mapping what were known as tourGrades under v1 and are now known as productOptions under v2.

More information about product options is available here:

However, there are differences in syntax between the v1 and v2 conventions. A bridging endpoint has been created to fill the gap for you:

 

From /upgrade/agebands:

While the name of the field in the response – ageBands – remains the same, working with age bands has changed markedly enough that you will need to scrutinize the two systems, in particular the age-band naming conventions, to correctly map that data.

An informative article has been written on this subject – Partner resources center: Implementing age-bands and pax mix – that will no doubt be of great help to you.

Another resource that should also be useful:

Further to that, bridging between the v1 and v2 age-band lexicon can be carried out using the following upgrade endpoint: /upgrade/agebands/

 

From /v1/taxonomy/destinations:

The following elements can be looked up using the /v1/taxonomy/destinations endpoint, which has identical functionality to its v1 equivalent. Only the destination ID is communicated in the v2 response, so the remaining elements must be obtained from the taxonomy response. The field names you can plug-’n’-play are:

  • primaryDestinationName → destinationName
  • primaryDestinationUrlName → destinationUrlName

For more information about destinations, see these sections of the v2 specification manual:

 

From /v1/product/photos:

The images array in the v2 response contains image details from the supplier for the product in question. From the length of this array you can determine the value for v1’s photoCount.

userPhotos can be determined using the response from v2’s /v1/product/photos endpoint if the /reviews/product endpoint is not used for this purpose (however we recommend using the /reviews/product endpoint to get traveler photos, especially if you already retrieve reviews from that endpoint)

An informative article on this topic is available here: Partner resources center: Implementing traveler photos via the Viator API

 

From /reviews/product:

While statistics regarding reviews are available from v2’s product content response, in order to get the full review text and its metadata, you must retrieve these from v2’s /reviews/product endpoint.

You should use this endpoint to retrieve traveler photos (photosInfo).

 

From /bookings/book:

All voucher information you will require can be found in the voucherInfo object in the response from /bookings/book when a booking is made. In addition to html vouchers we added a pdf voucher and you can select the voucher type when submitting the /bookings/book request.​

See: Booking concepts – Booking questions for more information about how to find out whether or not the first and/or last names of all travelers are required (as communicated previously by v1’s allTravellerNamesRequired element) but with v2 conventions.

↑ Back to top

3. Migrating ingestion of product-availability schedules

 

Ingesting availability schedules

In v2 of this API, product availability data has undergone significant restructuring with respect to its presentation and therefore the workflows surrounding it.

Your first step will be to set up the logic to retrieve and interpret a product’s availability schedules.

If you don’t ingest availability schedules, you will need to use the /availability/schedules/{product-code} endpoint to get schedules for a single product selected by the customer from search. A single request to this endpoint returns a response that includes all the availability schedules and pricing for a particular product.

If you ingest availability schedules, you should retrieve schedules for all products in bulk with v2’s /availability/schedules/modified-since endpoint. Only this endpoint can be used to ingest availability and pricing schedules. See also: v2 manual: Ingesting and updating availability.

This response was designed with a view to efficiently communicate a fairly complex data structure; as such, you will need to create some logic on your end in order to expand the availability schedule ‘instructions’ into explicit table entries in your local database.

This will become evident once you read:

As mentioned in the previous section, the following fields from v1’s /product endpoint response can be extracted from the availability schedules data:

  • currencyCode
  • priceFormatted
  • merchantNetPriceFromFormatted
  • merchantNetPriceFrom
  • price
  • specialOfferAvailable
  • operates

v1’s pricingUnit field in the response from /booking/availability/tourgrades/pricingmatrix is now communicated via v2’s product content endpoints. Compare the following sections in the v2 and v1 manuals, respectively, to see how to transpose this information.

An informative guide regarding pricing in the merchant API is available here: Partner Resource Center: Calculating Product Pricing with the Merchant API

Currencies
In v2, product prices are always denominated in the supplier’s local currency, the identity of which can be found in the currency field at the top level of the availability schedules response. To convert to your customer’s currency, v2’s /exchange-rates endpoint must be used.

↑ Back to top

4. Migrating booking endpoints

At this stage, your system should have all the required modifications in place such that you can commence migrating to the v2 booking workflow. In v2, the following endpoints are used to make a booking:

Comparison of booking workflows

The v2 booking workflow also differs somewhat markedly from how things were done under v1. You can compare the two systems by reviewing the following sections:

Pricing and availability holds

v2 also allows for the securing of an availability and/or pricing hold (depending on the product) prior to finalizing the booking as a highly recommended step in the booking process, as doing so ensures that the product remains available at the correct price while the customer finalizes payment during checkout. However, as such functionality was not within the scope of v1, you might also elect to add this feature at a later point.

Notable differences

In the v2 booking workflow, the distributorRef and distributorItemRef fields have been replaced by a single partner-specified identifier for the booking: partnerBookingRef. This value is sent in the request to /bookings/book.

There are marked differences between v1 and v2 with respect to which booking questions must be answered and how they should be answered when making a booking request. Review and contrast the following sections from the respective manuals:

↑ Back to top

5. Migrating the search endpoint

Under v1, product searching via the /search/products endpoint was a key component of the product ingestion workflow for all partner types. Under v2, this remains the case for basic-access affiliate partners, while for other partner types it is considered an optional modality, with the recommended approach being to ingest the entire catalog into a local database and then extract from that the products you wish to include on your site according to your own criteria.

v1 has three search-related endpoints that you might have integrated to:

  1. /search/products – Searches for products based on:
    1. the destination (locale) in which the tour/product operates OR its association with an attraction (but not both)
    2. its category and/or subcategory
    3. the time period during which it operates
  2. /search/products/freetext – Performs a ‘free text’ search that returns any products including the search string across a variety of product characteristics.
  3. /search/products/codes – Returns the product details for multiple products. The v2 equivalent of this endpoint is /products/bulk, which is not technically a ‘search’ endpoint and therefore will not be discussed further in this section.

In migrating to v2, you will use the /products/search and /search/freetext endpoints to satisfy these functions.

This article introduces v2’s /products/search endpoint and its capabilities: Partner Resources Center: New product search capabilities on the Viator Partner API.

The following article describes how to implement a search-based ingestion methodology that you might find informative even though it was written for the basic access affiliate type: Golden Path – Basic Access Affiliate Partners

A key difference between the v1 and v2 search functions relates to the changes in nomenclature with respect to v1’s categories and subcategories having been replaced by tags in v2. You may need to use the /upgrade/categories endpoint to translate between these two formats.

↑ Back to top

6. Migrating the reviews endpoint

There are a few differences between v1 and v2 with respect to the way in which reviews and user-submitted photos are presented via the API.

Whereas in v1, the full details for the first 24 reviews were provided within the response from v1’s /product endpoint (with the remainder available from v1’s /product/reviews endpoint in the event that more than 24 reviews were available), in v2, only summary data regarding product reviews is included in the product content response.

Therefore, in order to get any of the actual user-submitted review content under v2, you will need to make a call to v2’s /reviews/product endpoint. v2 also provides enhanced review metadata, such as on which platform the review was submitted and links to any images that were provided by the user when the review was submitted.

As such, v2’s /reviews/product endpoint also fulfills the content that was provided by v1’s /product/photos endpoint.

Translating between these two formats should not present any great difficulty, as a comparison of the available data will no doubt illustrate.

Please refer to the following resources:

In summary: whereas, under v1, it might have been adequate for your needs to just use the review content that was included in the /product response, under v2 you will need to make a call to a separate endpoint to obtain that data.

Note:

The sort order specifiers for v1 and v2 do differ, so please pay attention to these differences; i.e.:

  • v1’s sortOrder request parameter took one of:
    • “REVIEW_RATING_A”: sort by traveler rating average (ascending)
    • “REVIEW_RATING_D”: sort by traveler rating average (descending)
    • “REVIEW_RATING_SUBMISSION_DATE_D”: Most recent first
  • v2’s sortBy request parameter takes one of:
    • “HIGHEST_RATING_PER_LOCALE” – sort by rating (descending) for each locale
    • “MOST_RECENT_PER_LOCALE” – sort by publication date (descending) for each locale
    • “MOST_HELPFUL_PER_LOCALE” – sort by the number of ‘helpful’ votes (descending) for each locale
    • “HIGHEST_RATING” – sort by rating (descending) across all locales
    • “MOST_RECENT” – (default) sort by publication date (descending) across all locales
    • “MOST_HELPFUL” – sort by the number of ‘helpful’ votes (descending) across all locales

↑ Back to top

7. Summary and next steps

To recap, the purpose of this guide has been to show you how to, with minimal effort, completely eliminate your reliance on any of the v1 endpoints. It is necessary to do this because, beyond December 1, 2023, v1 will be officially deprecated, no longer supported; and, in fact, not be available at all in any capacity.

It is only applicable to partners who have a complete working integration to v1.

Once you have completed all the steps in this guide, you will have all the functionality that you had in v1.

Between now and December 1, 2023, we will be ending various levels of support:

While we would strongly recommend taking full advantage of all the new features available under v2, this can be done at a pace most suitable for you.

Before you can exit the sandbox and make real-life bookings, merchant partners will need to have their integration certified before being granted an API-key that allows access to the live production API. Affiliate partners should consult with the onboarding team for a final check before going live.

↑ Back to top