What are tags & why they matter
Tags are numeric identifiers used to categorize products. For example, tags allow you to distinguish walking tours and bus tours from other sightseeing tours. There are a variety of functions beyond categorization that tags offer and can be used creatively to fit the needs of your integration with Viator. Because all products have tags, they can be used to include or exclude products.
Simply put, tags offer customization and flexibility to your integration that cannot be achieved otherwise. In this article, we’ll cover many of the use cases for and benefits of using tags.
Quick find
Overview of different tag types
Tags are unique and are not defined for a single use case. For example, you’ll notice that some tags align closely with product categories (e.g. Helicopter Tours), while others align closely with product features (e.g. Skip the line Tickets).
Tags related to product categories, for example:
- tagId 12026 – Helicopter Tours
- tagId 13018 – Bike Tours
- tagId 21765 – Shows
Tags related to the historic performance of a product, for example:
- tagId 367652 – Top Products
- tagId 22143 – Best Conversion
Tags that may indicate a product’s quality, for example:
- tagId 21972 – Excellent Quality
- tagId 367654 – Low Last Minute Supplier Cancellation
- tagId 367653 – Low Supplier Cancellation
Tags that relate to a product’s availability, for example
- tagId 21592 – Seasonal
- tagId 367661 – Short term availability
Tags used to highlight specific product features, for example:
- tagId 21579 – Dinner
- tagId 12118 – Free Shuttle or Taxi Services
- tagId 12074 – Skip the line Tickets
Tags indicating a target group of participants:
- tagId 18884 – Adults Only
- tagId 11919 – Kid-Friendly
- tagId 20222 – LGBT Friendly Tours
Tags linked to a specific area or a popular tourist attraction, for example:
- tagId 11982 – Cinque Terre Day Trips from Milan
- tagId 11960 – Western Caribbean Shore Excursions
- tagId 11999 – Rome To Siena
Tags for special occasions, for example:
- tagId 11892 – Christmas
- tagId 11893 – Halloween
- tagId 21583 – Chinese New Year
Tags indicating tour/activity time frame, for example:
- tagId 13121 – Afternoon tea
- tagId 11922 – Multi-day Tours
- tagId 18953 – Evening Entertainment
Product tags for special distinction, for example:
- tagId 21074 – Unique experiences
- tagId 367655 – Viator Experience Award 2025
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.
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. Using quality and performance tags
Our quality and performance tags can be used as catalog filters to help surface top products based on performance and reliability signals on Viator.com.
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:
Product performance tags, for example:
- tagId 367652 – Top Products: active products that rank in a top percentile of product gross booking value in its primary destination in the last 12 months
- tagId 22143 – Best Conversion: active products that rank in a top percentile of conversion in their destination. Based on Viator.com performance only.
Product quality tags, for example:
- tagId 21972 – Excellent Quality: Products that are meeting the “Excellent” criteria in Viator’s Product Quality Standards. More info here
- tagID 367654 – Low Last Minute Supplier Cancellation: 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
- tagId 367653 – Low Supplier Cancellation: meet a threshold of bookings in the past year and have a low cancellation rate in the past year
- 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.
The above tags may be used to create custom sort orders or additional filters in the back-end system in order to help customers find the best products.
The only tags that may be used for front-end display are:
- tagId 21074 – Unique experiences
- tagId 367655 – Viator Experience Award 2025
- tagId 11940 – Once in a Lifetime
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
Unsupported tags and additional front-end filtering guidelines
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 relevanceDisplay 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 for product filtering in the back-end system only:- 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 While these tags are returned by the API, they are not currently supported for partner use and must not be used:
- tagId 22083 – Likely To Sell Out
- 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: