openapi: 3.0.0
info:
  title: Partner Api Bookings Reviews API
  description: This GetYourGuide Partner API provides access to GetYourGuide’s marketplace for tours and activities. It has a RESTful interface and uses the JSON media format. Access is secured via SSL and an API access token. Further documentation can be found in the public GitHub repository linked below. Do not forget to also check out the GitHub wiki for some more extensive guides.
  version: 1.0.0
  contact:
    name: Partner Tech
    url: https://partner.getyourguide.com/
  license:
    name: Apache License, Version 2.0
    url: https://github.com/getyourguide/partner-api-spec/blob/main/LICENSE
servers:
- url: https://api.getyourguide.com
  description: Production
- url: https://api.gygtest.net
  description: Testing
security:
- ApiKeyAuth: []
tags:
- name: Reviews
paths:
  /{version}/reviews/tour/{tour_id}:
    get:
      operationId: Reviews
      tags:
      - Reviews
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/tourId'
      - $ref: '#/components/parameters/cntLanguage'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/date'
      - $ref: '#/components/parameters/sortfield'
      - $ref: '#/components/parameters/sortdirection'
      - $ref: '#/components/parameters/limit-2'
      - $ref: '#/components/parameters/offset-2'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/MetaData'
                  data:
                    type: object
                    properties:
                      reviews:
                        type: object
                        properties:
                          outline:
                            $ref: '#/components/schemas/Outline'
                          review_items:
                            $ref: '#/components/schemas/ReviewItems'
        4XX:
          $ref: '#/components/responses/4XX'
        default:
          $ref: '#/components/responses/Default'
components:
  schemas:
    Outline:
      type: array
      items:
        type: object
        properties:
          rating:
            $ref: '#/components/schemas/Rating'
          number_of_reviews:
            type: integer
            description: The number of reviews for this rating.
            example: 20
          share:
            type: number
            description: The percentage of all reviews that have this rating.
            example: 96
    Currency:
      description: ISO 4217, The currency with which you would like to pay.
      enum:
      - AED
      - ARS
      - AUD
      - BGN
      - CAD
      - CHF
      - CLP
      - CNY
      - COP
      - CZK
      - DKK
      - EGP
      - EUR
      - GBP
      - HKD
      - HRK
      - HUF
      - IDR
      - ILS
      - INR
      - JPY
      - KRW
      - MAD
      - MXN
      - MYR
      - NOK
      - NZD
      - PHP
      - PLN
      - RON
      - RUB
      - SEK
      - SGD
      - THB
      - TRY
      - UAH
      - USD
      - UYU
      - VND
      - ZAR
      example: USD
      type: string
    Language:
      type: string
      description: ISO 639 formatted language
      example: en
    Version:
      description: The version of the API, currently only 1 is available.
      example: '1'
      type: string
      format: integer
    ReviewItems:
      type: array
      items:
        type: object
        properties:
          review_id:
            type: integer
            description: The review ID.
            example: 786101
          tour_id:
            $ref: '#/components/schemas/TourId'
          supplier_id:
            $ref: '#/components/schemas/SupplierId'
          review_date:
            $ref: '#/components/schemas/Datetime'
          subject:
            type: string
            description: The subject of the review.
            example: Very good
          comment:
            type: string
            description: A comment of the user about the tour.
            example: Super
          reviewer_name:
            type: string
            description: The name of the person who did the review.
            example: Reichenbach – France
          review_rating:
            $ref: '#/components/schemas/Rating'
          review_rating_service:
            $ref: '#/components/schemas/Rating'
          review_rating_orga:
            $ref: '#/components/schemas/Rating'
          review_rating_value:
            $ref: '#/components/schemas/Rating'
          review_rating_safety:
            $ref: '#/components/schemas/Rating'
    Limit:
      description: Number of items to retrieve.
      type: integer
      minimum: 1
      maximum: 500
      default: 10
      example: 10
    MetaData:
      type: object
      properties:
        descriptor:
          type: string
          example: GetYourGuide AG
        date:
          $ref: '#/components/schemas/Datetime'
        status:
          type: string
          description: Status of the request
          example: OK
        query:
          type: string
          description: URL parameters used for the request sent
          example: cnt_language=en&currency=eur
        availableLanguages:
          type: array
          description: Available conduction languages aggregated across all tours
          items:
            $ref: '#/components/schemas/Language'
          example:
          - en
          - es
          - fr
        exchange:
          type: object
          description: Deprecated! Please do not use to calculate prices, but pass a different currency parameter in the request URL.
          properties:
            rate:
              type: integer
              example: 1
            currency:
              $ref: '#/components/schemas/Currency'
        totalCount:
          type: integer
          description: Total amount of tours that match the search query
          example: 127
        limit:
          $ref: '#/components/schemas/Limit'
        offset:
          $ref: '#/components/schemas/Offset'
    Datetime:
      description: The local datetime format `Y-m-d T H:i:s`.
      example: '2017-09-01T00:00:00'
      format: date-time
      type: string
    Rating:
      description: The value of the rating.
      minimum: 0
      maximum: 5
      example: 4.5
      type: number
      format: float
    Offset-2:
      description: Offset the list of returned results by this amount.
      type: integer
      minimum: 0
      maximum: 300
      default: 0
      example: 0
    SupplierId:
      description: The supplier id
      type: integer
      example: 90545
    Limit-2:
      description: Number of reviews to retrieve.
      type: integer
      minimum: 1
      maximum: 50
      default: 10
      example: 10
    Error:
      type: object
      properties:
        descriptor:
          type: string
          example: GetYourGuide AG
        apiVersion:
          type: string
          example: '1'
        method:
          type: string
          example: getBookingByHashAction
        date:
          $ref: '#/components/schemas/Datetime'
        status:
          type: string
          example: ERROR
        query:
          type: string
          example: cnt_language=en&currency=eur
        errors:
          type: array
          items:
            type: object
            properties:
              errorCode:
                description: GetYourGuide internal error code
                type: integer
                format: int32
                example: 25
              errorMessage:
                description: Verbose description of the error.
                type: string
                example: Unauthorized. The access token is invalid.
        helpURL:
          type: string
          example: https://api.getyourguide.com/doc
    Offset:
      description: Offset the list of returned results by this amount.
      type: integer
      minimum: 0
      default: 0
      example: 0
    CntLanguage:
      description: ISO 639, Language of the text content.
      enum:
      - ar
      - ca
      - cs
      - da
      - de
      - el
      - en
      - es
      - et
      - fi
      - fr
      - he
      - hr
      - hu
      - id
      - it
      - ja
      - ko
      - lt
      - lv
      - ms
      - nl
      - 'no'
      - pl
      - pt
      - ro
      - ru
      - sk
      - sv
      - th
      - tr
      - zh
      - zh-hant
      example: en
      type: string
    TourId:
      description: The ID of the tour.
      example: 50872
      type: integer
  parameters:
    currency:
      description: ISO 4217, The currency with which you would like to pay.
      in: query
      name: currency
      example: USD
      required: true
      schema:
        $ref: '#/components/schemas/Currency'
    sortdirection:
      description: Defines the sort order. Ignored when `sortfield=popularity`.
      in: query
      name: sortdirection
      required: false
      schema:
        enum:
        - DESC
        - ASC
        type: string
    date:
      description: Defines the date of the oldest review that should be returned.
      in: query
      name: date
      required: false
      schema:
        $ref: '#/components/schemas/Datetime'
    offset-2:
      description: Defines the offset of the first review that should be returned. Currently limited to 300.
      in: query
      name: offset
      required: false
      schema:
        $ref: '#/components/schemas/Offset-2'
    limit-2:
      description: Number of reviews to retrieve. Maximum value for this endpoint is 50.
      in: query
      name: limit
      required: false
      schema:
        $ref: '#/components/schemas/Limit-2'
    tourId:
      in: path
      name: tour_id
      required: true
      schema:
        $ref: '#/components/schemas/TourId'
    sortfield:
      description: Defines the sort field.
      in: query
      name: sortfield
      required: false
      schema:
        enum:
        - rating
        - date
        type: string
    version:
      in: path
      name: version
      required: true
      schema:
        $ref: '#/components/schemas/Version'
    cntLanguage:
      in: query
      name: cnt_language
      required: true
      schema:
        $ref: '#/components/schemas/CntLanguage'
  responses:
    4XX:
      description: HTTP 400, 401, 404 have the same response format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Default:
      description: Other HTTP status codes which do not provide additional information are 403, 405, 429 and 500.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-ACCESS-TOKEN
externalDocs:
  description: Further Documentation, additional resources and best practices
  url: https://github.com/getyourguide/partner-api-spec