GetYourGuide Partner API (getyourguide/partner-api-spec)

GetYourGuide Partner API

https://github.com/getyourguide/partner-api-spec
Admin
GetYourGuide Partner API is a RESTful JSON-based marketplace API that enables partners to search,...

Tokens:31,267
Snippets:163
Trust Score:9.4
Update:3 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# GetYourGuide Partner API

The GetYourGuide Partner API provides access to GetYourGuide's marketplace of 75,000+ tours and activities worldwide. It enables partners to search for activities, check real-time availability and pricing, and complete end-to-end bookings through a modern, JSON-based REST interface. All requests require TLS 1.2+ encryption and authentication via the `X-ACCESS-TOKEN` header.

The API supports three access tiers: BASIC/LIMITED_READ for catalogue browsing, READ for live availability and pricing, and BOOKING for full end-to-end booking capabilities including payment processing. Partners can generate client libraries in 50+ languages using the OpenAPI specification with tools like openapi-generator. The default rate limit is 130 calls per minute with a 5-minute block when exceeded.

## Authentication

All API requests require authentication via the `X-ACCESS-TOKEN` header and must be made over HTTPS. Two headers are required for every request: the access token and the Accept header set to `application/json`.

```bash
# Basic authenticated request with required headers
curl -X GET "https://api.getyourguide.com/1/tours?q=Paris&cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response includes metadata and tour data
{
  "_metadata": {
    "descriptor": "GetYourGuide AG",
    "method": "getTourByQueryAction",
    "date": "2024-01-15T10:30:00Z",
    "status": "OK",
    "totalCount": 498,
    "limit": 10,
    "offset": 0
  },
  "data": {
    "tours": [...]
  }
}
```

## Search Tours

Search for tours and activities by query string, geographic coordinates, date range, ratings, price range, and other filters. Returns a paginated list of tours matching the search criteria with pricing, ratings, and images.

```bash
# Search for tours in Berlin with date range and minimum rating
curl -X GET "https://api.getyourguide.com/1/tours?q=Berlin&date[]=2024-06-01T00:00:00&date[]=2024-06-07T23:59:59&rating[]=4&cnt_language=en&currency=EUR&limit=10&offset=0" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Search by geographic coordinates (latitude, longitude, radius in km)
curl -X GET "https://api.getyourguide.com/1/tours?coordinates[]=48.8566&coordinates[]=2.3522&coordinates[]=10&cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response example
{
  "_metadata": {
    "status": "OK",
    "totalCount": 250,
    "limit": 10,
    "offset": 0
  },
  "data": {
    "tours": [
      {
        "tour_id": 66985,
        "title": "Paris: Catacombs Skip-the-Cash-Desk Ticket with Audio Guide",
        "abstract": "Skip the cash desk line at the Paris Catacombs...",
        "overall_rating": 4.4974,
        "number_of_ratings": 7000,
        "price": {
          "values": { "amount": 29 },
          "description": "individual"
        },
        "pictures": [
          {
            "id": 1,
            "url": "https://cdn.getyourguide.com/img/tour/59cba8cb6b06c.jpeg/[format_id].jpg"
          }
        ],
        "coordinates": { "lat": 48.85693, "long": 2.3412 },
        "url": "https://www.getyourguide.com/paris-l16/paris-catacombs-skip-the-line-ticket-t66985/?partner_id=YOURPARTNERID"
      }
    ]
  }
}
```

## Get Tour Details

Retrieve detailed information about a specific tour by ID, including tour options, meeting points, duration, languages, and booking questions. Use `preformatted=home` to get comprehensive tour information with all options.

```bash
# Get tour details with full information
curl -X GET "https://api.getyourguide.com/1/tours/66985?cnt_language=en&currency=EUR&preformatted=home" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response with tour options and booking questions
{
  "_metadata": { "status": "OK" },
  "data": {
    "tours": [
      {
        "tour_id": 66985,
        "title": "Paris: Catacombs Skip-the-Cash-Desk Ticket with Audio Guide",
        "tour_options": [
          {
            "option_id": 265866,
            "tour_id": 66985,
            "title": "Paris: Catacombs Skip-the-Cash-Desk Ticket with Audio Guide",
            "duration": 1,
            "duration_unit": "hour",
            "meeting_point": "Please go directly with your voucher to the entrance of the catacombs.",
            "cond_language": {
              "language_audio": ["es", "en", "fr", "de"]
            },
            "questions": {
              "booking_questions": [
                { "question": "booking_customer_accommodation", "mandatory": true }
              ],
              "participant_questions": [
                { "question": "traveler_dates_of_birth", "mandatory": true },
                { "question": "traveler_names", "mandatory": true }
              ],
              "conduction_language": { "mandatory": true }
            },
            "price": {
              "values": { "amount": 29 },
              "description": "individual"
            },
            "free_sale": true
          }
        ]
      }
    ]
  }
}
```

## Get Tour Availability

Check available dates, ticket categories, participant ranges, and add-ons for a specific tour. Returns availability for the next 16 months.

```bash
# Get tour availability
curl -X GET "https://api.getyourguide.com/1/tours/66985/availability?cnt-language=en" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response with available dates and categories
{
  "tour_id": 66985,
  "participants_range": {
    "min": 1,
    "max": 20
  },
  "categories": [
    {
      "ticket_category": "adult",
      "name": "Adults",
      "age_range": { "min": 18, "max": 99 },
      "independently_bookable": true
    },
    {
      "ticket_category": "child",
      "name": "Children",
      "age_range": { "min": 6, "max": 17 },
      "independently_bookable": false
    }
  ],
  "addons": [
    {
      "id": 1934,
      "name": "Free drinks",
      "max_quantity": 10
    }
  ],
  "available_dates": [
    { "date": "2024-06-15" },
    { "date": "2024-06-16" },
    { "date": "2024-06-17" }
  ],
  "update_timestamp": "2024-01-15T04:56:07"
}
```

## Get Price Breakdown

Retrieve detailed pricing information for a tour on a specific date with participant configuration. Returns time slots with retail prices, discounts, and category breakdowns.

```bash
# Get price breakdown for individual pricing
curl -X POST "https://api.getyourguide.com/1/tours/66985/price-breakdown" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "base_data": {
      "currency": "EUR"
    },
    "data": {
      "date": "2024-06-15",
      "participants": {
        "adult": 2,
        "child": 1
      }
    }
  }'

# Response with pricing for available time slots
{
  "options": [
    {
      "id": 265866,
      "opening_hours": [
        { "from": "10:00", "to": "18:00" }
      ],
      "time_slots": [
        {
          "date_time": "2024-06-15T11:00:00",
          "price_breakdown": {
            "price_summary": {
              "retail_price": 87,
              "currency": "EUR"
            },
            "individuals": [
              {
                "category_id": 1,
                "ticket_category": "adult",
                "quantity": 2,
                "min_age": 18,
                "max_age": 99,
                "independently_bookable": true,
                "price": { "retail_price": 29, "currency": "EUR" }
              },
              {
                "category_id": 2,
                "ticket_category": "child",
                "quantity": 1,
                "min_age": 6,
                "max_age": 17,
                "independently_bookable": false,
                "price": { "retail_price": 29, "currency": "EUR" }
              }
            ]
          },
          "vacancies": 20
        }
      ]
    }
  ]
}

# Group pricing example
curl -X POST "https://api.getyourguide.com/1/tours/731278/price-breakdown" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "base_data": { "currency": "EUR" },
    "data": {
      "date": "2024-06-15",
      "participants": { "adult": 8 }
    }
  }'

# Group pricing response
{
  "options": [
    {
      "id": 731278,
      "time_slots": [
        {
          "date_time": "2024-06-15T09:00:00",
          "price_breakdown": {
            "price_summary": { "retail_price": 1377, "currency": "EUR" },
            "groups": [
              {
                "group_breakdown": {
                  "max_group_size": 4,
                  "price": { "retail_price": 689, "currency": "EUR" },
                  "quantity": 4,
                  "ticket_category": "group"
                },
                "additional_pax_breakdown": {
                  "price": { "retail_price": 172, "currency": "EUR" },
                  "quantity": 4,
                  "ticket_category": "group"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}
```

## Create Booking

Create a new booking by adding an activity to a shopping cart. Requires option_id, date_time, categories with participant counts, price, and answers to mandatory questions. Returns a shopping cart hash and booking hash for further processing.

```bash
# Create a booking with participant questions
curl -X POST "https://api.getyourguide.com/1/bookings" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "base_data": {
      "cnt_language": "en",
      "currency": "EUR"
    },
    "data": {
      "booking": {
        "bookable": {
          "option_id": 265866,
          "datetime": "2024-06-15T11:00:00",
          "price": 87.00,
          "categories": [
            { "category_id": 1, "number_of_participants": 2 },
            { "category_id": 2, "number_of_participants": 1 }
          ],
          "questions": {
            "booking_questions": {
              "booking_customer_accommodation": {
                "value": "Hotel Ritz Paris, 15 Place Vendome"
              }
            },
            "participant_questions": [
              {
                "category_id": 1,
                "participant_answers": {
                  "traveler_date_of_birth": { "value": "1985-03-15" },
                  "traveler_name": { "first_name": "John", "last_name": "Smith" }
                }
              },
              {
                "category_id": 1,
                "participant_answers": {
                  "traveler_date_of_birth": { "value": "1987-07-22" },
                  "traveler_name": { "first_name": "Jane", "last_name": "Smith" }
                }
              },
              {
                "category_id": 2,
                "participant_answers": {
                  "traveler_date_of_birth": { "value": "2015-11-08" },
                  "traveler_name": { "first_name": "Emily", "last_name": "Smith" }
                }
              }
            ],
            "conduction_language": {
              "type": "language_audio",
              "value": "en"
            }
          }
        }
      }
    }
  }'

# Successful booking response
{
  "_metadata": {
    "status": "OK"
  },
  "data": {
    "bookings": {
      "shopping_cart_id": 290561411,
      "shopping_cart_hash": "XD93MUY6LTAJKUZHI2F9KHYYWS40T4MX",
      "booking_id": 170250302,
      "booking_hash": "7N1WE8IQU3PI4QJXH1LLSMCDAMJ4QS2GX",
      "status": "temp",
      "return_code": 0
    }
  }
}

# Add another booking to existing cart
curl -X POST "https://api.getyourguide.com/1/bookings" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "base_data": { "cnt_language": "en", "currency": "EUR" },
    "data": {
      "booking": {
        "shopping_cart_id": 290561411,
        "bookable": {
          "option_id": 123456,
          "datetime": "2024-06-16T09:00:00",
          "price": 45.00,
          "categories": [{ "category_id": 1, "number_of_participants": 2 }],
          "external_reference_id": "MY-REF-12345"
        }
      }
    }
  }'
```

## Get Booking Details

Retrieve information about a specific booking using its booking hash. Returns booking status, tour details, participants, and voucher information.

```bash
# Get booking information
curl -X GET "https://api.getyourguide.com/1/bookings/7N1WE8IQU3PI4QJXH1LLSMCDAMJ4QS2GX?cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response with booking details
{
  "_metadata": { "status": "OK" },
  "data": {
    "booking": {
      "booking_hash": "7N1WE8IQU3PI4QJXH1LLSMCDAMJ4QS2GX",
      "status": "confirmed",
      "tour_id": 66985,
      "option_id": 265866,
      "datetime": "2024-06-15T11:00:00",
      "total_price": 87.00,
      "currency": "EUR"
    }
  }
}
```

## Cancel Booking

Cancel an existing booking using its booking hash. Returns the cancellation status and any applicable refund information.

```bash
# Cancel a booking
curl -X DELETE "https://api.getyourguide.com/1/bookings/7N1WE8IQU3PI4QJXH1LLSMCDAMJ4QS2GX?cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response
{
  "_metadata": { "status": "OK" },
  "data": {
    "booking": {
      "booking_hash": "7N1WE8IQU3PI4QJXH1LLSMCDAMJ4QS2GX",
      "status": "cancelled"
    }
  }
}
```

## Confirm Shopping Cart

Confirm a shopping cart to complete the booking process and process payment. Requires billing information and payment details.

```bash
# Confirm shopping cart with payment
curl -X POST "https://api.getyourguide.com/1/carts" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "base_data": {
      "cnt_language": "en",
      "currency": "EUR"
    },
    "data": {
      "shopping_cart_hash": "XD93MUY6LTAJKUZHI2F9KHYYWS40T4MX",
      "traveler": {
        "email": "john.smith@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "phone_number": "+1234567890"
      },
      "billing": {
        "address": "123 Main Street",
        "city": "Paris",
        "postal_code": "75001",
        "country": "FR"
      },
      "payment": {
        "method": "credit_card",
        "encrypted_card_data": "ENCRYPTED_CARD_DATA_HERE"
      }
    }
  }'

# Response on successful confirmation
{
  "_metadata": { "status": "OK" },
  "data": {
    "shopping_cart": {
      "shopping_cart_hash": "XD93MUY6LTAJKUZHI2F9KHYYWS40T4MX",
      "status": "confirmed",
      "bookings": [
        {
          "booking_hash": "7N1WE8IQU3PI4QJXH1LLSMCDAMJ4QS2GX",
          "status": "confirmed"
        }
      ]
    }
  }
}
```

## Get Shopping Cart

Retrieve information about a shopping cart including all bookings, total price, and status.

```bash
# Get shopping cart details
curl -X GET "https://api.getyourguide.com/1/carts/XD93MUY6LTAJKUZHI2F9KHYYWS40T4MX?cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response
{
  "_metadata": { "status": "OK" },
  "data": {
    "shopping_cart": {
      "shopping_cart_hash": "XD93MUY6LTAJKUZHI2F9KHYYWS40T4MX",
      "status": "temp",
      "total_price": 132.00,
      "currency": "EUR",
      "bookings": [
        {
          "booking_hash": "7N1WE8IQU3PI4QJXH1LLSMCDAMJ4QS2GX",
          "tour_id": 66985,
          "option_id": 265866,
          "price": 87.00
        },
        {
          "booking_hash": "ABC123XYZ789",
          "tour_id": 123456,
          "option_id": 789012,
          "price": 45.00
        }
      ]
    }
  }
}
```

## Get Tour Option Details

Retrieve detailed information about a specific tour option by ID, including pricing, meeting point, questions, and availability.

```bash
# Get option details
curl -X GET "https://api.getyourguide.com/1/options/265866?cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response
{
  "_metadata": { "status": "OK" },
  "data": {
    "tour_options": [
      {
        "option_id": 265866,
        "tour_id": 66985,
        "title": "Paris: Catacombs Skip-the-Cash-Desk Ticket with Audio Guide",
        "description": "Tickets for under 18s must be bought on site.",
        "meeting_point": "Please go directly with your voucher to the entrance of the catacombs.",
        "duration": 1,
        "duration_unit": "hour",
        "price": {
          "values": { "amount": 29 },
          "description": "individual"
        }
      }
    ]
  }
}
```

## List Categories

Retrieve all available tour categories for organizing and filtering activities.

```bash
# List all categories
curl -X GET "https://api.getyourguide.com/1/categories?cnt_language=en&currency=EUR&limit=20" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response
{
  "_metadata": { "status": "OK" },
  "data": {
    "categories": [
      { "category_id": 27, "name": "Culture & History" },
      { "category_id": 28, "name": "Nature & Adventure" },
      { "category_id": 29, "name": "Food & Drink" },
      { "category_id": 30, "name": "Tours & Sightseeing" }
    ]
  }
}
```

## Get Tour Reviews

Retrieve customer reviews for a specific tour with ratings, comments, and reviewer information.

```bash
# Get tour reviews sorted by date
curl -X GET "https://api.getyourguide.com/1/reviews/tour/66985?cnt_language=en&currency=EUR&sortfield=date&sortdirection=DESC&limit=10" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response
{
  "_metadata": { "status": "OK" },
  "data": {
    "reviews": {
      "outline": {
        "overall_rating": 4.5,
        "total_reviews": 7000
      },
      "review_items": [
        {
          "rating": 5,
          "title": "Amazing experience!",
          "message": "The audio guide was very informative...",
          "author": "John D.",
          "date": "2024-01-10"
        }
      ]
    }
  }
}
```

## Get Supplier Information

Retrieve information about a tour supplier/operator.

```bash
# Get supplier details
curl -X GET "https://api.getyourguide.com/1/suppliers/12345?cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Response
{
  "_metadata": { "status": "OK" },
  "data": {
    "supplier": [
      {
        "supplier_id": 12345,
        "name": "Paris Underground Tours",
        "description": "Expert guided tours of Paris underground attractions"
      }
    ]
  }
}
```

## Get API Configuration

Retrieve API configuration information including supported currencies, languages, and version compatibility.

```bash
# Get configuration for API version 1
curl -X GET "https://api.getyourguide.com/configuration/1?cnt_language=en&currency=EUR" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"

# Get payment configuration
curl -X GET "https://api.getyourguide.com/1/configuration/payment?cnt_language=en&currency=EUR&country=DE" \
  -H "X-ACCESS-TOKEN: YOUR_API_TOKEN" \
  -H "Accept: application/json"
```

## Image Formats

Tour images are returned with a placeholder `[format_id]` that can be replaced with specific format IDs for different sizes and quality levels.

```bash
# Original URL from API
https://cdn.getyourguide.com/img/tour/59cba8cb6b06c.jpeg/[format_id].jpg

# Replace [format_id] with desired format
# Format 131: 240x160px, 3:2 ratio, 80% quality (thumbnails)
https://cdn.getyourguide.com/img/tour/59cba8cb6b06c.jpeg/131.jpg

# Format 75: 1440x960px, 3:2 ratio, 40% quality (large display)
https://cdn.getyourguide.com/img/tour/59cba8cb6b06c.jpeg/75.jpg

# Format 21: 640x480px, 4:3 ratio, 90% quality (medium display)
https://cdn.getyourguide.com/img/tour/59cba8cb6b06c.jpeg/21.jpg

# Common format IDs:
# 131 - 240x160 (3:2) - Thumbnails
# 75  - 1440x960 (3:2) - Hero images
# 21  - 640x480 (4:3) - Medium quality
# 50  - 200x200 (1:1) - Square thumbnails
# 117 - 300x300 (1:1) - Square medium
```

## Generating API Clients

Generate typed API clients in 50+ languages using the OpenAPI specification with openapi-generator.

```bash
# Install openapi-generator CLI
npm install @openapitools/openapi-generator-cli -g

# Generate TypeScript client
npx @openapitools/openapi-generator-cli generate \
  -i spec/api.yaml \
  -g typescript-node \
  -o ./generated/typescript-client

# Generate Python client
npx @openapitools/openapi-generator-cli generate \
  -i spec/api.yaml \
  -g python \
  -o ./generated/python-client

# Generate Go client
npx @openapitools/openapi-generator-cli generate \
  -i spec/api.yaml \
  -g go \
  -o ./generated/go-client

# Generate Ruby client
npx @openapitools/openapi-generator-cli generate \
  -i spec/api.yaml \
  -g ruby \
  -o ./generated/ruby-client
```

## Summary

The GetYourGuide Partner API enables partners to build complete travel booking experiences by integrating with GetYourGuide's extensive marketplace. The typical integration flow involves: (1) searching for tours using the `/tours` endpoint with location, date, and filter parameters, (2) retrieving tour details and options with `/tours/{tour_id}`, (3) checking availability via `/tours/{tour_id}/availability`, (4) getting precise pricing from `/tours/{tour_id}/price-breakdown`, (5) creating bookings with `/bookings`, and (6) confirming payment through `/carts`. Partners can choose between redirecting customers to GetYourGuide's marketplace (simple integration) or handling the complete booking flow via API (advanced integration).

For production integrations, partners should implement proper error handling for rate limits (130 calls/minute), cache availability and pricing data appropriately while respecting the real-time nature of the API, and ensure all mandatory booking questions are collected from customers before submission. The API supports 37 display currencies and 10 payment currencies, with content available in 28 languages. Access tiers determine which endpoints are available: BASIC/LIMITED_READ for catalogue browsing, READ for availability and pricing, and BOOKING for complete transaction capabilities. Partners receive commissions on bookings through the attribution system built into the API URLs.