1. cCopyright2013-GetYourGuideAG GetYourGuide Data API Version:
1.0- (981fd26) Contact: [email protected] Date: April 26,
2013 Copyright GetYourGuide AG. All rights reserved. Information in
this document is subject to change without notice. No part of this
document may be used, reproduced or transmitted in any form or by
any means unless authorised by GetYourGuide AG through a written
licence agreement. Further, this document does not grant any rights
to, or in, the products mentioned therein and no rights of any kind
relating to such products will be granted except pursuant to
written agreements with GetYourGuide AG. GetYourGuide AG
Technoparkstrasse 1, CH-8005 Zurich, Switzerland
6. cCopyright2013-GetYourGuideAG GetYourGuide Data API 1
Introduction This Document describes the GetYourGuide (GYG)
Application Programming Interface (API), denoted GYG-API. The API
intends to make the GetYourGuide data catalog available to part-
ners in a programmatic way. 1.1 Data Model GetYourGuides object
model is called the Tour Option model. The basic idea is to have a
lightweight basis entity called Tour representing the products
GetYourGuide AG is oering. This basis entity is then enriched with
one or more so-called Tour Options. A Tour Option is a bookable
entity for a Tour containing all the attributes that typically
express the diversity of tours and activities. This includes the
possibility that each Tour Option may have its own pricing and
availabilities, see Figure 1. Figure. 1: The GYG Tour Options Data
Model 1.2 Data Types 1
7. cCopyright2013-GetYourGuideAG GetYourGuide Data API Field
Data Type Date UTC Timestamp ISO 8601 YYYY-MM-DDTHH:MM:SS Integer
Native Data Type Float Native Data Type String Native Data Type
Bool Native Data Type true or false Table 1: Overview of Data Types
All requests are expected to be encoded in UTF-8. Responses are
encoded in UTF-8. 2 Access to the API The GetYourGuide API is a
RESTful interface, accessed via HTTPS, i.e., TLS encryption is
required. The URI of the API is as follows:
https://api.getyourguide.com/[api_version]/ where [api_version] is
an integer representing the version of the API. Prerequesites 1.
the URI parameter access_token is mandatory. Requests that do not
contain a valid access token are rejected (i.e., HTTP 401 -
Unauthorized). 2. the API is hosted via HTTPS on port 443 3. the
HTTP Header Accept: application/json has to be set As a result, an
example call to the API would look as follows: 1 c url H "Accept :
a p p l i c a t i o n / json " 2 X GET https :// api . getyourguide
. com/1/ tours /7483? access_token=AKEY 3 Search API 3.1 Quick
Reference Description HTTP Method URL Pattern State
gyg_tours_by_query GET /tours C gyg_tours_by_tour_id GET
/tours/:tour_id C Continued on next page 2
8. cCopyright2013-GetYourGuideAG GetYourGuide Data API Table 2
continued from previous page Description HTTP Method URL Pattern
State gyg_options_by_tour_id GET /tours/:tour_id/options C
gyg_options GET /options/:option_id C gyg_options_pricing GET
/options/:option_id/pricing C gyg_options_availability GET
/options/:option_id/availability C gyg_locations GET /locations P
gyg_location_tours GET /locations/:location_id/tours P
gyg_location_categories GET /locations/:location_id/categories P
gyg_location_category _tours GET
/locations/:location_id/categories/ :category_id/tours P Table 2:
Quick Reference of available REST Interfaces where C . . . Commited
to be delivered in Version 1 P . . . Commited to be delivered in
Version 2 3.2 REST Requests The following parameters are allowed
for all requests, unless stated otherwise, and are expected to be
submitted in the URI (i.e., URI?param1=value¶m2=value).
Name Description Type Mand. Default Value / Notes access_token The
identier token String yes fields Dene which elds the response
should contain List of Strings no offset oset the result list
Integer no 0 limit limit the number of result rows in the response
Integer no 10 cnt_language the language of the texts in the
response String yes Expected Value: ISO 639-1 2 Letter Language
Code currency the currency of prices in re- sponses String yes
Expects: 3 letter currency codes as dened in ISO 4217 suppress
_response_codes Developer Parameter to sup- press HTTP Error Codes
BOOL no some Apps have problems with non-HTTP-200 response codes.
Table 3: Parameters allowed for all Requests 3
9. cCopyright2013-GetYourGuideAG GetYourGuide Data API 3.2.1
Search Tours /tours/ GET Get a list of tours according to a query
Additional Parameters: Name Description Type Mand. Default Value /
Notes q Query String String no if no q is set then: returns the
best 3 Tours date check for tours that are oered on date or between
date_from and date_to Date no no default Single Value: exact date
Otherwise: [from, to] cond_language the conduction language of a
tour. When given, the re- sults contain only tours that are
available in this language. String no no default Expected Value:
ISO 639-1 2 Letter Language Code price Filter for price in the
query List of Float no no default Single Value: max.price
Otherwise: [min, max] max = 0 . . . unlimited categories Filter for
categories List of int no no default rating Filter for ratings List
of Int no no default Filter for Tours with the given ratings
duration Filter for min and/or max dura- tion in minutes List of
int no no default Single Value: max. duration Otherwise: [min, max]
coordinates long, lat, radius List of Float no no default location
GYG annotation for Locations List of int no no default flags
Possible values are (multiple selection allowed): private ,
wheelchair , skip-line , pick-up , special List of String no no
default sortfield According to which eld should the resultset be
sorted. Possible values are: price , rating , duration , popularity
String no popularity sortdirection ASC, DESC String no DESC
Continued on next page 4
10. cCopyright2013-GetYourGuideAG GetYourGuide Data API Table 4
continued from previous page Name Description Type Mand. Default
Value / Notes preformatted Respond with a special for- mat for the
tours found by the search String no default is teaser Possible
Values: 1) teaser 2) full if the given value does not cor- respond
to any predened op- tion, the standard response is generated. Table
4: Parameters for the Search Tour Service where the values for
flags have the following meaning: private . . . Private Tour. The
Lead Traveler (and his/her group) is the only participant.
wheelchair . . . Tour is accessible with a wheelchair skip-line . .
. allows to skip any queues pick-up . . . Hotel pick-up possible
special . . . Special oers only Responses: Description HTTP Code
Content OK 200 List of Tours Objects 3.2.2 Get a Tour
/tours/:tour_id GET Get data for a specic tour Additional
Parameters: Name Description Type Mand. Default Value / Notes
preformatted Respond with a special format for this tour String no
default is teaser Possible Values: 1) teaser 2) full Table 6:
Parameters for the single tour service 5
11. cCopyright2013-GetYourGuideAG GetYourGuide Data API
Responses: Description HTTP Code Content OK 200 Tours Objects
Notes: Parameters offset and limit have no eect on this request.
3.2.3 Get the Options for a Tour /tours/:tour_id/options GET Get
data for a specic tour option Additional Parameters: no parameters
Responses: Description HTTP Code Content OK 200 List of Options
Objects Notes: Parameters offset and limit have no eect on this
request. 3.2.4 Get an Option /options/:option_id GET Get data for a
specic options Additional Parameters: no parameters Responses:
Description HTTP Code Content OK 200 Options Objects 6
12. cCopyright2013-GetYourGuideAG GetYourGuide Data API Notes:
Parameters offset and limit have no eect on this request. 3.2.5 Get
Pricing /options/:option_id/pricings GET Get the pricing for a
specic option Additional Parameters: no parameters Responses:
Description HTTP Code Content OK 200 Pricing Object 3.2.6 Get the
Availability /options/:option_id/availabilities GET Get the
availabilities for a specic op- tion Additional Parameters: Name
Description Type Mand. Default Value / Notes date check the
availability for this option and the time between date_from and
date_to String no default: [today, today+30days] Single Value:
exact date Otherwise: [from, to] Table 11: Parameters for the
availability service Responses: Description HTTP Code Content OK
200 Availability Object 4 Search API Data Objects The output format
is JSON in UTF-8 encoding. 7
13. cCopyright2013-GetYourGuideAG GetYourGuide Data API 4.1
Response The response contains information about the current API
version, status of the request (with an optional error message if
the call was not successful), name of API method and the requested
data itself. Depending on the request, the data can have dierent
objects as described in the following sections. Listing 1: Response
Header for successful requests 1 { 2 "_metadata": { 3 "descriptor":
"GetYourGuide AG", 4 "apiVersion": , 5 "method": , 6 "status":
"OK", 7 "totalCount": , 8 "offset": , 9 "limit": , 10 "date": , 11
"query": 12 } 13 "data": 14 } The eld totalCount gives the size of
the result set, if offset and limit would not have been applied.
The eld query gives the original parameters submitted with the
request in the URI. The eld data contains the data objects, as
described in the following Sections. If the API call is not
successful, the response contains an additional error code
information: Listing 2: Response Header for unsuccessful requests 1
{ 2 "descriptor": "GetYourGuide AG", 3 "apiVersion": 4 "method": ,
5 "status": "ERROR", 6 "errorCode": , 7 "errorMessage": 8
"helpURL":"api.getyourguide.com/docu /" 9 } Error codes are specied
in the appendix. 4.2 Tour Object The tour object contains all the
information about the tour itself. The Tour Object comes in a
number of formatting options. The base for these options is the
Format Option full , as described in Listing 3. Other formatting
options contain a subset of the information provided in the full
option. Listing 3: Tour Object with Format Option full 1 { 2
"tours":[ 3 { 8
15. cCopyright2013-GetYourGuideAG GetYourGuide Data API Note
that with the Teaser Format Option, the following Objects contain
only a single entry, i.e., the prime result for the corresponding
Object: pictures categories locations JSON Data Field Description
Type / Data Structure avail. in Format tour_id Tour ID Integer all
cond_language The available Conduction Languages List of Strings,
ISO 639-1 2 Letter Lan- guage Codes all title Tour Title String all
abstract Short Description of Tour String all description Long
Description of Tour String full additional_information Additional
Information for the Cus- tomer String full bestseller full
overall_rating The overall rating of the tour (across all options)
Float all number_of_ratings The number of ratings for this tour
Integer all highlights A List of notable properties List of Strings
0 .. n full inclusions What is included in the tour? String full
exclusions What is not included in the tour? String full pictures A
List of Pictures List of Objects 0 .. n Teaser: 1 Object all
coordinates.lat Approximate location of the tour Float all
coordinates.long Approximate location of the tour Float all price
The From Price, i.e., the cheapest Adult Fare among all Options
within the next year. FromPrice Object all categories List of
Categories ordered according to importance. List of Objects 0 .. n
Teaser: 1 Object all locations List of Locations ordered according
to importance. List of Objects 1 .. n Teaser: 1 Object all url The
URL of that tour on the GetYour- Guide Website. String all Table
13: Tour Object Response Data Details 10
16. cCopyright2013-GetYourGuideAG GetYourGuide Data API 4.3
Tour Options Object For every option that matches the API input
parameters, we provide the following data. Listing 5: Tour Option
Object 1 { 2 "tour_options":[ 3 { 4 "option_id": , 5 "title": , 6
"description": , 7 "pick_up": , 8 "meeting_point": , 9 "drop_off":
, 10 "duration": , 11 "duration_unit ": , 12 "cond_languages ":[ 13
:[,, ...], 14 ... 15 ], 16 " booking_parameter ":[ 17 { 18 "name":
19 } 20 { ... } multiple parameters 21 ], 22 "private_flag": , 23 "
coordinate_type ": , // exact, approximate 24 "coordinates":[{ 25
"lat": , 26 "long": , 27 ]}, 28 "price": , 29 } 30 { ... } //
multiple options 31 ] JSON Data Field Description Type / Data
Structure option_id Option ID, used (required) for booking
Approximate Integer title Option Title String description
Description String pick_up Information about the hotel pickup
possibilities String meeting_point Information about the
drop-o/where the tour ends String drop_off Information about where
to meet for the tour option String duration Integer duration_unit
The Unit of the duration eld (day, hour, minute) String
cond_languages A List of Objects specifying possible languages for
dierent types of information. List of Objects 3 Objects Continued
on next page 11
17. cCopyright2013-GetYourGuideAG GetYourGuide Data API Table
14 continued from previous page JSON Data Field Description Type /
Data Structure language.type Either: language_audio - Audio Guide
& Headphones language_booklet - Information Booklet
language_live - Live tour guide String language.language List of
available languages for a specic type of infor- mation List of
Strings 1 . . . n booking_parameter. name Information required for
the Booking API. language : Customer has to select language, since
it is required for the booking API. hotel : Hotel for pick-up.
Customer has to specify the hotel. comment : Customer Comment
String private_flag if the ag is set, the tour closes with a single
book- ing. The customer will be on the tour without other guests,
except those he included in the booking. Bool coordinate_type this
ag species whether or not the meeting_point information on the
option is an exact location or not. It denes if the information is
exact enough for the customer to walk/get there. String
coordinates.lat Coordinate of the meeting point, the latitude Float
coordinates.long Coordinate of the meeting point, the longitude
Float price The From Price, i.e., the cheapest Adult Fare among all
Options within the next year (default) or the given time period.
FromPrice Object Table 14: Tour Option Object Response Data Details
4.4 Tour Option Pricing Object Listing 6: Tour Option Pricing
Object 1 { 2 "pricing":[ 3 { 4 "pricing_id": , 5 "categories": [{ 6
"id": , 7 "name": , 8 "min_age": , 9 "max_age": , 10 "stand_alone":
, 11 "addon": , 12 "scale": [{ 13 " min_participants ": , 14 "
max_participants ": , 15 "retail_price": , 16 "net_price": ,
12
18. cCopyright2013-GetYourGuideAG GetYourGuide Data API 17
"type": , 18 } 19 { ... } // multiple scales 20 ] 21 } 22 { ... }
// multiple categories 23 ] 24 } 25 { ... } // multiple pricing_ids
26 ] JSON Data Field Description Type / Data Structure pricing
Object containing pricing information pricing_id categories List of
Category Objects. categories.id categories.name categories.min_age
The minimum age for that category. If 0, no restric- tion.
categories.max_age The maximum age for that category. If 0, no
restric- tion. categories.stand_alone Can this category be booked
alone (e.g., Category "Kids" might not be bookable alone)
categories.addon Is this category for an Addon? e.g., Helmets etc.
optional. false if not present categories.scale. min_participants
GYG pricing schema allows to dene prices depending on the number of
persons in the booking. "Scales" specify the minimum and maximum
number of participants for which a price schema can be used.
min_praticipants and max_participants of dierent items in the scale
list never overlap. categories.scale. max_participants
categories.scale. retail_price Suggested Retail Price in the
requested currency categories.scale. net_price The net price that
GYG is charging for this tour categories.scale.type Is this price
to be considered as a per Person price (pax) or as a price per
group (flat). See Calculation Examples in the Appendix. Table 15:
Tour Option Price Object Response Data Details 4.5 Tour Option
Availability Object To reduce the data size we dont use named keys
in this object. So the order of the attributes is relevant. 13
19. cCopyright2013-GetYourGuideAG GetYourGuide Data API Listing
7: Tour Option Availability Object 1 { 2 "availabilities":[ 3 [
start_time, pricing_id, available_seats , discount, end_time:
optional ] 4 [ ... ] // multiple entries 5 ] 6 } JSON Data Field
Description Type / Data Structure availabilities List of
Availability Objects List of Objects 0 . . . n availabilities.
start_time Start Time and Date in local time. Format:
YYYY-MM-DDTHH:mm:ss String availabilities. pricing_id The price id
for this particular availability Integer availabilities.
available_seats Number of seats that are available Integer
availabilities. discount If the starting time is eligible for a
deal, specify the discount on the retail_price of the corresponding
pricing_id Float availabilities. end_time Optional response
parameter. End Time of a Tour - only given in case of opening
hours. Format: YYYY-MM-DDTHH:mm:ss Note: for Booking API set
HH:mm:ss to 00:00:00. Table 16: Tour Option Availability Object
Response Data Details 4.6 Locations Object The location object is
only present for specic request methods. There could be 1 to n
locations. Listing 8: Locations Object 1 { 2 "locations":[ 3 { 4
"location_id":, 5 "type": , // ENUM: AREA, CITY, POI 6 "name":, 7
"country":, 8 "coordinates": [{ 9 "long":, 10 "lat":, 11 }], 12
"parent": , 13 } 14
20. cCopyright2013-GetYourGuideAG GetYourGuide Data API 14 {
... } // multiple locations 15 ] 16 } JSON Data Field Description
Type / Data Structure locations List of Locations List of Objects 0
. . . n locations.location_id The id of the location. This is the
root location. Integer locations.name Name of the location String
locations.country The country of the location ISO 3166-1 2 Letter
Code String locations.type The type of root location type in this
Object. Could be either: 1 - AREA 2 - CITY 3 - POI open for
extension String locations.coordinates. long Longitude and Latitude
in Signed Degrees format (DDD.dddd) (e.g., 90.0 and 0.0 for the
North Pole) Float locations.coordinates. lat Float locations.parent
The id of the parent location. There are the following relations:
Location Type possible Parent Type: POI City ID POI Area ID City ID
Area ID Area ID no parent (null) Integer Table 17: Locations Object
Response Data Details 4.7 Categories Object Listing 9: Categories
Object 1 { 2 "categories":[ 3 { 4 "category_id":, 5 "name":, 6
"parent": 7 } 8 { ... } // multiple categories 9 ] 10 } 15
21. cCopyright2013-GetYourGuideAG GetYourGuide Data API JSON
Data Field Description Type / Data Structure categories List of
Categories List of Objects 0 . . . n categories.category_id The ID
of the Category Integer categories.name The Name of the Category
String categories.parent The ID of the parent category Integer
Table 18: Categories Object Response Data Details 4.8 FromPrice
Object Listing 10: FromPrice Object 1 { 2 "price":{ 3 "values":[{ 4
"amount": , 5 "special" : [{ 6 "original_price": , 7 "savings": 8
}], 9 }, 10 "description": 11 }] JSON Data Field Description Type /
Data Structure values Inline Object values.amount Price of the
adult fare of the cheapest option in the requested currency. Float
values.special If this inline object exists, then this is a Special
Oer Inline Object, op- tional values.special. original_price the
regular price for this option in the requested cur- rency. Float
values.special.savings saving between regular price and special
price, in per- cent [%] discount in percent. description additional
information about the pricing. For example "per Group" or "per
Person" or "per Group up to 10 people". Table 19: FromPrice Object
Response Data Details 4.9 Pictures Object 16
22. cCopyright2013-GetYourGuideAG GetYourGuide Data API Listing
11: Pictures Object 1 { 2 "pictures":[ 3 { 4 "id": , 5
"description": 6 "url": , 7 "ssl_url": , 8 } 9 { ... } multiple
pictures 10 ] 11 } JSON Data Field Description Type / Data
Structure pictures A List of Pictures List of Objects 0 . . . n
pictures.id Integer pictures.description Text String pictures.url
The le name of the String. The URL can be gen- erated for dierent
Picture sizes and qualities, as de- scribed in Appendix A String
pictures.ssl_url The base URL of the Image for usage with HTTPS.
The base URL needs to be enriched with sizing in- formation to
retrieve an actual image - see Appendix A. String Table 20:
Pictures Object Response Data Details 5 Security Aspects The
GetYourGuide API (GYG-API) implements the "bearer token" approach
as dened in the OAuth 2.0 Authorization Framework, see RFC 6750.
The token is named access_token and is mandatory for any request
that is sent to the API. Failing to present the bearer token will
result in a HTTP 401 Response. In addition, each request is
required to be sent using TLS, ie., HTTPS. 5.1 Bearer Token
provisioning for Partners Consumers of the API receive a Bearer
Token from GetYourGuide. Consumers of the API can request a new
Token. In this case, GetYourGuide will invalidate the old token
after an appropriate period of time. 17
23. cCopyright2013-GetYourGuideAG GetYourGuide Data API A Image
Size Codes ID width height crop 1 80 80 1 2 100 100 1 3 50 50 1 4
280 0 0 5 150 0 0 6 200 140 1 7 70 70 1 8 55 55 1 9 240 0 0 10 150
150 1 11 80 80 0 12 150 150 0 13 55 55 0 14 120 120 1 15 60 60 1 16
85 85 1 17 260 0 0 18 86 86 1 19 130 130 1 20 30 30 1 21 640 480 0
22 28 28 1 23 0 70 0 24 2500 2500 0 ID width height crop 25 185 133
1 26 190 90 1 27 115 74 1 28 175 114 1 29 173 73 1 30 192 81 1 31
150 70 1 32 80 55 1 33 102 65 1 34 266 186 1 35 96 60 1 36 150 100
1 37 100 75 1 38 320 210 1 39 580 300 1 40 880 320 1 41 200 160 1
42 284 177 1 46 200 150 1 45 132 110 1 44 66 55 1 43 568 354 1 47
220 93 1 48 584 320 1 Based on this list, an image can be retrieved
by accessing the following URL:
http://img.getyourguide.com/img/tour_img-[picture_id]-[format_id].jpg
or for SSL:
https://www.getyourguide.com/https/tour_img.php?id=[picture_id]&format_id=[format_id]
where [picture_id] . . . The id of the picture, as given in the
picture object. [format_id] . . . The desired format of the
picture, as stated in the table above. 18
24. cCopyright2013-GetYourGuideAG GetYourGuide Data API B
Booking Return Codes ID height 1 . . . successful 2 . . . failed:
invalid tour 3 . . . failed: invalid date 4 . . . failed: required
category missing 5 . . . failed: price mismatch 6 . . . failed:
required parameter missing 7 . . . failed: no vacancies left 50 . .
. failed: billing salutation_id invalid 51 . . . failed: billing
rst_name invalid 52 . . . failed: billing name invalid 53 . . .
failed: billing email invalid 54 . . . failed: billing street
invalid 55 . . . failed: billing city invalid 56 . . . failed:
billing postal code invalid 57 . . . failed: billing country id
invalid 58 . . . failed: billing phone number invalid 59 . . .
failed: billing company name invalid 60 . . . failed: traveler
salutation_id invalid 61 . . . failed: traveler rst_name invalid 62
. . . failed: traveler name invalid 63 . . . failed: traveler email
invalid 64 . . . failed: traveler phone invalid 97 . . . failed:
payment could not be executed 98 . . . failed: failure due to
failure of other booking 99 . . . failed: unknown error C Error
Codes 19
25. cCopyright2013-GetYourGuideAG GetYourGuide Data API Code
Description 400 Bad Request. We cannot process the request for some
reason. 401 Unauthorized. The access_token is missing. 403
Forbidden. Even with access_token, this resource is not available.
404 Page does not exist 405 Method is not allowed on Resource.
(e.g., HTTP DELETE on Tour) 500 Server Error. Put the Server Error
Message in the Response 301 Resource moved permanently. (e.g., the
API moved to another URL) Table 24: Error Codes 20