Technical Guide for API Partners

Welcome to the Viator Partner Program! In this guide, we’ll go through a variety of topics regarding how you can best use the Viator Partner API to display, promote and sell Viator’s 300,000+ products on your own website or travel-booking system. For our partners who are the merchant of record (merchant partners), we will also discuss how to interact with our booking systems via the Partner API to support your booking/checkout workflow.

All documentation pertaining to the Viator Partner API can be found here. If you have any questions about your integration, please reach out to affiliateapi@tripadvisor.com at any time.

Please note that which endpoints you are able to access depends on what kind of partner you are. Access to endpoints depends on your partner type and the endpoints in this guided will be marked. For example, endpoints marked as below would not be accessible by Basic-access Affiliate:

⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Merchants

Furthermore, in a small number of cases an endpoint accessible to both partner types will behave differently between merchants and affiliates. We will mention these differences in the relevant sections.

Getting started: choosing ingestion-model or search-model

While merchant partners are required to use the ingestion model, our affiliate API partners have two choices when deciding how they will connect to Viator’s supply: they can choose an ingestion-model or a search-model.

Ingestion model

  • The ingestion model of connecting to Viator’s supply requires that the partner builds and maintains a local database of products and also requires that the partner makes regular calls to Viator to ensure that product and availability information is up to date.
  • This model is required for merchant partners and is ideal for partners that want a full-scale tours and activities integration and can manage large amounts of data

Search model

  • The search model is an easiest and faster way to connect to Viator’s supply via an API integration. The amount of data returned in a search API request is less than what would be returned using the ingestion model, and therefore there is no need to store any data.
  • This model is ideal for partners that are looking for a fast integration and do not desire a full tours and activities integration.

Building your local database (ingestion model)

In order to begin selling Viator experiences, you must ingest and keep up-to-date a database of Viator products and availability schedules. Products may then be managed and filtered according to your business needs. All our products are categorized under a destination hierarchy. You will use this hierarchy to build your database and effectively catalogue our products.

/v1/taxonomy/destinations

✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

Get details of all destinations

  • Every product in the Viator catalogue is categorized according to the destination/locale in which it operates. This endpoint returns a complete list of Viator destinations, including destination names and parent identifiers.
  • This endpoint is used to help define the locations of products (i.e. primary and secondary) for the purpose of merchandising products. For example, Disneyland Paris’s primary destination is Paris, even though the actual location (secondary location) is Marne-la-Vallee. Travelers are more likely to search for Paris when looking for Disneyland Paris than Marne-la-Valle.
  • This endpoint is used to provide navigation on your site, through drilldown lists, combo boxes, or breadcrumbs.
  • While destinations rarely change, we recommend refreshing the list of destinations weekly.

/v1/taxonomy/attractions

✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

Gets all attractions for a destination

  • This endpoint returns all attractions within a destination and is used to help merchandize products by attraction.
  • This is also useful for navigation as well as building out basic attractions pages.

Ingesting products & keeping the product catalogue up to date

Key features of these endpoints

"

Ingest over 300,000+ products quickly and efficiently

R

Updating product content with fewer, but more frequent requests provides travelers with accurate information

Only ingesting new or modified product information speeds up load times

f

Structured data fields make it easier to break out key information and merchandise products

/products/modified-since

⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

1a. Perform an initial ingestion of all product data

  • Performs an initial ingestion of all product data into a local database. You may filter out any products during the initial ingestion.

1b. Ingest only new or updated product data

  • Used to ingest only new or updated product information. Products are considered updated when the supplier makes any changes to the product’s details, excluding pricing and availability changes, which are retrieved from the availability schedule endpoint.
  • We recommend polling this service hourly to look for updates and to avoid any discrepancies.

/products/{product-code}

✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

2. Pull product data for a single product

  • Pulls info for a single product by providing the corresponding product code.
Use cases
  • Pulling product info for a single product can be useful for merchandising purposes. For example, you may want to recommend a related product for an email remarketing campaign. Or you may want to include a top product on a pop-up or intestinal to grab the attention of customers exiting your site.
  • Update product information between routinely scheduled checks for updated or new products via the /products/modified-since endpoint.
  • If you needed to force a refresh of some products in your system. For example, if products were corrupted or if you wanted to integrate new features you have missed on your initial ingestion.

    /products/bulk

    ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

    3. Pull product data for multiple products

    • Similar to /products/{product-code}, this endpoint will pull in product information for a specified list of products, up to 500 products per request.
    • This endpoint is useful for further product curation beyond featuring a single product. For example, you may curate a list of tours for a niche audience or you may want all product details of products from a single destination.
    • In the case that a product was not correctly ingested via the /products/modified-since endpoint, you can use /products/bulk to reingest those products.
    • This should be used only if you have a small curated product list that you want to refresh on schedule or if you need to need to fix some products on your end.

    *You may need to re-ingest the entire product catalogue during development

    What’s included in our product catalogue?

    These endpoints return all product information, including, but not limited to:

    • Titles
    • Descriptions
    • Ticket types
    • Supplier photos*
    • Start and end times
    • Meeting points
    • Traveler pick up details (if applicable)
    • Inclusions and exclusions
    • Cancellation policy
    • Additional info
    • Booking confirmation settings (e.g. instant confirmation or on-request products)
    • Booking requirements (e.g. min or max travelers
    • Booking questions
    • Itineraries
    • Product options
    • Supplier name
    • Review ratings and counts

    /products/search

    ✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

    Pull product summaries based on search criteria

    • When product summaries are returned, they contain a small amount of crucial product information such as, but not limited to, title, short descriptions, images, pricing, and review ratings and counts.
    • You can effectively filter out products returned in the request by specifying search criteria, such as destination IDs, price range, and date range. You also have the option to filter by category using tag IDs and can filter by flags, such as free cancellation or skip-the-line tours.
    • You will specify the format in which you want the response, such as the language and currency and will specify how the response will be sorted. Tours, activities and experiences are ranked using exclusive Viator data that may include product quality, reviews, ratings, photos, popularity, user preferences, price, bookings made through Viator, and payments made by operators.
    • This endpoint is ideal for where short product summaries would be ideal, such as on search cards on search results pages.

      /locations/bulk

      ✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

      Get full location details for the requested location references

      • Location details include the name of the location, the street address, and the longitude/latitude coordinates of the location. These locations are not to be confused with destinations.
      • Locations detail can be used to highlight pickup/drop off points, to build itineraries, or even overlay locations on a map to help provide additional context to what a traveler can expect on the tour.
      • Travelers can also provide special pickup points when filling out booking questions. This endpoint can be used to provide those locations to travelers through a drop down list. Otherwise, travelers can specify custom pickup info through a plain text field.
        structured itinerary

        Example of a structured itinerary with a map overlay

        Getting availability and pricing for products

        Key features of these endpoints

        Real time availability checks ensure accuracy and create a seamless checkout

        Only ingesting new or modified availability schedules speed up load times

        Schedules can be used to display future availability

        f

        Structured data allows you to easily build a variety of display and filtering options

        /availability/schedules/modified-since

        ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

        1a. Perform an initial ingestion of all availability schedules

        1b. Make regular calls to check for new or updated availability schedules

        • We recommend doing checks at least every hour to ensure that your travelers see the most up-to-date pricing and availability. A product’s availability is considered modified if a supplier makes changes to pricing or availability.

        /availability/schedules/{product-code}

        ✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

        2. Pull availability schedules for a single product

          /availability/schedules/bulk

          ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

          3. Pull availability schedules for multiple products

          • This endpoint pulls availability for a list of products, up to 500 products per request.

            /availability/check

            ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

            4. Checking availability in real time

            • This endpoint enables a real time check and calculation of pricing and availability and should be used throughout the booking path. For example, this endpoint can be used to ensure accuracy when the traveler is starting the checkout process.
            • This endpoint would be used before a booking is made to verify the product is available on the desired date for the desired passenger mix. Before a booking hold can be requested, you’ll need to use this endpoint to check that it’s still available and make sure the pricing is correct.
            • This should not be called until a user inputs dates and passenger mix.

              Creating a seamless booking experience (Merchants only)

              A series of booking endpoints enables you to build booking/checkout user flows that allow travelers to add experiences to shopping carts, provide pickup info, add special requirements (like dietary restrictions), and hold their booking to guarantee availability and pricing.

              For Full + Booking affiliates: please see here for more info on how to use our payment solutions to create a booking/checkout experience.

              booking workflow

              In general, to give your travelers the ability to book a product, you must do the following:

              /availability/check

              ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

              1. Check availability

              • Using traveler inputs of tour date, tour time, and passenger mix, you will perform a real time check before the traveler is able to add to a shopping cart and/or before placing the booking.

                /bookings/hold

                ⊗ Basic-access Affiliates ⊗ Full-access Affiliates ⊗ Full + Booking access Affiliates ✓ Merchants

                2. Request a booking hold

                • Requests the creation of a booking-hold – a guarantee that either the price or availability (or both) of the product will be retained until a booking request is made using the /bookings/book endpoint.
                • Availability holds may not be granted, but pricing holds will always be granted and is sufficient to confirm bookings.
                • Do not call this service just because the traveler picked a date and passenger mix. Only call this service if a user takes high intent actions, like adding to a cart or during checkout.
                Use Cases
                • Although booking holds are an optional feature, we recommend using this functionality. This feature gives travelers flexibility to continue to shop without worrying about any products becoming unavailable.

                  /bookings/book

                  ⊗ Basic-access Affiliates ⊗ Full-access Affiliates ⊗ Full + Booking access Affiliates ✓ Merchants

                  3. Confirm the booking

                  • Confirms/finalizes the held booking using the /bookings/book endpoint.
                  • All relevant booking information will need to be provided in the request (e.g. booking questions).

                    /bookings/status

                    ⊗ Basic-access Affiliates ⊗ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

                    4. Provide booking statuses

                    • Requests the status of an existing booking. Statuses can be either: confirmed, rejected, cancelled, or pending.
                    • This endpoint is required for manual confirmation products (formerly known as “on request” products).
                    Use cases
                    • This is useful to display to users to keep them up to date on the status of their bookings.
                    • This is also useful when reconciling your finances to account for any cancelled bookings where a refund was processed.

                      Cancelling bookings

                      All cancellations (except those requested after the date of travel) must be performed via the API. Should you need to cancel a booking after the travel date, please contact Viator Partner Support.

                      /bookings/cancel-reasons

                      ⊗ Basic-access Affiliates ⊗ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

                      1. Getting cancellation reasons

                      • In order to successfully cancel a booking, a traveler must select one of our pre-set cancellation reasons. This endpoint pulls in the acceptable cancellation reasons. You can take these cancellation reasons and provide them to travelers during the cancellation process.
                      • Recommended: as the acceptable reasons for cancellation may be altered at any point, we recommend retrieving an up-to-date list from this endpoint at least weekly.

                        /bookings/{booking-reference}/cancel-quote

                        ⊗ Basic-access Affiliates ⊗ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

                        2. Getting cancellation quotes

                        • To see if a booking is eligible to be cancelled, make a call to the API using the booking reference number. As the merchant of record, you will be processing refunds and will need to call the API to get the correct refund amount.
                        • If the booking can be cancelled you will be returned a quote and can proceed with cancellation the booking using the /bookings/{booking-reference}/cancel endpoint.

                          /bookings/{booking-reference}/cancel

                          ⊗ Basic-access Affiliates ⊗ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

                          3. Cancel a booking

                            Exchange rates

                            /exchange-rates

                            ✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

                            Getting exchange rates

                            • All our products are priced in the supplier’s currency and will need to be converted to the end user. Using the /exchange-rates endpoint you can pull the exchange rates for conversions between specified currencies.

                            Supported currencies

                            While we support many currencies, payments for bookings can only be made using the following four currencies:
                            • GBP (British Pound)
                            • EUR (Euros)
                            • USD (US Dollars)
                            • AUD (Australian dollars)
                            While you can still price products in any of the supported currencies, you will be invoiced in your choice of the four currencies above.

                            Traveler photos

                            /v1/product/photos

                            ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

                            Getting traveler-submitted photos

                            • Traveler photos are photos that travelers can upload when submitting their reviews. These photos are Unlike supplier photos, travelers photos are not ingested through any of the /products endpoints.
                            • Including traveler photos have their benefits. Traveler photos help capture the experience from a traveler’s point of view. We only require suppliers to upload a minimum of 4 photos when creating their listing and traveler photos can augment listings with just the minimum amount of photos.
                            • Including traveler photos is required for an “Excellent” build to our API, as we know that including traveler photos generally improves conversion.
                            Note: supplier photos are already ingested through our product ingestion endpoints. Learn more about implementing traveler photos

                            Traveler reviews

                            /reviews/product

                            ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ✓ Merchants

                            Getting traveler reviews

                            • This endpoint retrieves traveler reviews, supplier responses, review photos and all other necessary attributes in one request.
                            • Reviews are retrieved on an individual product basis.
                            • “Helpful votes” left by other travelers help provide relevance to customers
                            • You can retrieve up to 500 reviews per product. Our research indicates that there are diminishing returns after the 100th review.
                            • You can filter reviews by rating, by a single language, and can filter out machine-translated reviews. Machine translated reviews will always be sorted after reviews in the primary language.
                            • You can sort reviews by one of the following: by highest rating, most recent, or most helpful. This sort is applied within the chosen languages.
                            Determining ratings Product ratings and rating counts are returned by the /products/{product-code}, /products/bulk, and products/modified-since endpoints. Details of attributes included can be found in the API specs.

                            Attractions

                            These endpoints make it possible for affiliate partners to create pages dedicated to an attraction – e.g. a page that just promotes tours of the Colosseum. A single attraction could have multiple tour grades or multiple tour operators and by building an attraction page, you can present all options to your audience.

                            These endpoints can also be used to display attractions on search results pages (SRPs) and on destination pages.

                            /v1/search/attractions

                            ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ⊗ Merchants

                            Retrieve list of attractions

                            • This service retrieves a list of attractions associated with the given destination.

                            /v1/attraction

                            ⊗ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ⊗ Merchants

                            Get all attraction details

                            • Attraction details include, but are not limited to: review counts, descriptions, titles, and location information.

                            /v1/attraction/products

                            ✓ Basic-access Affiliates ✓ Full-access Affiliates ✓ Full + Booking access Affiliates ⊗ Merchants

                            Get all attraction-related products

                            • Using this endpoint, you can pull in all the products related to an attraction.
                            • This endpoint can also be used for cross-selling opportunities. For example, you may want to promote nearby attractions.

                            Did you find this article useful?