What are tags & why they matter
Tags are numeric identifiers used to categorize products. They let you distinguish offerings (e.g., walking tours vs. bus tours), can be used to use as a search criteria or to decide which products to include or exclude. Since all products have tags, they provide powerful customization options for your Viator integration
This document outlines how to consume, filter, and prioritize Viator product tags—especially merchandising and quality-focused tags, which are essential for surfacing, sorting, and curating top-performing products.
Quick find
Tag types overview
Most tags are suitable for front-end use, while others are intended solely for back-end filtering. Some tags are restricted for Viator’s internal use and should not be used at all.
1. Merchandising signals tags: (back-end filtering)
Our merchandising tags can be used as catalog filters to help select and rank top products, boost reliability, conversion or uniqueness
These tags can be used on the back end but must not be used to create any front-end filters or labels for customers unless otherwise stated below.
| Type | Tag name | Purpose | Display-eligible |
| Performance | Top Product (tagId 367652) | active products that rank in a top percentile of product gross booking value in its primary destination in the last 12 months | ❌ |
| Quality & Reliability | Best Conversion (tagId 22143) | active products that rank in a top percentile of conversion in their destination. Based on Viator.com performance only. | ❌ |
| Low Supplier Cancellation Rate (tagId 367653) | meet a threshold of bookings in the past year and have a low cancellation rate in the past year | ❌ | |
| Low Last Minute Supplier Cancellation Rate (tagId 367654) | meet a threshold of bookings in the past year and have a low supplier cancellation within a short time to travel in the past year | ❌ | |
| Excellent Quality (tagId 21972) | Products that are meeting the “Excellent” criteria in Viator’s Product Quality Standards. More info here | ❌ | |
| Availability | Likely to Sell Out (tagId 22083 | active products that have availability in the next 365 days and have a designated threshold of product slots that have sold out in the past 30 days through Viator.com and its distribution partners. | ❌ |
| Short term availability (tagId 367661) | Active products that have at least one Tour Grade available in the next 5 days | ❌ | |
| Seasonal (tagId 21592) | Active products tied to specific times of the year, holidays, or seasonal events. | ✅ |
2. Filtering & categorization tags (front-end priority)
These tags are safe for front-end use and valuable for navigation, filtering, and personalizing the catalog – some tags align closely with product categories (e.g. Helicopter Tours), while others align closely with product features (e.g. Skip the line Tickets).
| Type | Example tags |
| Category |
|
| Product feature |
|
| Target participant |
|
| Special occasions |
|
| Tour/activity time frame |
|
| Special distinctions |
|
Please note:
Tags are dynamic – new tags may be added at any time, and existing tags may be modified or removed. It’s essential to keep the tag structure up to date to ensure accurate product mapping.
While these tags are returned by the API, they are not currently supported for partner use and must not be used:
- tagId 367649 – Worry-Free Shore Excursion
- tagId 5184 – Budget
- tagId 22098 – Best Seller
- tagId 21859 – Best Seller
- tagId 6226 – Best Value
- tagId 21873 – Best Seller
- tagId 21971 – Viator Plus
- tagId 22211 – Featured New
Working with tags in the API
Key information about Viator tags:
- Each product has at least one tag returned in the product content response (tags array).
- In order to verify details of each tag, it’s necessary to use the /products/tags endpoint.
- The API returns tag details in all supported languages (listed here).
- Tags are grouped in hierarchical order with the use of tagIds and parentTagIds.
- Most tags are suitable for front-end use, while others are intended solely for back-end systems. Some tags are restricted for Viator’s internal use and should not be used at all.
Please note:
It’s not necessary to use all Viator tags returned in the API. You have the flexibility to create your own tag hierarchy and map Viator’s tags to your existing categories or organizational structure. However, it is highly recommended to utilize a meaningful number of relevant tags for search and filtering functions. Doing so enhances product discoverability and helps deliver a more personalized and efficient experience for your travelers. Thoughtful use of tags supports higher conversion rates by making it easier for customers to find exactly what they’re looking for.
An example of the API response to /products/{product-code} for product 5516ST5:
“tags”: [
21957,
22045,
21953,
21958,
11953,
12026,
21956,
21951,
21971,
21955,
21949,
21959,
21954,
11938,
21948,
12057,
21860,
21950,
21972
],
Tag structure
Tags have a “mesh” like structure: conceptually they are not organized in a tree like formation but instead each child tag can have multiple parents. Additionally, their parent tags themselves can have multiple parents. This provides an abundance of flexibility in the way a product can be merchandised.
Example 1
1a. tagId: 22046 (Adventure Tours) is linked to two parentTagIds: 21725 and 21913.
{
“tagId”: 22046,
“parentTagIds”: [
21725,
21913
],
“allNamesByLocale”: {
“de”: “Abenteuertouren”,
“no”: “Spenningsturer”,
“sv”: “Äventyrsturer”,
“pt”: “Excursões de aventura”,
“ko”: “어드벤처 투어”,
“en_AU”: “Adventure Tours”,
“en“: “Adventure Tours”,
“it”: “Tour avventurosi”,
“fr” “Circuits aventure”,
“en_UK”: “Adventure Tours”,
“es”: “Tours de aventura”,
“zh”: “探险之旅”,
“zh_HK”: “探险之旅”,
“zh_TW”: “冒險遊覽”,
“ja”: “アドベンチャーツアー”,
“zh_CN”: “探险之旅”,
“da”: “Oplevelsesture”,
“nl”: “Avontuurlijke tours”
}
},
1b. In order to check the details of the parentTagId 21725, it’s necessary to search for it in the /products/tags response.
{
“tagId”: 21725,
“parentTagIds”: [
21913
],
“allNamesByLocale”: {
“de”: “Sightseeingtouren”,
“no”: “Sightseeing-turer”,
“sv”: “Sightseeing-turer”,
“pt”: “Passeios turísticos”,
“ko”: “관광 투어”,
“en_AU”: “Sightseeing Tours”,
“en”: “Sightseeing Tours”,
“it”: “Giri turistici”,
“fr”: “Visites guidées”,
“en_UK”: “Sightseeing Tours”,
“es”: “Tours turísticos”,
“zh”: “观光游览”,
“zh_HK”: “观光游览”,
“zh_TW”: “觀光遊覽”,
“ja”: “観光ツアー”,
“zh_CN”: “观光游览”,
“da”: “Sightseeing”,
“nl”: “Sightseeingtours”
}
},
1c. tagId 21725 also has a parent – tagId 21913, which is not linked to any other parent tag which means that tagId 21913 is one of the main parent tags.
{
“tagId”: 21913,
“allNamesByLocale”: {
“de”: “Touren, Sightseeing und Bootsfahrten”,
“no”: “Turer, sightseeing og cruise”,
“sv”: “Rundturer, sightseeing och kryssningar”,
“pt”: “Excursões, passeios turísticos e cruzeiros”,
“ko”: “투어 관광, 크루즈”,
“en_AU”: “Tours, Sightseeing & Cruises”,
“en”: Tours, Sightseeing & Cruises”,
“it”: “Tour, giri turistici e crociere”,
“fr”: “Circuits et croisières”,
“en_UK”: “Tours, Sightseeing & Cruises”,
“es”: “Tours, visitas turísticas y cruceros”,
“zh”: “游览、观光活动与邮轮之旅”,
“zh_HK”: “遊覽團、觀光活動與郵輪之旅”,
“zh_TW”: “遊覽、觀光和郵輪”,
“ja”: “ツアー、観光、クルーズ”,
“zh_CN”: “游览、观光活动与邮轮之旅”,
“da”: “Ture, sightseeing og krydstogter”,
“nl”: “Tours, bezienswaardigheden en cruises”
}
},
Based on that, we can see the following hierarchy:
- tagId 21913 (Tours, Sightseeing & Cruises) – main parent tag
- tagId 21725 (Sightseeing tours)
- tagId 22046 (Adventure Tours)
Example 2
This chart illustrates the correlation between tags from the example below:
2a. tagId 11892 (Christmas) has two parents: 21584 (Holidays), 21916 (Seasonal & Special Occasions)
{
“tagId”: 11892,
“parentTagIds”: [
21584,
21916
],
“allNamesByLocale”: {
“de”: “Weihnachten”,
“no”: “Jul”,
“sv”: “Jul”,
“pt”: “Natal”,
“ko”: “크리스마스”,
“en_AU”: “Christmas”,
“en”: “Christmas”,
“it”: “Natale”,
“fr”: “Noël”,
“en_UK”: “Christmas”,
“es”: “Navidad”,
“zh”: “圣诞节”,
“zh_HK”: “聖誕節”,
“zh_TW”: “聖誕節”,
“ja”: “クリスマス”,
“zh_CN”: “圣诞节”,
“da”: “Jul”,
“nl”: “Kerstmis”
}
},
2b. We can see that tagId 21916 (Seasonal & Special Occasions) is the parent tag for tagId 21584 (Holidays):
{
“tagId”: 21584,
“parentTagIds”: [
21916
],
“allNamesByLocale”: {
“de”: “Feiertage”,
“no”: “Ferier”,
“sv”: “Helger”,
“pt”: “Férias”,
“ko”: “휴일”,
“en_AU”: “Holidays”,
“en”: “Holidays”,
“it”: “Vacanze”,
“fr”: “Jours fériés”,
“en_UK”: “Holidays”,
“es”: “Vacaciones”,
“zh”: “假日”,
“zh_HK”: “假期”,
“zh_TW”: “節日”,
“ja”: “イベント”,
“zh_CN”: “假日”,
“da”: “Ferier”,
“nl”: “Feestdagen”
}
},
2c. Additionally, tagId 21916 (Seasonal & Special Occasions) doesn’t have any parent tagIds, therefore it’s the main parent.
{
“tagId”: 21916,
“allNamesByLocale”: {
“de”: “Saisonale und besondere Anlässe”,
“no”: “Sesongbaserte og spesielle anledninger”,
“sv”: “Säsongsbundna och särskilda tillfällen”,
“pt”: “Ocasiões especiais e temáticas”,
“ko”: “계절적인 특별한 날”,
“en_AU”: “Seasonal & Special Occasions”,
“en”: “Seasonal & Special Occasions”,
“it”: “Occasioni stagionali e speciali”,
“fr”: “Saisonnier et grandes occasions”,
“en_UK”: “Seasonal & Special Occasions”,
“es”: “Ocasiones especiales y de temporada”,
“zh”: “节庆与特殊场合”,
“zh_HK”: “節慶和特別場合”,
“zh_TW”: “季節性及特殊場合”,
“ja”: “季節限定・特別な日”,
“zh_CN”: “节庆与特殊场合”,
“da”: “Sæsonbetonede og særlige lejligheder”,
“nl”: “Seizoensgebonden en speciale gelegenheden”
}
},
The hierarchy here is:
- tagId 21916 (Seasonal & Special Occasions) – main parent tag
- tagId 21584 (Holidays)
- tagId 11892 (Christmas) and other tags for which tagId 21584 (Holidays) is their parent tag
Tag 21916 has more tags linked to it, such as tag 21593 (Weddings & Celebrations) or tag 21592 (Seasonal) with their own child tags that create additional hierarchies for different categories of tags.
Tag taxonomy tree
Below you will find a file containing the current version of the tag taxonomy available in the API. You may use this structure to support your tag mapping processes, for example, when creating categories and subcategories.
Please note, however, that tags are dynamic and may change over time. We cannot guarantee that the same tag structure will be available in the API when you access it. Therefore, we recommend using this file with caution and not as a static or definitive reference.
Product search by tags
How partners can use tags, depending on their integration method:
1. If you use /products/search and/or /search/freetext endpoints:
- You can actively filter products using tag IDs in your requests.
In order to do this, it’s necessary to include the relevant tagId(s) under the tags object in the request body when using the search endpoint.
For example this request will allow to find bus tours (tagId 11930) available in London (destId 737) for Christmas (tagId 11892) that are excellent quality products (tagId 21972):
2. If you do not use search endpoints:
- You will still receive tag data as part of the product content returned via the /products/modified-since endpoint
- In this case, filtering by tags has to be implemented on your end based on ingested product data.
For example, product 9025P51 returns the following tags:
“filtering”: {
“destination”: “737”,
“tags”: [
21972, 11892, 11930
],
“flags”: [
“FREE_CANCELLATION”
],
“highestPrice”: 1500,
“startDate”: “2021-11-23”,
“endDate”: “2021-12-29”
},
“sorting”: {
“sort”: “PRICE”,
“order”: “DESCENDING”
},
“pagination”: {
“start”: 1,
“count”: 50
},
“currency”: “USD”
}
“tags”: [
22046, 11930, 12056, 21768, 11923, 11892, 11903, 11929
],
Please note:
Regardless of the method, incorporating tags into your experience helps improve discoverability and organization of products.
Tag implementation on the front-end
1. Identifying product categories and subcategories
The main purpose of tags is to classify products into categories and subcategories. This allows for the creation of customer filters, enabling users to quickly find relevant products based on category or specific features.
The screenshots below demonstrate different ways to use tags to display product categories and to enable filtering by category or subcategory.
Product 5836DINNERCRUISE returns the following tags in the API:
21953,
21958,
21956,
21074,
21951,
11963,
11965,
21955,
21960,
21949,
21959,
21954,
11938,
21948,
21952,
12053,
20255,
21972
],
Tag 11965 (Dinner Cruises) has several parentTagIds:
{
“tagId”: 11965,
“parentTagIds”: [
11890, ← Dining Experiences
21911, ← Food & Drink
21442, ← On the Water
21909, ← Outdoor Activities
21701, ← Cruises & Sailing
21913 ← Tours, Sightseeing & Cruises
],
Tag 11965 is for Dinner Cruises, so products mapped to it (e.g., 5836DINNERCRUISE) appear on Viator under the Dinner Cruises category.
Thanks to the presence of multiple parentTagIds, it’s possible to link products to different categories and subcategories when they meet specific criteria, like in the example above. This way the product bookability could be increased by better product visibility.
Tag 11965 can be used to search for products from the category “Dinner Cruises”:
2. Featuring best products
Quality and performance tags are valuable for surfacing high-quality products, but they must be implemented in ways that align with our guidelines. We also offer additional tags to help identify the right products based on specific features and special distinctions.
Direct use (approved tags only)
Special distinction tags or tags related to specific product features can be used as individual front-end filters. This allows you to highlight products on the front-end that are worth booking because they offer exceptional experiences, unique value, have received prestigious awards, or simply match the user’s specific search criteria.
Here are some examples:
- tagId 11940 – Once in a Lifetime: Rare and/or extraordinary experiences that travelers are unlikely to repeat. These are bucket-list moments with significant emotional or personal impact, often involving exclusive access, limited availability, or iconic destinations.
- tagId 21074 – Unique experiences: Highlights distinctive experiences or offerings designed to deliver one-of-kind moments that stand out from ordinary or more common experiences in that destination.
- tagId 367655 – Viator Experience Award 2025: This tag is placed on products that have been recognized by Viator as a top travel experience. This award is refreshed yearly, more information can be found here. This tag should be updated annually, typically around May, when new awards are granted. At that time, a new tag representing the current year’s award will be returned in the API response.
- tagId 12074 – Skip the line Tickets: Type of admission that allows you to bypass the regular queue at a popular attraction, saving a significant amount of time.
Indirect use (aggregated filters)
Viator quality and performance tags listed in the table above are not approved for direct front-end display however they can be used to create front-end filters when combined in the back-end logic.
For example:
Combine multiple quality/performance tags (e.g., “Likely to Sell Out” + “Top products”) into a single front-end filter such as “Recommended by us” – This aggregated filter can influence what products are shown or prioritised, without exposing each underlying tag individually.
Valid use cases:
- Back-end logic to promote high-quality products in search results.
- Custom algorithms to feature “best value” selections.
- Highlighting collections based on multiple internal performance signals.
What to avoid:
- Displaying non-approved tags as standalone front-end filter options.
- Using tags in ways that could mislead customers about product availability, ratings, or other claims.
3. Multiple filtering options
Tags may be used to create multiple filtering options based on the specific business model and customer needs. Below is an example of the implementation of tags to create filtering based on different filters, such as: Time of Day, Duration, Price, Rating, Specials.
Why smart filtering boosts engagement and conversions:
- Helps with user decision-making by narrowing choices
- Surfaces the most relevant products for each user
- Streamlines the path from discovery to booking
- Promotes high-performing products
- Enables timely, targeted seasonal or promotional campaigns
- Optimizes the experience for users, especially on mobile where space is limited
4. Creating campaigns
Tags are also very useful in creating temporary campaigns for specific holidays and special occasions.
For example:
- tagId 11892 – Christmas
- tagId 11893 – Halloween
- tagId 21583 – Chinese New Year
- tagId 11895 – National Holidays
- tagId 11957 – Easter
- tagId 11894 – Mother’s Day
- tagId 20213 – Father’s Day
- tagId 11898 – Valentine’s Day
- tagId 11896 – New Years
- tagId 11956 – Day of the Dead
They all are linked to tags 21584 (Holidays) and 21916 (Seasonal & Special Occasions).
Why using seasonal tags is beneficial:
- Easily group and promote relevant products without manual curation
- Quickly launch seasonal landing pages or time-sensitive campaigns
- Enable targeted promotions tied to specific holidays or occasions
- Increase user engagement by surfacing timely and relevant offers
- Boost conversions during peak travel periods through curated product visibility
Requirements and best practices
When implementing tag-based filtering using data from the API, partners should follow these requirements and best practices to ensure a high-quality user experience and compliance with applicable regulations:
Requirements
- Validate tag usage
Only include tags in the front-end UI that have products currently mapped to them. Tags without any associated products may lead to empty filtering and should be ignored. - Ensure front-end relevance
Display only those tags that are meaningful and helpful to end users when filtering products. Do not implement all tags from the API by default – evaluate each for usability and relevance.. - Exclude back-end filtering tags from the front-end UI
Not all tags returned by the API are suitable for front-end display. Some tags serve informational or compliance purposes and are intended for back-end filtering only. For example these tags are informational only and should be used only for product filtering in the back-end system:- tagId 367651 – DSA non-compliant: Products provided by suppliers who have not yet been verified under applicable EU law. You may wish to remove these products from being shown to your EU/UK users.
- tagId 367650 – Additional fees: Products that require fees paid to third parties in-destination. In some markets, it may be legally required to show prices inclusive of these fees.
- Exclude unsupported tags When processing tags returned by the API, it’s important to exclude any unsupported tags from the provided list, even if they appear in the response. These tags currently have no products mapped to them and are therefore irrelevant for filtering. By removing unsupported tags, we ensure that only valid, actionable filtering options are presented to users, improving both the efficiency of search and the overall usability of the system. While these tags are returned by the API, they are not currently supported for partner use and must not be used:
- tagId 367649 – Worry-Free Shore Excursion
- tagId 5184 – Budget
- tagId 22098 – Best Seller
- tagId 21859 – Best Seller
- tagId 6226 – Best Value
- tagId 21873 – Best Seller
- tagId 21971 – Viator Plus
- tagId 22211 – Featured New
Best practices
- Use tags generously to maximize filtering options
The more tags are supported in your implementation, the more filtering options become available – helping users better navigate and discover relevant experiences. - Map tags thoughtfully to your own taxonomy
You don’t need to adopt every Viator tag. Instead, map those relevant to your platform’s structure – keeping product filtering coherent and consistent. - Leverage tag hierarchy flexibly
Tags have a “mesh” structure (multi‑parent relationships). Use this to your advantage when creating logical product groupings or navigation paths. - Prioritize filtering by quality and conversion signals Use tags related to the historic performance of a product or product quality when building filters or sort options in your back-end system – products with these tags tend to drive higher revenue.
- Combine tag filters with other criteria
For a better user experience, integrate tag‑based filters with other filtering options, like: filtering by destination, attraction, ratings, price, or duration. - Use merchandising tags for smart curation
Tags like Top‑Product (tagId 367652) and Low Supplier Cancellation (tagId 367653) can be used to automate promotions and feature reliably performing experiences, reducing manual curation. - Keep tagging logic aligned with UX
Structure filters and navigation so they map logically – e.g., categories → subcategories – helping users find products intuitively.
Updating tags
1. Weekly updates
Tags retrieved via the /products/tags endpoint must be cached and refreshed once per week. This schedule is sufficient because tag data rarely changes for existing tags.
2. On-demand updates
Tags should be updated immediately whenever a new tag ID appears in an API response that isn’t yet stored in your system. This ensures you have complete details for all new tags and that products are accurately mapped.
3. Product-level tag refresh
Tags associated with each product must be refreshed during your regular product data update, which should happen at least hourly via the /products/modified-since endpoint.
This ensures that product-to-tag mappings remain current. For example, a product assigned the “Top Products” tag today might lose this tag tomorrow if it no longer qualifies. Tag data should be refreshed based on the tag details already stored in your database.
Important:
Product-to-tag mappings can change over time, so regularly updating tags is essential to maintain accurate filtering and categorization. For example, a product assigned the “Top Products” tag today might lose this tag tomorrow if it no longer qualifies.
Tag mapping should be based on the tag details already stored in your database. If an existing product appears with a new tag in the product content response, use the tag information already in your system – do not call the /products/tags endpoint again. Only call the /products/tags endpoint if you encounter a tag reference that you haven’t stored previously.
Additional resources
For additional information, please check the following sections of our API documentation: