GetYourGuide Tours API

openapi: 3.2.0
info:
  title: Partner Api Bookings Tours 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: Tours
paths:
  /{version}/tours:
    get:
      operationId: ToursQuery
      summary: Search for tours by different parameters such as a query or geographical coordinates.
      tags:
      - Tours
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/cntLanguage'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/preformatted'
      - $ref: '#/components/parameters/q'
      - $ref: '#/components/parameters/coordinates'
      - $ref: '#/components/parameters/dates'
      - $ref: '#/components/parameters/condLanguages'
      - $ref: '#/components/parameters/prices'
      - $ref: '#/components/parameters/categories'
      - $ref: '#/components/parameters/ratings'
      - $ref: '#/components/parameters/durations'
      - $ref: '#/components/parameters/flags'
      - $ref: '#/components/parameters/sortfield-2'
      - $ref: '#/components/parameters/sortdirection'
      - $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:
                      tours:
                        type: array
                        items:
                          $ref: '#/components/schemas/Tour'
        '400':
          description: Missing Parameters
        '500':
          description: Server error
  /{version}/tours/{tour_id}:
    get:
      operationId: ToursByIdQuery
      summary: Search for tours by id
      tags:
      - Tours
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/tourId'
      - $ref: '#/components/parameters/cntLanguage'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/preformatted'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/MetaData'
                  data:
                    type: object
                    properties:
                      tours:
                        type: array
                        items:
                          $ref: '#/components/schemas/Tour'
        4XX:
          $ref: '#/components/responses/4XX'
        default:
          $ref: '#/components/responses/Default'
  /{version}/tours/{tour_id}/availability:
    get:
      operationId: tours-by-id-availability
      summary: Find availability of a tour.
      tags:
      - Tours
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/tourId'
      - $ref: '#/components/parameters/cnt-language'
      responses:
        '200':
          $ref: '#/components/responses/AvailabilityResponse'
        4XX:
          $ref: '#/components/responses/4XX'
        default:
          $ref: '#/components/responses/Default'
  /{version}/tours/{tour_id}/options:
    get:
      operationId: ToursByIdOptions
      summary: Find all options of a tour.
      tags:
      - Tours
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/tourId'
      - $ref: '#/components/parameters/cntLanguage'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/dates'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/MetaData'
                  data:
                    type: object
                    properties:
                      tour_options:
                        type: array
                        items:
                          $ref: '#/components/schemas/TourOption'
        4XX:
          $ref: '#/components/responses/4XX'
        default:
          $ref: '#/components/responses/Default'
  /{version}/tours/{tour_id}/price-breakdown:
    post:
      operationId: tours-by-id-price-breakdown
      description: Find pricing information for a tour by date.
      tags:
      - Tours
      parameters:
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/tourId'
      requestBody:
        $ref: '#/components/requestBodies/DayBreakdownRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/DayBreakdownResponse'
        4XX:
          $ref: '#/components/responses/4XX'
        default:
          $ref: '#/components/responses/Default'
components:
  schemas:
    SupplierId:
      description: The supplier id
      type: integer
      example: 90545
    UnavailabilityReason:
      type: object
      required:
      - reason_group
      properties:
        reason_group:
          type: string
          example: not_enough_spots
          description: 'Possible values:

            - no_availability

            - not_enough_spots

            - invalid_request

            - others

            '
    Country:
      description: ISO code of the country of the location (ISO 3166-1).
      example: US
      type: string
    HealthAdvisory:
      type: array
      deprecated: true
      items:
        type: object
        properties:
          tag_id:
            type: integer
            description: Tag Id
            example: 161578
          name:
            type: string
            description: Tag name
            example: Frequent_cleaning
          text:
            type: string
            description: Verbose description
            example: All areas that customers touch are frequently cleaned
    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'
    Special:
      type: object
      properties:
        original_price:
          $ref: '#/components/schemas/PriceField'
        savings:
          type: number
          description: The maximum possible discount in percent.
          example: 12
        apps_only:
          type: boolean
          description: Flag if the special offer is only available for the GYG internal mobile apps.
    ItineraryItemDuration:
      description: How long a stop lasts.
      type: object
      properties:
        value:
          type:
          - number
          - 'null'
          format: float
          description: Numeric duration value.
          example: 1.5
        unit:
          type:
          - string
          - 'null'
          enum:
          - day
          - hour
          - minute
          description: Time unit for the duration value.
          example: hour
    CancellationPolicyText:
      description: Cancellation policy text. Kept for backwards compatibility, please use CancellationPolicy.cancellation_policy_text instead.
      deprecated: true
      example: Your activity is non-refundable
      type: string
    ValidityFrom:
      type: string
      description: When the validity period starts counting from.
      enum:
      - time_booked
      - time_selected
      - time_activated
      example: time_booked
    Duration:
      type: number
      description: Duration of the tour (to be used in combination with duration unit).
      example: 2.5
    OptionId:
      description: The ID of the tour option.
      example: 69232
      type: integer
    Longitude:
      description: The longitude in ISO 6709 standard.
      type: number
      format: float
      minimum: -180
      maximum: 180
      example: -81.5545306
    Date:
      description: The local date format `Y-m-d`.
      example: '2023-09-01'
      format: date
      type: string
    OpeningHour:
      type: object
      required:
      - from
      - to
      properties:
        from:
          type: string
          example: '14:00'
        to:
          type: string
          example: '18:00'
    Coordinates:
      type: object
      required:
      - lat
      - long
      properties:
        lat:
          $ref: '#/components/schemas/Latitude'
        long:
          $ref: '#/components/schemas/Longitude'
    Validity:
      type: number
      format: float
      description: Validity period of the booking (to be used in combination with validity unit). Represents how long the ticket/voucher remains valid after booking or activation.
      example: 30
    Option:
      type: object
      required:
      - option_id
      - time_slots
      properties:
        option_id:
          type: integer
          format: int64
          example: 1231
        next_available_date:
          type: string
          format: date
          description: Next available date for the option, in case no timeslots could be found for a given date and participants.
        opening_hours:
          description: This field is show if the given product does not offer fixed time slots, but has opening hours for which a ticket will be valid.
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/OpeningHour'
        time_slots:
          type: array
          items:
            $ref: '#/components/schemas/TimeSlot'
    CancellationPolicy:
      description: The activity cancellation policy
      type: object
      properties:
        cancellable:
          description: Indicates whether the booking is cancellable.
          type: boolean
          example: true
        cancellation_fee_unit:
          description: The type of cancellation fee.
          type: string
          enum:
          - fixed
          - percentage
          example: standard
        cancellation_fee_value:
          description: The cancellation fee percentage if fee_type is percentage or the fixed amount in the requested currency. Null or 0 means no cancellation fee.
          type: number
          format: float
          example: 10
        cancellation_offset_minutes:
          description: The time in minutes before the start of the activity when the booking can be cancelled. Null or 0 means that the booking can be cancelled at any time.
          type: integer
          format: int32
          example: 2880
        cancellation_policy_text:
          description: The cancellation policy text.
          type: string
          example: You can cancel your booking up to 48 hours before the start of the activity for a full refund.
    FreeSale:
      type: boolean
      description: Indicates whether if the tour option's booking engine is free-sale (i.e. whether a booking does not require confirmation by the supplier).
      example: true
    DurationUnit:
      type: string
      description: Unit of the duration field
      enum:
      - day
      - hour
      - minute
      example: hour
    IntegerRange:
      type: object
      properties:
        min:
          type: integer
          description: Minimum value of the range.
          example: 1
        max:
          type: integer
          description: Maximum value of the range.
          example: 20
    Version:
      description: The version of the API, currently only 1 is available.
      example: '1'
      type: string
      format: integer
    Flags:
      description: Various flags about properties of the tour (multiple selection allowed).
      type: string
      enum:
      - private
      - wheelchair
      - skip-line
      - pick-up
      - special
      - free-sale-only
      - mobile-voucher-only
    AdditionalPaxBreakdown:
      type: object
      required:
      - max_group_size
      - quantity
      - price
      properties:
        quantity:
          type: integer
          description: Number of individual/group participants, or addon items.
          example: 5
        price:
          $ref: '#/components/schemas/Price'
        deal_information:
          $ref: '#/components/schemas/DealInformation'
    GroupPriceBreakdown:
      type: object
      required:
      - category_id
      - group_breakdown
      properties:
        category_id:
          type: integer
          description: The value to use when adding the group participants to the booking.
          format: int64
          example: 1
        group_breakdown:
          $ref: '#/components/schemas/GroupBreakdown'
        additional_pax_breakdown:
          $ref: '#/components/schemas/AdditionalPaxBreakdown'
    Price:
      type: object
      required:
      - retail_price
      - currency
      properties:
        customer_base_price:
          type: number
          example: 45
          description: The price for which the tour option category is sold to the customer excluding discounts if any.
        retail_price:
          type: number
          example: 40
          description: The price for which the tour option category is sold to the customer.
        currency:
          type: string
          description: ISO 4217, The currency with which you would like to pay.
          example: USD
    TourId:
      description: The ID of the tour.
      example: 50872
      type: integer
    StartingPrice:
      type: object
      description: Starting price. Should be read as e.g. "from XX.YY USD.
      properties:
        values:
          type: object
          properties:
            amount:
              $ref: '#/components/schemas/PriceField'
        description:
          type: string
          description: Additional information about the pricing. E.g. 'per group' or 'per person' or 'per Group up to 10 people'.
          example: individual
    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
    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
    ItineraryItemLocation:
      description: Location of an itinerary stop.
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Display name of the location.
          example: Colosseum
        coordinates:
          $ref: '#/components/schemas/Coordinates'
    ParticipantCategory:
      type: object
      required:
      - ticket_category
      - name
      properties:
        ticket_category:
          type: string
          example: adult
          description: 'Possible values:

            - infant

            - child

            - youth

            - student

            - eu_citizen_student

            - adult

            - eu_citizen

            - military

            - senior

            - group

            '
        name:
          type: string
          example: Adults
        age_range:
          $ref: '#/components/schemas/IntegerRange'
        independently_bookable:
          description: Only relevant for non-group categories
          type: boolean
          example: true
    IndividualCategoryPriceBreakdown:
      type: object
      required:
      - category_id
      - ticket_category
      - quantity
      - price
      properties:
        category_id:
          type: integer
          format: int64
          description: The value to use when adding the individual participants to the booking.
          example: 1
        quantity:
          type: integer
          description: Number of individual/group participants, or addon items.
          example: 5
        price:
          $ref: '#/components/schemas/Price'
        ticket_category:
          type: string
          description: 'Possible values:

            - adult

            - child

            - youth

            - infant

            - senior

            - student

            - eu_citizen

            - military

            - eu_citizen_student

            '
          example: adult
        min_age:
          type: integer
          description: Minimum age of participant.
          example: 16
        max_age:
          type: integer
          description: Maximum age of participant.
          example: 64
        independently_bookable:
          type: boolean
          description: Whether or not the category can be booked on its own.
        deal_information:
          $ref: '#/components/schemas/DealInformation'
    Tour:
      description: A tour is a product.
      type: object
      properties:
        tour_id:
          $ref: '#/components/schemas/TourId'
        tour_code:
          deprecated: true
          type: string
          description: Deprecated field, does not contain any meaningful information.
          example: deprecated
        cond_language:
          type: array
          description: Available conduction languages.
          items:
            $ref: '#/components/schemas/Language'
          example:
          - en
          - de
          - es
        title:
          type: string
          description: Title of the option.
          example: 2-Park 2-Day Universal Orlando™ Theme Park Tickets
        abstract:
          type: string
          description: Short description of the tour.
          example: Universal Orlando Resort is an entire universe of action and thrills with two jaw-dropping theme parks, exceptional shopping and incredible entere unforgettable experiences together. You can have the ultimate adventure, enjoy fun with your kids, rejuvenatainment
        description:
          type: string
          description: Long description of the tour.
          example: At both Universal Studios Florida and Universal's Islands of Adventure ... The ticket must be used by the first use date printed on the ticket. The ticket will expire in full on the expiration date printed on ticket. Unused days shall be forfeited. These tickets are not valid for residents of the UK and Ireland
        is_auto_translation:
          type: boolean
          description: Flag if the title, abstract, description, … are auto-translated.
          example: false
        is_english_fallback:
          type: boolean
          description: Flag if the title, abstract, description, … are English since we don't have the translation yet.
          example: false
        additional_information:
          type: string
          description: Additional information for the customer.
          example: Tickets must be used by the same person on all days...you must present the actual Universal Orlando ticket to receive entry to the parks.
        items_to_bring:
          type: array
          description: Recommended items the customer should bring.
          items:
            type: string
          example:
          - Comfortable shoes
          - Sunscreen
        not_allowed:
          type: array
          description: Things that are not allowed to bring to the activity.
          items:
            type: string
          example:
          - Alcohol
          - Pets
        not_suitable_for:
          type: array
          description: Certain demographics for whom this activity is not suitable.
          items:
            type: string
          example:
          - Children under 3 years
          - People with impeded movement.
        bestseller:
          type: boolean
          description: Flag if the tour is a bestseller.
          example: false
        certified:
          type: boolean
          description: Flag if the tour is a certified tour.
          example: true
        has_pick_up:
          type: boolean
          description: Indicates if pickup is available for this product
          example: true
        overall_rating:
          $ref: '#/components/schemas/Rating'
        number_of_ratings:
          type: integer
          description: Number of rating of the tour.
          example: 25
        highlights:
          type: array
          description: List of highlights of that tour.
          items:
            type: string
        inclusions:
          type: string
          description: What's included in the tour.
          example: • Entry to both Universal Studios Florida and Universal’s Islands of Adventure for 2-days
        exclusions:
          type: string
          description: What's not included in the tour.
          example: Parking
        pictures:
          type: array
          items:
            $ref: '#/components/schemas/Picture'
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        price:
          oneOf:
          - $ref: '#/components/schemas/StartingPrice'
          - $ref: '#/components/schemas/StartingPriceDiscounted'
        categories:
          description: List of tour categories tagged to this tour.
          type: array
          items:
            $ref: '#/components/schemas/TourCategoryMinimal'
        health_advisory:
          $ref: '#/components/schemas/HealthAdvisory'
        health_requirement:
          $ref: '#/components/schemas/HealthRequirement'
        locations:
          description: List of locations ordered according to importance.
          type: array
          items:
            $ref: '#/components/schemas/Location'
        url:
          type: string
          format: uri
          description: URL of the tour on the GetYourGuide website.
          example: https://www-getyourguide-com.partner.gygtest.com/orlando-l191/walt-disney-world-orlando-with-ticket-options-t50872/?partner_id=173E8&psrc=partner_api¤cy=EUR
        translations:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Language'
        free_sale:
          type: boolean
          description: Indicates whether there exists at least one tour option of which the booking engine is free-sale (i.e. whether a booking does not require confirmation by the supplier).
        guide_type:
          type: string
          enum:
          - none
          - host_greeter
          - instructor
          - driver
          - live_tour_guide
          - self_guided
          description: "Type of guide that is conducting the tour, available are\n  * `none`: no guide available for this tour.\n  * `host_greeter`: a host or greeter that welcomes the customer.\n  * `instructor`: an instructor e.g. for diving classes.\n  * `driver`: a driver for motorized tours.\n  * `live_tour_guide`: a standard live tour guide.\n  * `self_guided`: tour conducted without a guide; the customer explores on their own.\n"
        mobile_voucher:
          type: boolean
          description: If the tour accepts mobile voucher.
          example: true
        supplier_id:
          $ref: '#/components/schemas/SupplierId'
        durations:
          type: array
          items:
            $ref: '#/components/schemas/Durations'
        opening_hours:
          description: A list of opening hours for a given attraction or venue in local time.
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/OpeningHours'
        cancellation_policy:
          $ref: '#/components/schemas/CancellationPolicy'
        cancellation_policy_text:
          $ref: '#/components/schemas/CancellationPolicyText'
        itineraries:
          type:
          - array
          - 'null'
          description: Structured itinerary describing the ordered stops/days of the tour. May be null or empty for tours without structured itinerary data.
          items:
            $ref: '#/components/schemas/Itinerary'
    Rating:
      description: The value of the rating.
      minimum: 0
      maximum: 5
      example: 4.5
      type: number
      format: float
    Availability:
      description: Availability by tour.
      type: object
      required:
      - tour_id
      - participants_range
      - categories
      - available_dates
      - update_timestamp
      properties:
        tour_id:
          $ref: '#/components/schemas/TourId'
        participants_range:
          $ref: '#/components/schemas/IntegerRange'
        categories:
          description: List of tour categories available to book.
          type: array
          items:
            $ref: '#/components/schemas/ParticipantCategory'
        addons:
          description: List of addons available to book within a tour (not necessarily present in all the tour-options within a tour).
          type: array
          items:
            $ref: '#/components/schemas/AvailableAddon'
        available_dates:
          description: List of available dates to book for this tour.
          type: array
          items:
            $ref: '#/components/schemas/AvailableDate'
        update_timestamp:
          description: The timestamp of the last update to the available entity (in UTC).
          type: string
          format: date-time
          example: '2023-01-23T04:56:07'
    CategoryId:
      description: ID of the category.
      example: 33
      type: integer
    BoundingBox:
      type: object
      properties:
        sw_lat:
          type: number
          format: double
        sw_long:
          type: number
          format: double
        ne_lat:
          type: number
          format: double
        ne_long:
          type: number
          format: double
    Offset:
      description: Offset the list of returned results by this amount.
      type: integer
      minimum: 0
      default: 0
      example: 0
    LocalDateRange:
      type: object
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
    StartingPriceDiscounted:
      type: object
      description: Starting price and theoretic maximum possible discount. Should be read as e.g. "from XX.YY USD. The discounts are still bound to individual dates.
      properties:
        values:
          type: object
          properties:
            amount:
              $ref: '#/components/schemas/PriceField'
            special:
              $ref: '#/components/schemas/Special'
        description:
          type: string
          description: Additional information about the pricing. E.g. 'per group' or 'per person' or 'per Group up to 10 people'.
          example: individual
    TourOption:
      description: Tour option
      type: object
      properties:
        option_id:
          $ref: '#/components/schemas/OptionId'
        tour_id:
          $ref: '#/components/schemas/TourId'
        title:
          type: string
          description: Title of the option.
          example: 'From Abu Dhabi: Private Transfer to Dubai'
        description:
          type: string
          description: Description of the option.
        pick_up:
          type: string
          description: Information about the hotel pickup possibilities.
        pick_up_location:
          $ref: '#/components/schemas/PickUpLocation'
        meeting_point:
          type: string
          description: Information about where to meet.
        drop_off:
          type: string
          description: Information about the drop-off (where the tour ends).
        duration:
          $ref: '#/components/schemas/Duration'
        duration_unit:
          $ref: '#/components/schemas/DurationUnit'
        validity:
          $ref: '#/components/schemas/Validity'
        validity_unit:
          $ref: '#/components/schemas/ValidityUnit'
        validity_from:
          $ref: '#/components/schemas/ValidityFrom'
        cond_language:
          type: object
          properties:
            language_audio:
              type: array
              items:
                $ref: '#/components/schemas/Language'
              description: List of languages that are available as audio guide
              example:
              - de
              - fr
              - es
              - ru
            language_booklet:
              type: array
              items:
                $ref: '#/components/schemas/Language'
              description: List of languages that are available as booklet
              example:
              - de
              - fr
              - en
            language_live:
              type: array
              items:
                $ref: '#/components/schemas/Language'
              description: List of languages that are spoken by the guide
              example:
              - de
              - en
        booking_parameter:
          deprecated: true
          description: DEPRECATED! use questions instead
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the booking parameter.
                enum:
                - language
                - hotel
                - comment
                - supplier_requested_question
                example: supplier_requested_question
              description:
                type: string
                description: Description of the property.
                example: Please provide the client names, flight details, and pick up and drop-off location.
              mandatory:
        

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getyourguide/refs/heads/main/openapi/getyourguide-tours-api-openapi.yml