This Golden Path may not be the only path you try out. You should follow the path that makes the most sense for your business and your site or app. However, we recommend starting with this particular implementation as it’s the most common for our API partners and by getting through the steps, you get a better feel for what’s possible with our API.
Preparing for The Golden Path
Get acquainted with our API & API documentation
Understand what endpoints you have access to – because you have basic access to our API, you only have access to certain endpoints. You can see which endpoints you have access to here. You may not need to use all endpoints. If you follow our Golden Path, you will only need to use:
| Endpoint | Description | Why it’s useful |
|---|---|---|
| /product/search | Pulls product summaries based on search criteria | This endpoint is ideal for where short product summaries would be ideal, such as product previews on search results or destination pages. |
| /v1/taxonomy/destinations | Gets details of all destinations, such as destination names and parent identifiers | Provide navigation on your site, through drilldown lists, combo boxes, or breadcrumbs. |
| /products/tags | Get details for all tags | We categorize all products by using tags. Tags are useful to providing more context to your customers and by organizing products by category. |
Familiarize yourself with what information you can request
In your request to /products/search endpoint, you’ll provide which destination you want to pull products for and will indicate how you want those products sorted in the response (e.g. sort requested products by price in descending order).
Familiar yourself with what types of information the API returns
This will be useful when planning out the layout and design of your pages. For example, in the /product/search response, we return such information as images, tour descriptions, review ratings, and pricing. Ask yourself: how will I present this information/functionality on my site so my customers can easily find the right tour or activity for them?
The Golden Path
At the end of the Golden Path, you will have an API integration that allows your users to search for or select a destination, browse for and choose products, and then users are redirected to viator.com to complete the final transaction for which you will earn a commission.
Find your API key in your account dashboard
You can generate an API key immediately at any time. In your account go to Tools → Affiliate API → Start your development. Then you’ll need to verify your email address before you get your key.
Get set up on Postman
To facilitate your testing of the API’s functionality, please use Viator Affiliate API Postman collection. Set up a Postman account here.
Establish a “things to do” vertical on your site
If you sell other products, like accommodations or flights, you’ll need to establish a dedicated “things to do” section of your site for tours and activities. The best way to do this is through the navigation or directly on the search bar.
What is a “things to do” vertical? A things-to-do vertical is a section of your website dedicated to merchandising and selling tours and activities from. Here is an example of a “Things to do” vertical on Tripadvisor.com:
Build your destination pages & populate with product previews
On your destination page, you should:
- Implement product categories using the Viator tags (explained here)
- Add sort functionality for the traveler to use (e.g. sort by price low to high)
- Allow travelers to apply filters (e.g. filter for products with free cancellation)
- Include an option to update the search (e.g. allow travelers to change their dates)
- Sort/order the returned products (indicated in the initial request)
What is a destination page? A destination page is a list of product previews for a specific destination, often including options to filter the list of displayed products. To set yourself up to work with experiences, you will want to make sure this page includes sort orders, filters, and an option to update the search.
What are product previews? After your travelers search for a destination, they’ll land on a destination page, which will display a list of tours and activities that are returned by a request to the /products/search endpoint. Product previews contain 6 key elements: product title, thumbnail image, short description, average rating, review count, and price). When a user clicks on one of the product reviews on your destination page, they will be sent to the corresponding viator.com product description page (PDP) where the traveler will complete their transaction.
Example request to /products/search:
curl –location –request POST ‘https://api.viator.com/partner/products/search’ \
–header ‘Accept-Language: en-US’ \
–header ‘Content-Type: application/json’ \
–header ‘Accept: application/json;version=2.0’ \
–header ‘exp-api-key: f26df9bd-0b21-427b-9a9f-6d2be46f06d8’ \
–data-raw ‘{
“filtering”: {
“destination”: “77”,
“tags”: [
21972,
11930
],
“flags”: [
“FREE_CANCELLATION”
],
“lowestPrice”: 300,
“highestPrice”: 500,
“startDate”: “2022-06-20”,
“endDate”: “2022-06-24”
},
“sorting”: {
“sort”: “PRICE”,
“order”: “DESCENDING”
},
“pagination”: {
“start”: 1,
“count”: 2
},
“currency”: “USD”
}’
Example response from /products/search:
{
“products”: [
{
“productCode”: “227717P1”,
“title”: “Acadia National Park private minivan tour- 3 Hours Local Guides”,
“description”: “A local guide will show you all of the highlights of Acadia National Park!\n\nWe will pick you up and we’ll drive along the stunning 27-mile long Park Loop Road up to the summit of Cadillac Mountain, the highest peak on the eastern seaboard. From Cadillac you can see spectacular views of Bar Harbor and the surrounding islands.\n\nSee all of the famous sites on the Park Loop Road, including Cadillac Mountain, Rockefeller’s stone bridges & Carriage House, Otter Cliffs, Thunder Hole, and Sieur du Monts Gardens and Nature Center. See Sand Beach surrounded by the famous pink granite coastline. \n\nWe can stop and stay as long as you would like at each location. We will point out trailheads and carriage roads to explore on your own.”,
“images”: [
{
“imageSource”: “SUPPLIER_PROVIDED”,
“caption”: “Bar Harbor”,
“isCover”: true,
“variants”: [
{
“height”: 50,
“width”: 50,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-50×50/0b/d5/69/3d.jpg”
},
{
“height”: 100,
“width”: 100,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-100×100/0b/d5/69/3d.jpg”
},
{
“height”: 200,
“width”: 200,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-200×200/0b/d5/69/3d.jpg”
},
{
“height”: 400,
“width”: 400,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-400×400/0b/d5/69/3d.jpg”
},
{
“height”: 40,
“width”: 60,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-60×40/0b/d5/69/3d.jpg”
},
{
“height”: 80,
“width”: 120,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-120×80/0b/d5/69/3d.jpg”
},
{
“height”: 120,
“width”: 180,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-180×120/0b/d5/69/3d.jpg”
},
{
“height”: 160,
“width”: 240,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-240×160/0b/d5/69/3d.jpg”
},
{
“height”: 240,
“width”: 360,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-360×240/0b/d5/69/3d.jpg”
},
{
“height”: 320,
“width”: 480,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-480×320/0b/d5/69/3d.jpg”
},
{
“height”: 360,
“width”: 540,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-540×360/0b/d5/69/3d.jpg”
},
{
“height”: 446,
“width”: 674,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-674×446/0b/d5/69/3d.jpg”
},
{
“height”: 480,
“width”: 720,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-720×480/0b/d5/69/3d.jpg”
},
{
“height”: 118,
“width”: 210,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-210×118/0b/d5/69/3d.jpg”
},
{
“height”: 75,
“width”: 75,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-75×75/0b/d5/69/3d.jpg”
},
{
“height”: 109,
“width”: 154,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-154×109/0b/d5/69/3d.jpg”
}
]
}
],
“reviews”: {
“sources”: [
{
“provider”: “VIATOR”,
“totalCount”: 10,
“averageRating”: 5.0
},
{
“provider”: “TRIPADVISOR”,
“totalCount”: 63,
“averageRating”: 5.0
}
],
“totalReviews”: 73,
“combinedAverageRating”: 4.972603
},
“pricing”: {
“summary”: {
“fromPrice”: 500.00,
“fromPriceBeforeDiscount”: 500.00
},
“currency”: “USD”
},
“productUrl”: “https://www.viator.com/tours/Bar-Harbor/3-Hour-ACADIA-NATIONAL-PARK-TOUR-Cadillac-Mountain-Sand-Beach-and-Thunder-Hole/d4371-227717P1?mcid=42383&pid=P00063937&medium=api&api_version=2.0”,
“destinations”: [
{
“ref”: “4371”,
“primary”: true
}
],
“tags”: [
11930,
21956,
21768,
21951,
21955,
21949,
12029,
20757,
12056,
21948,
22083,
11929,
11941,
21972
],
“flags”: [
“FREE_CANCELLATION”,
“LIKELY_TO_SELL_OUT”
],
“translationInfo”: {
“containsMachineTranslatedText”: false
}
},
{
“productCode”: “7908P9”,
“title”: “New York Tour by Subway and Bus with Private Guide”,
“description”: “Experience New York like a real New Yorker on this private tour using subways and buses to get around. Learn to navigate the city the way most New Yorkers do. Get a great orientation and overview for the rest of your stay. Visit some of the major sights, attractions and neighborhoods, along with off the beaten path places. Discover from the beginning where you would like to go back and spend more time, during your visit. Learn the short-cuts and secrets (maybe new just yesterday!) only known to locals.”,
“images”: [
{
“imageSource”: “SUPPLIER_PROVIDED”,
“caption”: “Times Square”,
“isCover”: true,
“variants”: [
{
“height”: 50,
“width”: 50,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-50×50/06/74/b1/60.jpg”
},
{
“height”: 100,
“width”: 100,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-100×100/06/74/b1/60.jpg”
},
{
“height”: 200,
“width”: 200,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-200×200/06/74/b1/60.jpg”
},
{
“height”: 400,
“width”: 400,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-400×400/06/74/b1/60.jpg”
},
{
“height”: 40,
“width”: 60,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-60×40/06/74/b1/60.jpg”
},
{
“height”: 80,
“width”: 120,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-120×80/06/74/b1/60.jpg”
},
{
“height”: 120,
“width”: 180,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-180×120/06/74/b1/60.jpg”
},
{
“height”: 160,
“width”: 240,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-240×160/06/74/b1/60.jpg”
},
{
“height”: 240,
“width”: 360,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-360×240/06/74/b1/60.jpg”
},
{
“height”: 320,
“width”: 480,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-480×320/06/74/b1/60.jpg”
},
{
“height”: 360,
“width”: 540,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-540×360/06/74/b1/60.jpg”
},
{
“height”: 446,
“width”: 674,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-674×446/06/74/b1/60.jpg”
},
{
“height”: 480,
“width”: 720,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-720×480/06/74/b1/60.jpg”
},
{
“height”: 118,
“width”: 210,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-210×118/06/74/b1/60.jpg”
},
{
“height”: 75,
“width”: 75,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-75×75/06/74/b1/60.jpg”
},
{
“height”: 109,
“width”: 154,
“url”: “https://media-cdn.tripadvisor.com/media/attractions-splice-spp-154×109/06/74/b1/60.jpg”
}
]
}
],
“reviews”: {
“sources”: [
{
“provider”: “VIATOR”,
“totalCount”: 10,
“averageRating”: 4.0
},
{
“provider”: “TRIPADVISOR”,
“totalCount”: 16,
“averageRating”: 5.0
}
],
“totalReviews”: 26,
“combinedAverageRating”: 4.6538463
},
“pricing”: {
“summary”: {
“fromPrice”: 499.00,
“fromPriceBeforeDiscount”: 499.00
},
“currency”: “USD”
},
“productUrl”: “https://www.viator.com/tours/New-York-City/New-York-Tour-by-Subway-and-Bus-with-Private-Guide/d687-7908P9?mcid=42383&pid=P00063937&medium=api&api_version=2.0”,
“destinations”: [
{
“ref”: “687”,
“primary”: true
}
],
“tags”: [
21946,
11930,
21956,
12075,
21768,
21971,
21949,
12056,
21948,
12046,
11929,
11941,
21972
],
“flags”: [
“FREE_CANCELLATION”
],
“translationInfo”: {
“containsMachineTranslatedText”: false
}
}
],
“totalCount”: 45
}
Build a search-by-destination tool
After setting up your things-to-do vertical, you’ll add structure by integrating our destinations into your site that enables your customers to search for or find destinations.
Having search functionality on your site is the quickest and easiest way that a traveler can find exactly what they’re looking for. The search functionality should be front and center and should include some basic search criteria like destination, travel dates, price ranges, or other filters (e.g. free cancellation products).
How to create a destination search:
- Retrieve a list of destinations on a regular schedule (e.g. daily) using the /v1/taxonomy/destinations endpoint.
- Implement a search of the destination names from the list of destinations using the /products/search endpoint.
You’re ready to lanch!
After you finish your own testing, you are ready to go live using the same API key you generated in step 1. You can also continue to build out your integration.
Need additional help? See these guides:
Viator tags, explained
Tags are numeric identifiers used to categorize products, as well as include or exclude products.
Implementing traveler photos
Traveler photos are user-submitted photos, taken by travelers while they are participating in a Viator experience. Including traveler photos in your API implementation is recommended as a best practice, but not required.
Front-end guide
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.
How attribution works
As a Viator affiliate, you earn commission from sales made by your users after being redirected to the Viator site. Viator uses cookies to track the activity of your users on our site and attribute sales to your account for 30 days.