Viator Attractions API

openapi: 3.2.0
info:
  title: Viator Partner Attractions API
  description: 'code { white-space: nowrap; }

    a { font-weight: bold; }


    figure {

    width: 100%;

    text-align: center;

    font-style: italic;

    font-size: smaller;

    text-indent: 0;

    border: thin silver solid;

    margin: 0.5em;

    padding: 0.5em;

    }


    ## Updates


    ### Latest updates:


    | Date | Description…'
  version: '2.0'
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/au/
servers:
- url: https://api.viator.com/partner
  description: Production server (uses live data)
- url: https://api.sandbox.viator.com/partner
  description: Sandbox server (uses test data)
security:
- API-key: []
tags:
- name: Attractions
paths:
  /attractions/search:
    post:
      tags:
      - Attractions
      operationId: attractionsSearch
      summary: /attractions/search
      description: 'Get a list of attractions associated with a given `destinationId`, along with all relevant information about them, including products mapped.


        Attractions should be cached and refreshed weekly.


        **Note**:


        - Pages generated using data from this endpoint are subject to a strict no-index policy.

        You must ensure that your site is configured such that **no Viator Unique Content is indexed by any search engine**.

        This is a requirement for site certification. For more information, see Key concepts – Protecting unique content.

        If you are unsure about whether you are correctly following this rule or if you would like to take advantage of our unique content, please reach out to our support team.'
      parameters:
      - $ref: '#/components/parameters/acceptLanguage'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/campaignValueAttraction'
      requestBody:
        content:
          application/json;version=2.0:
            schema:
              $ref: '#/components/schemas/AttractionsSearchRequest'
      responses:
        '200':
          description: Success
          headers:
            X-Unique-ID:
              $ref: '#/components/headers/XUniqueId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json;version=2.0:
              schema:
                $ref: '#/components/schemas/AttractionsSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /attractions/{attraction-id}:
    get:
      tags:
      - Attractions
      operationId: attractions
      summary: /attractions/{attraction-id}
      description: 'Get all relevant information about a specific `attractionId`, including products mapped.


        **Note**:


        - Pages generated using data from this endpoint are subject to a strict no-index policy.

        You must ensure that your site is configured such that **no Viator Unique Content is indexed by any search engine**.

        This is a requirement for site certification. For more information, see Key concepts – Protecting unique content.

        If you are unsure about whether you are correctly following this rule or if you would like to take advantage of our unique content, please reach out to our support team.'
      parameters:
      - $ref: '#/components/parameters/acceptLanguage'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/campaignValueAttraction'
      responses:
        '200':
          description: Success
          headers:
            X-Unique-ID:
              $ref: '#/components/headers/XUniqueId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json;version=2.0:
              schema:
                $ref: '#/components/schemas/AttractionDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  headers:
    RateLimit-Reset:
      required: true
      schema:
        type: string
        description: 'The fixed window in time, in seconds, which represents when a limit is fully replenished. For informational purposes only.

          '
    XUniqueId:
      required: true
      schema:
        type: string
        description: 'Tracking identifier for this response. Please include the value of this field when making help requests.

          - **Example**: `"0A871A13:DE2A_0A8712F9:01BB_5DCCC98C_260DAA:0D5B"`

          '
    RateLimit-Remaining:
      required: true
      schema:
        type: string
        description: 'Remaining requests for this endpoint for a given window. For informational purposes only

          '
    Retry-After:
      required: true
      schema:
        type: string
        description: 'The fixed window in time, in seconds, which represents when a limit is fully replenished. For informational purposes only.

          '
    RateLimit-Limit:
      required: true
      schema:
        type: string
        description: 'Total limit of requests for this endpoint for a given window. For informational purposes only.

          '
  responses:
    Forbidden:
      description: Forbidden
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"FORBIDDEN"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"Request is forbidden"`

                    '
              example:
                code: FORBIDDEN
                message: Request is forbidden
                timestamp: '2019-09-17T03:20:45.737043Z'
    MethodNotAllowed:
      description: HTTP Method Not Allowed
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"METHOD_NOT_ALLOWED"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"HTTP 405 Method Not Allowed"`

                    '
            - type: object
              example:
                code: METHOD_NOT_ALLOWED
                message: HTTP 405 Method Not Allowed
                timestamp: '2019-09-17T03:20:45.737043Z'
    TooManyRequests:
      description: Too Many Requests
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"TOO_MANY_REQUESTS"`


                    See [Workflows - Rate limiting](#section/Workflows/Rate-limiting) for more information about this error.

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"Too many requests, please try again"`

                    '
            - type: object
              example:
                code: TOO_MANY_REQUESTS
                message: Too many requests
                timestamp: '2019-09-17T03:20:45.737043Z'
    InternalServerError:
      description: Internal Server Error
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"INTERNAL_SERVER_ERROR"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"Internal server error"`

                    '
            - type: object
              example:
                code: INTERNAL_SERVER_ERROR
                message: Internal Server Error
                timestamp: '2019-09-17T03:20:45.737043Z'
    ServiceUnavailable:
      description: Service Unavailable
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"SERVICE_UNAVAILABLE"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"Service unavailable"`

                    '
            - type: object
              example:
                code: SERVICE_UNAVAILABLE
                message: Service Unavailable
                timestamp: '2019-09-17T03:20:45.737043Z'
    BadRequest:
      description: Bad Request
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"BAD_REQUEST"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"Invalid request"`

                    '
            - type: object
              example:
                code: BAD_REQUEST
                message: Invalid request
                timestamp: '2019-09-17T03:20:45.737043Z'
    NotFound:
      description: Not Found
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"NOT_FOUND"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"The specified resource was not found"`

                    '
            - type: object
              example:
                code: NOT_FOUND
                message: The specified resource was not found
                timestamp: '2019-09-17T03:20:45.737043Z'
    Unauthorized:
      description: Unauthorized
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"UNAUTHORIZED"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"Invalid API Key"`

                    '
            - type: object
              example:
                code: UNAUTHORIZED
                message: Invalid API Key
                timestamp: '2019-09-17T03:20:45.737043Z'
    NotAcceptable:
      description: Not Acceptable
      headers:
        X-Unique-ID:
          $ref: '#/components/headers/XUniqueId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponse'
            - type: object
              properties:
                code:
                  description: 'Code for this error type


                    **Example**: `"NOT_ACCEPTABLE"`

                    '
                message:
                  description: 'Details of this error


                    **Example**: `"Not acceptable"`

                    '
            - type: object
              example:
                code: NOT_ACCEPTABLE
                message: Not acceptable
                timestamp: '2019-09-17T03:20:45.737043Z'
  schemas:
    LocationCenter:
      type: object
      description: Geographic coordinates (latitude/longitude) for this location
      properties:
        latitude:
          type: number
          description: "Latitude of this location\n\n  - **Example**: `-33.870037`\n"
        longitude:
          type: number
          description: "Longitude of this location\n\n  - **Example**: `151.20955`\n"
    TranslationDetails:
      type: object
      description: Information about whether the text in this response was machine-translated
      required:
      - containsMachineTranslatedText
      - translationSource
      properties:
        containsMachineTranslatedText:
          type: boolean
          description: Indicates whether this product description utilizes text in any of its natural language fields that was automatically machine-translated with no human oversight
        translationSource:
          type: string
          description: "One of:\n- `\"MACHINE\"` – The text provided by the supplier is in a **different language** and has been **automatically translated** by our systems with no human oversight.\n- `\"ORIGINAL\"` – The text provided by the supplier is in the language that is standard for their locale.\n- `\"MANUAL\"` – The text provided by the supplier was in a different language to the standard for their locale; however, whether this is a direct translation of the original text (performed either by machine or human) or whether it is a customised description for speakers of this language is not known. \n"
        translationAttribution:
          type: string
          description: "Value specifying the machine-translation service vendor. At present, translation attribution is not a requirement.\n\n  - **Example**: `\"GOOGLE\"`\n"
    AttractionsSearchRequest:
      type: object
      required:
      - destinationId
      properties:
        destinationId:
          type: integer
          description: 'Unique numeric identifier of the destination to retrieve attractions for

            '
        sorting:
          type: object
          description: How the search results will be sorted
          properties:
            sort:
              type: string
              default: DEFAULT
              description: 'Method by which attraction results will be sorted; one of:


                - `"DEFAULT"`: the default sort, where ''featured'' attractions appear first (Note: What Viator gets paid impacts this sort order).

                - `"ALPHABETICAL"`: attractions are sorted by alphabetical ascending order

                - `"REVIEW_AVG_RATING"`: attractions are sorted by reviews average rating descending order

                '
        pagination:
          type: object
          description: Pagination details specifying which search results to return based on start position and item count
          properties:
            start:
              type: integer
              default: 1
              minimum: 1
              description: 'Position of first filtered and ordered search result to be included in the response (1-based)

                '
            count:
              type: integer
              default: 30
              maximum: 30
              minimum: 1
              description: 'Number of filtered and ordered search results to be returned in the response

                '
    ProductReviewsSummarySource:
      type: object
      required:
      - provider
      - totalCount
      properties:
        provider:
          type: string
          description: 'Provider for this set of reviews; one of:

            - `"VIATOR"`

            - `"TRIPADVISOR"`

            '
        reviewCounts:
          type: array
          description: Breakdown of number of reviews per rating for reviews sourced from this provider
          items:
            $ref: '#/components/schemas/ProductReviewsSummaryCount'
        totalCount:
          type: integer
          format: int64
          description: Total number of reviews for this product sourced from this provider
    ImageVariant:
      type: object
      required:
      - height
      - width
      - url
      properties:
        height:
          type: integer
          description: "Height of this image in pixels\n\n  - Example: `'480'`\n"
        width:
          type: integer
          description: 'Width of this image in pixels

            - Example `''720''`

            '
        url:
          type: string
          pattern: (?s).*[\S].*
          description: 'URL from which this image can be retrieved.

            '
    ProductReviewsSummaryCount:
      type: object
      required:
      - rating
      - count
      properties:
        rating:
          type: number
          description: This object refers to reviews with this star-rating
          format: float
        count:
          type: integer
          description: Number of reviews for this product with a star-rating of `rating`
          format: int64
    AttractionDetails:
      type: object
      required:
      - attractionId
      - name
      - attractionUrl
      - destinations
      - productCodes
      - productCount
      - images
      properties:
        attractionId:
          type: integer
          description: Unique numeric identifier for this attraction
        name:
          type: string
          description: 'Natural-language title of this attraction


            **Note**: This field contains natural language suitable for display to the user; content will be translated (if necessary) into the language specified in the Accept-Language header parameter

            '
        destinations:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int64
                description: Unique numeric identifier for this destination
              primary:
                type: boolean
                description: '**True** if this is the primary destination associated with this product

                  '
          description: Destinations associated with this attraction
        attractionUrl:
          type: string
          description: "**URL** to forward users to in order to complete their purchase on the Viator site\n\nThis URL includes all the necessary information for Viator to correctly attribute and pay commission for the sale to the referring partner.\n\nIf `campaign-value` is included in the request, this URL will also include the campaign tracking value that you set.\n\nFor more information, see our guide to <a href=\"https://partnerresources.viator.com/blog/attribution/\">Affiliate Attribution</a> on the Viator Partner Resource Center.\n\n**Note**:\n  - This element is only returned for affiliate partners.\n  - **You must use the full URL and not modify it in any way – any changes could result in failure to attribute the sale to you, which means you will not be paid a commission for this sale.**\n  - For whitelabel partners, the attractionUrl will dynamically retrieve the partners custom **domain URL**, instead of defaulting to viator.com\n\nExample:\n  - https://www.viator.com/Inverness-attractions/Loch-Ness/d5051-a31?mcid=42383&pid=P00045135&medium=api&version=2.0&campaign=example\n"
        productCount:
          type: integer
          description: Number of products associated with the attraction
        productCodes:
          type: array
          items:
            type: string
            pattern: (?s).*[\S].*
          description: List of `productCodes` associated with the attraction
        images:
          type: array
          description: Images for this attraction
          items:
            $ref: '#/components/schemas/ImageVariant'
        reviews:
          $ref: '#/components/schemas/ProductReviewsSummary'
        freeAttraction:
          type: boolean
          description: Identifies if a admission fee is required to access this attraction
        openingHours:
          type: string
          description: This attraction Opening Hours
        viatorUniqueContent:
          type: object
          description: "Attraction details unique to Viator.com\n\n**Note**:\n  - Access to this information is only available if it is enabled for your account. Please [reach out to our support team](#section/Support) if you would like to take advantage of our unique content..\n  - You must ensure that your site is configured such that **no Viator Unique Content is indexed by any search engine**. This is a requirement for site certification. For more information, see [Key concepts – Protecting unique content](#section/Key-concepts/Protecting-unique-content)\n"
          properties:
            introduction:
              type: string
              description: 'Natural-language descriptive text for this attraction


                **Note**: This field contains natural language suitable for display to the user; content will be translated (if necessary) into the language specified in the Accept-Language header parameter

                '
            overview:
              type: object
              properties:
                sections:
                  type: array
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        description: Section title
                      text:
                        type: string
                        description: 'Section text

                          **Note**: Certain parts of the response may HTML content

                          '
              description: "Natural-language practical information about this attraction. Amount and content of sections is not standardized across attractions.\n\n**Notes**: \n- This field contains natural language suitable for display to the user; content will be translated (if necessary) into the language specified in the Accept-Language header parameter. It will not be returned if translation is not available.\n"
        translationInfo:
          $ref: '#/components/schemas/TranslationDetails'
        center:
          $ref: '#/components/schemas/LocationCenter'
        address:
          type: object
          description: Address details for this attraction
          properties:
            street:
              type: string
              description: Street address of the attraction
            city:
              type: string
              description: Name of the city in which the attraction is located
            state:
              type: string
              description: State in which the attraction is located
            postcode:
              type: string
              description: Postcode in which the attraction is located
    AttractionsSearchResponse:
      type: object
      properties:
        attractions:
          type: array
          items:
            $ref: '#/components/schemas/AttractionDetails'
        totalCount:
          type: integer
          format: int32
          description: Total number of products matching the filtering criteria – these may be accessed via multiple calls to this service using the pagination feature
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        timestamp:
          type: string
          format: date-time
          description: "Timestamp of the request. \n\n**Example**: `\"2019-09-17T03:20:45.737043Z\"`\n"
        trackingId:
          type: string
          description: "Tracking identifier for this error response. \n\n**Example**: `\"0A871A13:DE2A_0A8712F9:01BB_5DCCC98C_260DAA:0D5B\"`\n"
    ProductReviewsSummary:
      type: object
      description: "Summary of reviews and ratings for this attraction\n\n**Note**:\n  - Review data is updated daily; i.e., all reviews received on a day will be added and averages re-calculated in a single event.\n  - Viator performs checks on reviews - for more information, see [Review authenticity](#section/Key-concepts/Review-authenticity)\n"
      required:
      - totalReviews
      properties:
        sources:
          type: array
          description: Breakdown of review summaries for each review source
          items:
            $ref: '#/components/schemas/ProductReviewsSummarySource'
        reviewCountTotals:
          type: array
          description: Breakdown of number of reviews per rating for all reviews of this product
          items:
            $ref: '#/components/schemas/ProductReviewsSummaryCount'
        totalReviews:
          description: Total number of reviews available for this product from all sources
          type: integer
          format: int64
        combinedAverageRating:
          description: Combined average rating for this product across all reviews from all sources
          type: number
          format: float
  parameters:
    accept:
      in: header
      name: Accept
      description: 'Specifies the version of this API to access

        '
      required: true
      schema:
        type: string
        example: application/json;version=2.0
    campaignValueAttraction:
      name: campaign-value
      in: query
      description: '**Affiliate partners only**: Specifies the campaign tracking identifier that will be appended to the URL returned in `attractionUrl` as a query parameter. Campaigns allow you to track how specific links perform, with metrics such as sessions, bookings, and commission. Reports are available via the Viator Partner Platform.


        **Note**: If you wish to use a campaign value that includes non-alphanumeric characters (e.g., ''+'', ''-'', etc.), you must URL-encode these characters.

        '
      required: false
      schema:
        type: string
        maxLength: 200
    acceptLanguage:
      in: header
      name: Accept-Language
      description: 'Specifies the language into which the natural-language fields in the response from this service will be translated (see [Accept-Language header](#section/Localization/Accept-Language-header-parameter) for available language codes)

        '
      required: true
      schema:
        type: string
        example: en-US
  securitySchemes:
    API-key:
      type: apiKey
      in: header
      name: exp-api-key