Viator Product services API

openapi: 3.2.0
info:
  title: Viator Product services API
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/au
  version: '1.0'
  description: 'Operations tagged Product services across 2 of this provider''s published API definitions: viator-affiliate-api-v1-openapi.json, viator-merchant-api-v1-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://viatorapi.viator.com/service
  description: Production server
- url: https://viatorapi.sandbox.viator.com/service
  description: Sandbox server (uses test data)
security:
- API-key: []
- Legacy-API-key: []
tags:
- name: Product services
  description: Product services
paths:
  /search/products:
    post:
      tags:
      - Product services
      summary: /search/products
      operationId: searchProducts
      description: "\nThis service is used to search for products based on various criteria; such as:\n* the destination (locale) in which it operates\n* its association with a tourist attraction\n* its category and/or subcategory\n* the time period during which it operates\n\nThe fields you include in the request body for this service determine the kind of search that will be performed.\n\n**<u>Note</u>**: \n\n* You can search **EITHER** by destination (`destId`) **OR** by attraction-link (`seoId`), but not both.\n* The destination identifier (`destId`) can be retrieved from the [/taxonomy/destinations](#operation/taxonomyDestinations) service.\n* The category (`catId`) and subcategory (`subCatId`) identifiers can be retrieved from the [/taxonomy/categories](#operation/taxonomyCategories) service.\n* The attraction identifier (`seoId`) can be retrieved from the [/taxonomy/attractions](#operation/taxonomyAttractions) service.\n\n**<u>Examples</u>**:\n\n**Search by destination**:\n\n* E.g., \"Top ten highest-rated yoga classes operating in Las Vegas:\n```javascript\n{\n    \"destId\": 684,\n    \"subCatId\": 26052,\n    \"sortOrder\": \"REVIEW_AVG_RATING_D\",\n    \"topX\": \"1-3\"\n}\n```\n\n**Search by attraction-link**:\n\n* E.g., \"Products related to Everglades National Park operating 21-26 May 2019 in order of descending price\":\n```javascript\n{\n    \"seoId\": 1115,\n    \"startDate\": \"2019-05-21\",\n    \"endDate\": \"2019-05-26\",\n    \"sortOrder\": \"PRICE_FROM_D\"\n    \"topX\": \"1-3\"\n}\n```\n"
      parameters:
      - $ref: '#/components/parameters/acceptLanguage'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                destId:
                  type: integer
                  description: '**unique numeric identifier** of the destination in which to search for products

                    - `destinationId` is available from the [/taxonomy/destinations](#operation/taxonomyDestinations) service

                    - use **EITHER** `destId` **OR** `seoId`, but not both

                    '
                seoId:
                  type: string
                  description: '**search restriction specifier** for products associated with an attraction uniquely identified by `seoId`

                    - use **EITHER** `destId` **OR** `seoId`, but not both

                    '
                catId:
                  type: integer
                  description: '**unique numeric identifier** of *this* product category to search within

                    - `categoryId` can be retrieved from the [/taxonomy/categories](#operation/taxonomyCategories) service

                    - at present, it is not possible to use `catId` in conjunction with `seoId`

                    '
                subCatId:
                  type: integer
                  description: '**unique numeric identifier** of *this* product subcategory to search within

                    - `subcategoryId` can be retrieved from the [/taxonomy/categories](#operation/taxonomyCategories) service

                    - at present, it is not possible to use `subCatId` in conjunction with `seoId`

                    '
                startDate:
                  type: string
                  description: '**start date delimiter** for the search (must be in the future)

                    - e.g., `''2018-10-21''`

                    '
                endDate:
                  type: string
                  description: '**end date delimiter** for the search (must be in the future)

                    - e.g., `''2019-10-21''`

                    '
                currencyCode:
                  type: string
                  description: '**currency** in which to display product prices'
                topX:
                  $ref: '#/components/schemas/topX'
                sortOrder:
                  $ref: '#/components/schemas/sortOrder'
            examples:
              By destination:
                value:
                  destId: 684
                  subCatId: 26052
                  sortOrder: REVIEW_AVG_RATING_A
                  topX: 1-3
              By attraction link:
                value:
                  seoId: 1115
                  startDate: '2020-12-21'
                  endDate: '2020-12-31'
                  sortOrder: PRICE_FROM_D
                  topX: 1-3
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/basicErrorModel'
                - type: object
                  properties:
                    data:
                      type: array
                      description: '**array** of product objects'
                      items:
                        type: object
                        properties:
                          sortOrder:
                            type: integer
                            description: '**sort order** for *this* product'
                          supplierName:
                            type: string
                            description: '**natural-language name** of *this* product''s supplier'
                          currencyCode:
                            $ref: '#/components/schemas/currencyCode'
                          catIds:
                            type: array
                            description: '**list** of unique numeric category identifiers for *this* product

                              - the `categoryId` for the destination is available from the [/taxonomy/categories](#operation/taxonomyCategories) service

                              '
                            items:
                              type: integer
                          subCatIds:
                            type: array
                            description: '**list** of unique numeric subcategory identifiers for *this* product

                              - the `subcategoryId` for the destination is available from the [/taxonomy/categories](#operation/taxonomyCategories) service

                              '
                            items:
                              type: integer
                          webURL:
                            $ref: '#/components/schemas/webURL'
                          specialReservationDetails:
                            type: string
                            description: ignore (Viator only)
                          sslSupported:
                            description: ignore (Viator only)
                          panoramaCount:
                            type: integer
                            description: '**number** of panoramic images available for *this* product'
                          merchantCancellable:
                            type: boolean
                            description: "ignore (Viator only)\n\n    \nFor cancellation information regarding the booking, please refer to the `merchantTermsAndConditions` object\n"
                          bookingEngineId:
                            $ref: '#/components/schemas/bookingEngineId'
                          onRequestPeriod:
                            $ref: '#/components/schemas/onRequestPeriod'
                          primaryGroupId:
                            type: integer
                            description: ignore (Viator only)
                          pas:
                            type: object
                            description: '**object** detailing product availability

                              - `pas` stands for Product Availability Schema

                              '
                          available:
                            type: boolean
                            description: ignore (Viator only)
                          productUrlName:
                            type: string
                            description: '**URL-formatted name** of *this* product'
                          primaryDestinationUrlName:
                            type: string
                            description: '**URL-formatted name** of *this* product''s primary destination'
                          title:
                            type: string
                            description: '**natural-language title** of *this* product'
                          shortDescription:
                            type: string
                            description: '**HTML-formatted natural-language description** of *this* product'
                          supplierCode:
                            type: string
                            description: '**unique identifier** of *this* product''s supplier in text string format'
                          uniqueShortDescription:
                            type: string
                            description: ignore (Viator only)
                          merchantNetPriceFrom:
                            type: number
                            description: ignore (Viator only)
                          merchantNetPriceFromFormatted:
                            type: string
                            description: ignore (Viator only)
                          essential:
                            type: string
                            description: ignore (Viator only)
                          admission:
                            type: string
                            description: ignore (Viator only)
                          translationLevel:
                            $ref: '#/components/schemas/translationLevel'
                          thumbnailHiResURL:
                            type: string
                            description: '**URL** for the high resolution thumbnail for *this* product'
                          price:
                            $ref: '#/components/schemas/price'
                          priceFormatted:
                            $ref: '#/components/schemas/priceFormatted'
                          rrp:
                            $ref: '#/components/schemas/rrp'
                          rrpformatted:
                            $ref: '#/components/schemas/rrpFormatted'
                          savingAmount:
                            $ref: '#/components/schemas/savingAmount'
                          savingAmountFormated:
                            $ref: '#/components/schemas/savingAmountFormated'
                          onSale:
                            $ref: '#/components/schemas/onSale'
                          specialOfferAvailable:
                            $ref: '#/components/schemas/specialOfferAvailable'
                          photoCount:
                            type: integer
                            description: '**number** of user photos published for *this* product'
                          reviewCount:
                            $ref: '#/components/schemas/reviewCount'
                          primaryDestinationId:
                            type: integer
                            description: '**unique numeric identifier** of *this* product''s primary destination'
                          primaryDestinationName:
                            description: '**natural-language name** of *this* product''s primary destination'
                            type: string
                          thumbnailURL:
                            type: string
                            description: '**URL** for *this* product''s thumbnail image'
                          videoCount:
                            type: integer
                            description: ignore (Viator only) – videos are not available to partners
                          rating:
                            $ref: '#/components/schemas/rating'
                          shortTitle:
                            type: string
                            description: '**short natural-language title** of *this* product (for use when there is a need to conserve space)'
                          specialReservation:
                            type: boolean
                            description: ignore (Viator only)
                          duration:
                            type: string
                            description: '**natural-language description** of the duration of *this* product'
                          code:
                            type: string
                            description: '**unique alphanumeric identifier** of *this* product'
              examples:
                By destination:
                  $ref: '#/components/examples/search-products-example1'
                By attraction link:
                  $ref: '#/components/examples/search-products-example2'
    servers:
    - url: https://viatorapi.viator.com/service
      description: Production server
  /search/products/codes:
    post:
      tags:
      - Product services
      summary: /search/products/codes
      operationId: searchProductsCodes
      description: "- This service returns an array of products given an array of product identifiers that is useful for wishlist / shopping cart / user account display \n- **Note**: requesting an inactive or non-existent product code will return `0`, `null` and blank values (as per the example below).\n"
      parameters:
      - $ref: '#/components/parameters/acceptLanguage'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                currencyCode:
                  $ref: '#/components/schemas/currencyCode'
                productCodes:
                  type: array
                  description: '**array** of product codes to search for'
                  items:
                    type: string
            example:
              currencyCode: USD
              productCodes:
              - 2280SUN
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/basicErrorModel'
                - type: object
                  properties:
                    data:
                      type: array
                      description: '**array** of product objects'
                      items:
                        type: object
                        properties:
                          sortOrder:
                            type: integer
                            description: '**sort order** for *this* search result'
                          supplierName:
                            type: string
                            description: '**natural-language name** of *this* product''s supplier'
                          currencyCode:
                            $ref: '#/components/schemas/currencyCode'
                          catIds:
                            type: array
                            description: '**list** of category identifiers *this* product falls under

                              - `categoryId` is available from the [/taxonomy/categories](#operation/taxonomyCategories) service

                              '
                            items:
                              type: integer
                          subCatIds:
                            type: array
                            description: "**list** of subcategory identifiers that *this* product falls under \n- `subcategoryId` is available from the [/taxonomy/categories](#operation/taxonomyCategories) service\n"
                            items:
                              type: integer
                          webURL:
                            $ref: '#/components/schemas/webURL'
                          specialReservationDetails:
                            type: string
                            description: ignore (Viator only)
                          panoramaCount:
                            type: integer
                            description: '**number** of panoramic images available for *this* product'
                          merchantCancellable:
                            type: boolean
                            description: 'ignore (Viator only)

                              '
                          bookingEngineId:
                            $ref: '#/components/schemas/bookingEngineId'
                          onRequestPeriod:
                            $ref: '#/components/schemas/onRequestPeriod'
                          primaryGroupId:
                            type: string
                            description: ignore (Viator only)
                          shortDescription:
                            type: string
                            description: '**natural-language description** of *this* product (short)'
                          specialReservation:
                            type: boolean
                            description: ignore (Viator only)
                          rating:
                            $ref: '#/components/schemas/rating'
                          thumbnailURL:
                            type: string
                            description: '**URL** for *this* product''s thumbnail image'
                          photoCount:
                            type: integer
                            description: '**number** of user photos published for *this* product'
                          reviewCount:
                            $ref: '#/components/schemas/reviewCount'
                          supplierCode:
                            type: string
                            description: '**unique identifier** of *this* product''s supplier'
                          price:
                            $ref: '#/components/schemas/price'
                          priceFormatted:
                            $ref: '#/components/schemas/priceFormatted'
                          rrp:
                            $ref: '#/components/schemas/rrp'
                          rrpformatted:
                            $ref: '#/components/schemas/rrpFormatted'
                          onSale:
                            $ref: '#/components/schemas/onSale'
                          savingAmount:
                            $ref: '#/components/schemas/savingAmount'
                          savingAmountFormated:
                            $ref: '#/components/schemas/savingAmountFormated'
                          translationLevel:
                            $ref: '#/components/schemas/translationLevel'
                          primaryDestinationId:
                            type: integer
                            description: '**unique numeric identifier** of *this* product''s primary destination'
                          primaryDestinationName:
                            description: '**natural-language name** of *this* product''s primary destination'
                            type: string
                          merchantNetPriceFrom:
                            type: number
                            description: ignore (Viator only)
                          merchantNetPriceFromFormatted:
                            type: string
                            description: ignore (Viator only)
                          specialOfferAvailable:
                            type: boolean
                            description: '**indicator**: `true` if a special offer is available for *this* product'
                          thumbnailHiResURL:
                            type: string
                            description: '**URL** for *this* product''s high-resolution thumbnail image'
                          shortTitle:
                            type: string
                            description: '**natural-language title** (shortened) of *this* product'
                          videoCount:
                            type: integer
                            description: ignore (Viator only) – videos are not available to partners
                          title:
                            type: string
                            description: '**natural-language title** of *this* product'
                          duration:
                            type: string
                            description: '**natural-language description** of *this* product''s duration'
                          code:
                            type: string
                            description: '**unique alphanumeric identifier** of *this* product'
              examples:
                '1':
                  $ref: '#/components/examples/search-products-codes-example'
    servers:
    - url: https://viatorapi.viator.com/service
      description: Production server
  /search/freetext:
    post:
      tags:
      - Product services
      summary: /search/freetext
      operationId: searchFreetext
      description: '- This service provides a **free text search across all products destinations, attractions and recommendations**

        - The `text` parameter is required

        - **Note:** results include a type indicator (`type`) that you can use to display each result appropriately based on its content

        '
      parameters:
      - $ref: '#/components/parameters/acceptLanguage'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                destId:
                  type: integer
                  description: "**unique numeric identifier** of the destination to search within \n- `destinationId` can be retrieved from the [/taxonomy/destinations](#operation/taxonomyDestinations) service\n"
                topX:
                  $ref: '#/components/schemas/topX'
                currencyCode:
                  $ref: '#/components/schemas/currencyCode'
                text:
                  type: string
                  description: '**text** to search for'
                searchTypes:
                  type: array
                  description: "**array** of search domain specifiers where each item is *one of*:\n  - `'PRODUCT'`: a tour / activity\n  - `'DESTINATION'`: continent, country, city, region\n  - `'ATTRACTION'`: an attraction within a destination (only available to partners with SEO access)\n  - `'RECOMMENDATION'`: an attraction within a destination (only available to partners with SEO access)\n"
                  items:
                    type: string
                    enum:
                    - PRODUCT
                    - DESTINATION
                    - ATTRACTION
                    - RECOMMENDATION
                sortOrder:
                  $ref: '#/components/schemas/sortOrder'
            example:
              destId: 684
              topX: 1-3
              currencyCode: USD
              text: helicopter
              searchTypes:
              - PRODUCT
              - DESTINATION
              sortOrder: TOP_SELLERS
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/basicErrorModel'
                - type: object
                  properties:
                    data:
                      type: array
                      description: '**array** of search results'
                      items:
                        type: object
                        properties:
                          sortOrder:
                            type: integer
                            description: '**sort order** for *this* data object'
                          searchType:
                            type: string
                            enum:
                            - PRODUCT
                            - DESTINATION
                            - ATTRACTION
                            - RECOMMENDATION
                            description: "**indicator** of the entity type for *this* result that is *one of*:\n  - `'PRODUCT'`: a tour / activity\n  - `'DESTINATION'`: continent, country, city, region\n  - `'ATTRACTION'`: an attraction within a destination (only available to partners with SEO access)\n  - `'RECOMMENDATION'`: an attraction within a destination (only available to partners with SEO access)\n"
                          data:
                            type: object
                            description: '**object** detailing a product that matches the search criteria'
                            properties:
                              supplierName:
                                type: string
                                description: '**natural-language name** of *this* product''s supplier'
                              currencyCode:
                                $ref: '#/components/schemas/currencyCode'
                              catIds:
                                type: array
                                description: "**list** of unique numeric product category identifiers \n- `categoryId` is available for the destination from the [/taxonomy/categories](#operation/taxonomyCategories) service\n"
                                items:
                                  type: integer
                              subCatIds:
                                type: array
                                description: '**list** of unique numeric subcategory identifiers that *this* product falls under

                                  - `subcategoryId` is available from [/taxonomy/categories](#operation/taxonomyCategories) service"

                                  '
                                items:
                                  type: integer
                              webURL:
                                $ref: '#/components/schemas/webURL'
                              specialReservationDetails:
                                type: string
                                description: ignore (Viator only)
                              sslSupported:
                                type: boolean
                                description: ignore (Viator only)
                              panoramaCount:
                                type: integer
                                description: '**number** of panoramic images available for *this* product'
                              merchantCancellable:
                                type: boolean
                                description: ignore (Viator only)
                              bookingEngineId:
                                $ref: '#/components/schemas/bookingEngineId'
                              onRequestPeriod:
                                $ref: '#/components/schemas/onRequestPeriod'
                              primaryGroupId:
                                type: string
                                description: ignore (Viator only)
                              pas:
                                type: object
                                description: '**object** detailing product availability

                                  - `pas` stands for Product Availability Schema

                                  '
                              available:
                                type: boolean
                                description: ignore (Viator only)
                              productURLName:
                                type: string
                                description: '**URL-formatted name** of *this* product'
                              primaryDestinationUrlName:
                                type: string
                                description: '**URL-formatted name** of *this* product''s primary destination'
                              supplierCode:
                                type: string
                                description: '**unique identifier** of *this* product''s supplier'
                              translationLevel:
                                $ref: '#/components/schemas/translationLevel'
                              thumbnailHiResURL:
                                type: string
                                description: '**high-resolution thumbnail image URL** for *this* product'
                              primaryDestinationName:
                                type: string
                                description: '**natural-language name** of *this* product''s primary destination'
                              thumbnailURL:
                                type: string
                                description: '**URL** of *this* product''s thumbnail image'
                              price:
                                $ref: '#/components/schemas/price'
                              priceFormatted:
                                $ref: '#/components/schemas/priceFormatted'
                              rrp:
                                $ref: '#/components/schemas/rrp'
                              rrpformatted:
                                $ref: '#/components/schemas/rrpFormatted'
                              onSale:
                                $ref: '#/components/schemas/onSale'
                              savingAmount:
                                $ref: '#/components/schemas/savingAmount'
                              savingAmountFormated:
                                $ref: '#/components/schemas/savingAmountFormated'
                              photoCount:
                                type: integer
                                description: '**number** of user photos published for *this* product'
                              reviewCount:
                                $ref: '#/components/schemas/reviewCount'
                              primaryDestinationId:
                                description: '**unique numeric identifier** of *this* product''s primary destination'
                                type: integer
                              videoCount:
                                type: integer
                                description: ignore (Viator only) – videos are not available to partners
                              rating:
                                $ref: '#/components/schemas/rating'
                              shortTitle:
                                type: string
                                description: '**natural-language title** (shortened) of *this* product'
                              specialOfferAvailable:
                                type: boolean
                                description: '**indicator**: `true` if a special offer is available for *this* product'
                              specialReservation:
                                description: ignore (Viator only)
                                type: boolean
                              uniqueShortDescription:
                                type: string
                                description: ignore (Viator only)
                              merchantNetPriceFrom:
                                type: number
                                description: ignore (Viator only)
                              merchantNetPriceFromFormatted:
                                type: string
                                description: ignore (Viator only)
                              essential:
                                type: string
                                description: ignore (Viator only)
                              admission:
                                type: string
                                description: ignore (Viator only)
                              shortDescription:
                                type: st

# --- truncated at 32 KB (318 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/viator/refs/heads/main/openapi/viator-product-services-api-openapi.yml