openapi: 3.0.0
info:
  title: Partner Api Bookings Categories 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: Categories
paths:
  /{version}/categories:
    get:
      operationId: CategoriesList
      summary: List all categories
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/cntLanguage'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/MetaData'
                  data:
                    type: object
                    properties:
                      categories:
                        type: array
                        items:
                          $ref: '#/components/schemas/TourCategory'
        4XX:
          $ref: '#/components/responses/4XX'
        default:
          $ref: '#/components/responses/Default'
  /{version}/categories/{category_id}:
    get:
      operationId: CategoriesGetById
      summary: Get information about a category
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/categoryId'
      - $ref: '#/components/parameters/cntLanguage'
      - $ref: '#/components/parameters/currency'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/MetaData'
                  data:
                    type: object
                    properties:
                      categories:
                        type: array
                        items:
                          $ref: '#/components/schemas/TourCategory'
        4XX:
          $ref: '#/components/responses/4XX'
        default:
          $ref: '#/components/responses/Default'
components:
  schemas:
    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
    CategoryId:
      description: ID of the category.
      example: 33
      type: integer
    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'
    TourCategory:
      type: object
      properties:
        category_id:
          $ref: '#/components/schemas/CategoryId'
        name:
          type: string
          description: Name of the category.
          example: Theme Parks & Amusement Parks
        parent_id:
          $ref: '#/components/schemas/CategoryId'
        number_of_tours:
          type: integer
          description: Number of available tours in the category.
          example: 10
    Datetime:
      description: The local datetime format `Y-m-d T H:i:s`.
      example: '2017-09-01T00:00:00'
      format: date-time
      type: string
    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
  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'
    offset:
      in: query
      name: offset
      required: false
      schema:
        $ref: '#/components/schemas/Offset'
    limit:
      in: query
      name: limit
      required: false
      schema:
        $ref: '#/components/schemas/Limit'
    categoryId:
      in: path
      name: category_id
      required: true
      schema:
        $ref: '#/components/schemas/CategoryId'
    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