Get yourguide dataapi

  • 47 views
Uploaded on

 

More in: Technology , Business
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
47
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
2
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. cCopyright2013-GetYourGuideAG GetYourGuide Data API Version: 1.0-α (981fd26) Contact: partner@getyourguide.com 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
  • 2. cCopyright2013-GetYourGuideAG Contents 1 Introduction 1 1.1 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Access to the API 2 3 Search API 2 3.1 Quick Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 3.2 REST Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.2.1 Search Tours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2.2 Get a Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.2.3 Get the Options for a Tour . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.4 Get an Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.5 Get Pricing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2.6 Get the Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4 Search API Data Objects 7 4.1 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2 Tour Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.3 Tour Options Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.4 Tour Option Pricing Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.5 Tour Option Availability Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.6 Locations Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.7 Categories Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.8 FromPrice Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.9 Pictures Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5 Security Aspects 17 5.1 Bearer Token provisioning for Partners . . . . . . . . . . . . . . . . . . . . . . . . 17 A Image Size Codes 18 B Booking Return Codes 19 C Error Codes 19
  • 3. cCopyright2013-GetYourGuideAG List of Figures 1 The GYG Tour Options Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 1
  • 4. cCopyright2013-GetYourGuideAG List of Tables 1 Overview of Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 Quick Reference of available REST Interfaces . . . . . . . . . . . . . . . . . . . . 3 3 Parameters allowed for all Requests . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4 Parameters for the Search Tour Service . . . . . . . . . . . . . . . . . . . . . . . . 5 6 Parameters for the single tour service . . . . . . . . . . . . . . . . . . . . . . . . . 5 11 Parameters for the availability service . . . . . . . . . . . . . . . . . . . . . . . . 7 13 Tour Object Response Data Details . . . . . . . . . . . . . . . . . . . . . . . . . . 10 14 Tour Option Object Response Data Details . . . . . . . . . . . . . . . . . . . . . 12 15 Tour Option Price Object Response Data Details . . . . . . . . . . . . . . . . . . 13 16 Tour Option Availability Object Response Data Details . . . . . . . . . . . . . . 14 17 Locations Object Response Data Details . . . . . . . . . . . . . . . . . . . . . . . 15 18 Categories Object Response Data Details . . . . . . . . . . . . . . . . . . . . . . 16 19 FromPrice Object Response Data Details . . . . . . . . . . . . . . . . . . . . . . 16 20 Pictures Object Response Data Details . . . . . . . . . . . . . . . . . . . . . . . . 17 24 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
  • 5. cCopyright2013-GetYourGuideAG Listings 1 Response Header for successful requests . . . . . . . . . . . . . . . . . . . . . . . 8 2 Response Header for unsuccessful requests . . . . . . . . . . . . . . . . . . . . . . 8 3 Tour Object with Format Option full . . . . . . . . . . . . . . . . . . . . . . . . . 8 4 Tour Object with Format Option teaser . . . . . . . . . . . . . . . . . . . . . . . 9 5 Tour Option Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6 Tour Option Pricing Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 7 Tour Option Availability Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 8 Locations Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 9 Categories Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 10 FromPrice Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 11 Pictures Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
  • 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 GetYourGuide’s 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 offering. 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&param2=value). Name Description Type Mand. Default Value / Notes access_token The identifier token String yes fields Define which fields the response should contain List of Strings no offset offset 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 defined 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 offered 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 field 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 predefined 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 offers 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 specific 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 effect on this request. 3.2.3 Get the Options for a Tour /tours/:tour_id/options GET Get data for a specific tour option Additional Parameters: no parameters Responses: Description HTTP Code Content OK 200 List of Options Objects Notes: Parameters offset and limit have no effect on this request. 3.2.4 Get an Option /options/:option_id GET Get data for a specific 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 effect on this request. 3.2.5 Get Pricing /options/:option_id/pricings GET Get the pricing for a specific 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 specific 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 different objects as described in the following sections. Listing 1: Response Header for successful requests 1 { 2 "_metadata": { 3 "descriptor": "GetYourGuide AG", 4 "apiVersion": <int >, 5 "method": <String >, 6 "status": "OK", 7 "totalCount": <int >, 8 "offset": <int >, 9 "limit": <int >, 10 "date": <TIMESTAMP >, 11 "query": <String > 12 } 13 "data": <Data Object > 14 } The field totalCount gives the size of the result set, if offset and limit would not have been applied. The field query gives the original parameters submitted with the request in the URI. The field 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": <int > 4 "method": <String >, 5 "status": "ERROR", 6 "errorCode": <int >, 7 "errorMessage": <String > 8 "helpURL":"api.getyourguide.com/docu /" 9 } Error codes are specified 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
  • 14. cCopyright2013-GetYourGuideAG GetYourGuide Data API 4 "tour_id": <integer >, 5 "cond_language": list <string >, 6 "title": <string >, 7 "abstract": <string >, 8 "description": <string >, 9 " additional_information ": <string:optional >, 10 "bestseller": <bool >, 11 "overall_rating": <float >, 12 " number_of_ratings ": <int >, 13 "highlights": [ 14 <string > 15 ... 16 ], 17 "inclusions": <string:optional >, 18 "exclusions": <string:optional >, 19 "pictures": <Pictures Object >, 20 "coordinates":[{ 21 "lat": <string >, 22 "long": <string >, 23 ]}, 24 "price": <FromPrice Object >, 25 "categories": <Category Object >, 26 "locations": <Location Object, 27 "url": <string >, 28 } 29 { ... } // multiple tours 30 ] 31 } Listing 4 details the Tour Object in formatting option teaser. Listing 4: Tour Object with Format Option teaser 1 { 2 "tours":[ 3 { 4 "tour_id": <integer >, 5 "cond_language": list <string >, 6 "title": <string >, 7 "abstract": <string >, 8 "overall_rating": <float >, 9 " number_of_ratings ": <int >, 10 "pictures": <Pictures Object >, 11 "coordinates":[{ 12 "lat": <string >, 13 "long": <string > 14 ]}, 15 "price": <FromPrice Object >, 16 "categories": <Category Object >, 17 "locations": <Location Object, 18 "url": <string >, 19 } 20 { ... } // multiple tours 21 ] 22 } 9
  • 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": <int >, 5 "title": <string >, 6 "description": <string:optional >, 7 "pick_up": <string:optional >, 8 "meeting_point": <string:optional >, 9 "drop_off": <string:optional >, 10 "duration": <int >, 11 "duration_unit ": <enum:[’day ’,’hour ’,’minute ’]>, 12 "cond_languages ":[ 13 <language_type >:[<iso_code >,<iso_code >, ...], 14 ... 15 ], 16 " booking_parameter ":[ 17 { 18 "name": <string > 19 } 20 { ... } multiple parameters 21 ], 22 "private_flag": <boolean >, 23 " coordinate_type ": <String >, // exact, approximate 24 "coordinates":[{ 25 "lat": <string >, 26 "long": <string >, 27 ]}, 28 "price": <FromPrice Object >, 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-off/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 field (day, hour, minute) String cond_languages A List of Objects specifying possible languages for different 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 specific 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 flag 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 flag specifies whether or not the meeting_point information on the option is an exact location or not. It defines 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": <int >, 5 "categories": [{ 6 "id": <int >, 7 "name": <string >, 8 "min_age": <int: optional >, 9 "max_age": <int: optional >, 10 "stand_alone": <boolean >, 11 "addon": <boolean: optional >, 12 "scale": [{ 13 " min_participants ": <int >, 14 " max_participants ": <int >, 15 "retail_price": <float >, 16 "net_price": <float >, 12
  • 18. cCopyright2013-GetYourGuideAG GetYourGuide Data API 17 "type": <enum: flat, pax >, 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 define 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 different 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 don’t 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 specific request methods. There could be 1 to n locations. Listing 8: Locations Object 1 { 2 "locations":[ 3 { 4 "location_id":<integer >, 5 "type": <string >, // ENUM: AREA, CITY, POI 6 "name":<string >, 7 "country":<string >, 8 "coordinates": [{ 9 "long":<string >, 10 "lat":<string >, 11 }], 12 "parent": <int >, 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":<integer >, 5 "name":<string >, 6 "parent": <int > 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": <double >, 5 "special" <optional >: [{ 6 "original_price": <float >, 7 "savings": <float > 8 }], 9 }, 10 "description": <string > 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 Offer 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": <integer >, 5 "description": <string > 6 "url": <string >, 7 "ssl_url": <string >, 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 file name of the String. The URL can be gen- erated for different 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 defined 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 first_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 first_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