Front-End Guide for API Partners
Building a Great Front-end
As a Viator API Partner you can choose which products to highlight on your website and/or app and retrieve all details via the API.
How you choose to display these products is up to you – every implementation is unique.
Based on our years of experience with Viator.com and evaluating hundreds of affiliates sites, we have compiled a front-end guide for you, including UX best practices and how to optimize conversion.
Our Integrations Team is here to support you throughout the integration process.
Quick find
Using a Landing Page
Your travelers may be introduced to Viator tours and experiences via a landing page.
The structure of your integration and the contents of your landing page can vary greatly, based on your business needs. Often, the landing page takes the form of a home page or a Tours & Activities section.
The landing page sets the tone for the traveler, and should enable quick and easy navigation of the site while highlighting top destinations and products.
Search results page (SRP)
A search results page (SRP) allows travelers to narrow down their search to quickly and easily find the right tour or activity for them.
An SRP should enable users to quickly apply filters and locate their desired product(s). The display of high revenue / high conversion products should be prioritized.
- We include the most relevant product information on the search results page to highlight the value of our experiences. Elements like rating, thumbnail photo, teaser, free cancellation policy, price, and safety features play a vital role in merchandising products to grab a customer’s attention so that they want to click through to the product detail page to read more. All this information is included in product info. Included in this example: title, price, thumbnail, teaser, rating, safety features (select products), and free cancellation (select products)
- Category filtering tools: All Viator products are classified into specific categories based on their content, features or theme. This has been done with the use of identifiers called ‘tags’ that create a hierarchical system of categories. For example, we have a category of Air, Helicopter and Balloon Tours with the following subcategories: Air Tours, Helicopter Tours, Balloon Rides, Inter-island Flights. The search for products by category is one of the most essential features and it helps customers find the types of products they are looking for. Learn more about working with tag references
- The more filtering options are provided, the easier it is to find desired products. We recommend applying a variety of search criteria as every customer might have different needs – some will look for products with the highest rating or most popular ones, others will consider the price. Partners can use the data returned in the API to create their own sort orders. To create the sort order based on price you can use the fromPrice returned by availability schedules. Learn how to determine ratings to create a sort order based on ratings.
- Using product categorization based on tags, partners can easily create custom filtering options to enable search for products with specific features, such as products with COVID-19 safety measures, excellent quality products, kid-friendly experiences, private tours, etc. Learn more about working with tag references.
- Multiple filtering options make it easy for travelers to find types of products that match their specific needs. This could include the price range, duration of the tour, time of the day, review rating from other travelers, free cancellation policy, special offers, etc. These details are included in product info.
- With a clickable locations breadcrumb on top of the page travelers are able to easily navigate the website and browse products from desired destinations. This can be done on a city, region or country level based on the destinations included in the API. Learn more about working with destinations.
Product Display Page (PDP)
The product display page (PDP) is an up close view of an individual product, which allows users to view supplier and traveler images, detailed itineraries, reviews, and more.
A PDP should convey all product information needed for users to make their purchasing decision. It is recommended that all product information available to a partner be visible to customers via one unified PDP per product.
Sample PDP
Below is an example of a Viator PDP. We’ve annotated all the important elements necessary to give a traveler all the relevant information to make a booking with confidence.
You do not need to follow the same structure of our PDP when building your PDPs. We’ve catered our PDPs to our audience, and you should consider what’s most relevant to your audience when building out your PDPs.
- The product title is a text field displaying the name of the tour or activity. Titles are included in product data.
- Average ratings are a key filtering tool experiences shoppers use to inform purchase decisions. In our API, reviews and ratings are managed separately from products – reviews are requested per-product, and average ratings should be calculated based on all reviews. Learn more about working with reviews.
- The destination breadcrumb is key to site navigation. For desktop site implementations, we recommend including destination hierarchy. The destinations we supply come in three levels of hierarchy:
- country
- region
- cityLearn more about working with destinations.
Note: our breadcrumbs are a mix of destination, attraction, and product type. We recommend to keep it simple only only include only destinations.</p>
- Photos provide additional context about the experience and, in the case of traveler photos, show the experience from the point-of-view of travelers. Viator’s product images are available in multiple resolutions, from thumbnail to high-res. Our photos are divided into two categories – supplier and traveler photos:
- Supplier photos are added to the product by the tour operator. These photos are included in product data.
- Traveler photos are taken by travelers while participating in the experiences. When users interact with traveler photos, Viator’s testing indicates a moderate increase in conversion. Traveler photos are provided through a supplemental API endpoint.
- Price from: On the product detail page, we display the lowest “standard” price. This is calculated as the price for the cheapest tour option for the lowest permitted number of adult travelers. In our API, pricing info is considered part of availability schedules.
- Date selection and number of travelers: This is what travelers will use to select their dates, times, and number of travelers on their reservation. Learn more about passenger mix.
- Cancellation policy: Viator offers three cancellation policies: standard (full refund is available until 24h before the activity starts), all-sales-final (no refund is possible), and custom (a custom policy determined by the tour operator). A flexible cancellation policy is attractive to most users, and can inform a purchase decision. Cancellation policy is included in product info. Learn more about the different cancellation policies.
- Duration: The duration field indicates how long the experience will take. Duration information is included in product info.
- Ticket type indicates the type of tickets accepted by the tour operator (mobile, paper, or both). Ticket type information is included in product info.
- Languages: This indicates the languages in which the tour or activity is offered. Language information is included in product info.
- The overview is a textual description of the tour or activity, and is critical to informing a purchase decision. Overview information is included in product info.Some products will offer transportation to and from local hotels. Pickup information is included in product info.
- Covid-19 Safety Information (deprecated)
- Attraction: Highlight attractions nearby.
- Recommendations (deprecated)
- Nearby: Highlight things to do nearby.
- Inclusions and exclusions are features that are included/not included in the product package. Common examples would be “lunch,” “champagne,” etc. This information is included in product info.
- Departure and return details: information is included in product info.
- A product’s itinerary communicates detailed information on where and when the tour or activity will take place. Some experiences are designed to occur at a single location, while others will cover multiple locations and points of interest. Most Viator products offer structured itinerary data, and will include map locations and/or points of interest. Itineraries are included in product info.
- Additional info: Most products will include additional important information, which does not fit neatly into the other categories listed here. This data is shared in a machine-readable format, which allows you to manage and filter our products more easily. Additional info is included in product info.
- See #7
- Traveler photos: (see #4)
- Travelers rely on product reviews to inform their purchase decisions. In our API, reviews and ratings are managed separately from products – reviews are requested per-product, and should be available on the product detail page. Learn more about working with reviews.
Pricing (Merchant Partners only)
The API will return three prices:
Merchant Net Price
The amount that Viator will invoice the merchant for this sale, excluding the transaction fee.
Merchant Total Price
The total amount that Viator will invoice the merchant for this sale, including the transaction fee.
Suggested Retail Price
The recommended retail price for the product – this is the price that the product is sold at on the Viator site. As the merchant of record, the retail prices you set are entirely your decision.
Taxonomy
In order to efficiently manage our inventory of 300,000+ tours & activities, Viator’s site taxonomy is available via our API. All products are mapped to taxonomic IDs to enable sorting and filtering.
A single product can be mapped to multiple taxonomic elements:
Destinations
Destinations follow a hierarchy of country -> region -> city
Attractions
Attractions are major tourist sites such as landmarks, city squares/plazas, or geographic features.
Categories
Tours and activities are grouped into broad descriptive ‘categories’, each of which can also include a set of narrower ‘subcategories’.
User flow
Your travelers will respond positively to a simple, easy to navigate site/app.
Viator’s user flow is designed to minimize the pages and clicks required to make a purchasing decision.
On the home page, users may make a freetext search (directs to SRP), select a top destination (directs to SRP), or select a top product (directs to PDP).
On an SRP, the user may select a product (directs to PDP), or filter by category, attraction, and sort order (updates SRP).
