This document provides the OpenAPI specification for a set of three auxilliary endpoints that support the Viator Partner API v1 to v2 Upgrade Guide:

• /upgrade/agebands
  • provides the required mapping information between the age band designations v1's bandId and v2's ageBand

• /upgrade/categories
  • provides all mappings between v2's tags and v1's category and subCategory fields

• /upgrade/tourgrades/{product-code}
  • provides the v1 gradeCode and it's corresponding v2 productOption identifiers for the specified product

The following Postman collection can be used for testing these endpoints:

• PAPI v1-v2 upgrade endpoints

v1's treatAsAdult flag

In v1 of this API, the requirement (or lack thereof) for an adult to be included in a booking was communicated via the treatAsAdult flag in the items of the ageBands[] array in the response from the /product endpoint. The default assumption in the v1 API was that at least one adult is required per booking unless the treatAsAdult flag is set to true for a non-adult age-band, in which case the inclusion of one traveler from that age-band is sufficient to fulfil the requirement.

See: Key concepts – Working with age-bands (Partner API v1) for more information.

In v2 of this API, whether an adult traveler is required in order to make a booking is communicated via the bookingRequirements.requiresAdultForBooking flag in the response from any of the product content endpoints.

If this flag is true, at least one traveler from one of the 'ADULT', 'SENIOR' or 'TRAVELER' age-bands must be included when making the booking.

In version 2 of the Viator API, the concept of 'product categories' that was utilized in version 1 has been replaced by tags.

To learn more about tags, see this article: Viator tags, explained

In version 1, the list of categories and subcategories was available on a per-destination basis using v1's /taxonomy/cateogories endpoint. This list could be used to construct a category tree for display to the user; or, to aid in search.

In version 2, tags can be used to replicate this functionality simply by mapping the original v1 subcategory to its v2 tag equivalent. Tag information is available from the /products/tags endpoint.

These mappings are detailed in this Excel spreadsheet: v1 category and subcategory mappings to v2 tags.

All v2 tags that correspond to categories or subcategories in v1 are listed in the spreadsheet, which can be interpreted as per this example:

The example above shows that the v2 tag "Hot Air Balloon Rides", which has a tagId of 12027, corresponds to v1's "Balloon Rides" (subcategory 3), which falls under "Air, Helicopter & Balloon Tours" (category 1).

In the response from the v2 endpoint /products/tags, "Hot Air Balloon Rides" (tagId: 12027) is shown here:

{
    "tagId": 12027,
    "parentTagIds": [
        21715,
        21913,
        21436,
        21909
    ],
    "allNamesByLocale": {
        "de": "Heißluftballonfahrten",
        "no": "Turer i varmluftballong",
        "sv": "Flygturer i varmluftsballong",
        "pt": "Passeios de balão",
        "ko": "열기구 타기",
        "en_AU": "Hot Air Balloon Rides",
        "en": "Hot Air Balloon Rides",
        "it": "Giri in mongolfiera",
        "fr": "Vols en montgolfière",
        "en_UK": "Hot Air Balloon Rides",
        "es": "Paseos en globo aerostático",
        "zh": "热气球之旅",
        "zh_HK": "熱氣球之旅",
        "zh_TW": "熱氣球之旅",
        "ja": "熱気球での飛行体験",
        "zh_CN": "热气球之旅",
        "da": "Varmluftballonture",
        "nl": "Ballonvaarten"
    }
} 

This corresponds to the following result (Balloon-rides; category 1, subcategory 3) in the response from the v1 endpoint /taxonomy/categories:

{
    "sortOrder": 1,
    "thumbnailURL": "https://hare-media-cdn.tripadvisor.com/media/attractions-splice-spp-154x109/06/75/b7/96.jpg",
    "subcategories": [
        {
            "sortOrder": 1,
            "subcategoryUrlName": "Balloon-Rides",
            "subcategoryId": 3,
            "subcategoryName": "Balloon Rides",
            "categoryId": 1
        },
        {
            "sortOrder": 2,
            "subcategoryUrlName": "Air-Tours",
            "subcategoryId": 1,
            "subcategoryName": "Air Tours",
            "categoryId": 1
        },
        {
            "sortOrder": 3,
            "subcategoryUrlName": "Helicopter-Tours",
            "subcategoryId": 2,
            "subcategoryName": "Helicopter Tours",
            "categoryId": 1
        }
    ],
    "thumbnailHiResURL": "https://hare-media-cdn.tripadvisor.com/media/attractions-splice-spp-674x446/06/75/b7/96.jpg",
    "productCount": 76,
    "groupName": "Air, Helicopter & Balloon Tours",
    "groupUrlName": "Air-Helicopter-and-Balloon-Tours",
    "id": 1
},

Using the spreadsheet, as above, you can replicate the category tree and categorise products accordingly using a product's tags, which are provided in the product content response.