Technical Guide for API Partners

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.

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.

Only ingesting new or modified product information speeds up load times

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

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.

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.

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.

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.

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.

Schedules can be used to display future availability

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

1a. Perform an initial ingestion of all availability schedules

• Similar to using the /products/modified-since endpoint, you’ll use the /availability/schedules/modified-since endpoint to get availability for all products. Getting everything at once and updating only new or modified availability schedules will speed up ingestion and ensure availability is not stale.

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.

2. Pull availability schedules for a single product

• This endpoint can be used in conjunction with /products/{product-code to pull availability for a single product.

3. Pull availability schedules for multiple products

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

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.

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.

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.

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

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.

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.

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.

3. Cancel a booking

• If the /bookings/{booking-reference}/cancel-quote endpoint identifies the booking as cancellable, you can process the cancellation using /bookings/{booking-reference}/cancel.

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.

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 →

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.

Retrieve list of attractions

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

Get all attraction details

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

Get all photos related to an attraction

• The photos in this request may be associated with products that are related to the attraction.

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.

Getting reviews for an attraction

• This service gets reviews related to an attraction. These reviews might be associated indirectly through the related products.