Try Live
Add Docs
Rankings
Pricing
Enterprise
Docs
Install
Install
Docs
Pricing
Enterprise
More...
More...
Try Live
Rankings
Add Docs
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
Context
Skills
Chat
Benchmark
82.5
Suggestions
Latest
Show doc for...
Code
Info
Show Results
Context Summary (auto-generated)
Raw
Copy
Link
# 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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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¤cy=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.