{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"version":"v1.0","title":"Locations API 1.0","x-hugo-values":{"tags":["api"],"categories":["Addresses"],"public":true,"weight":60}},"paths":{"/address-autocomplete":{"post":{"tags":["Addresses"],"summary":"Address Autocomplete","description":"This endpoint returns a list of locations that match the provided search string. If latitude-longitude coordinates are provided, the results will be biased to that proximity. Once a location is selected from this list, a call to address-details will provide additional details (such as complete address).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationAutocompleteRequest"}}},"description":"request body","required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationAutocompleteResponse"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}},"security":[{"Bearer":[]}]}},"/address-details":{"post":{"tags":["Addresses"],"summary":"Address Details","description":"Get full details for a given location as defined by the Place ID. (Deprecated, used place-details instead)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationDetailsRequest"}}},"description":"request body","required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}},"security":[{"Bearer":[]}]}},"/place-details":{"post":{"tags":["Addresses"],"summary":"Place Details","description":"Get full details for a given place as defined by the Place ID with user session token support.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceDetailsRequest"}}},"description":"request body","required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}},"security":[{"Bearer":[]}]}},"/reverse-geocode":{"get":{"tags":["Addresses"],"summary":"Reverse geo-code","description":"Returns address details for a given latitude-longitude. The result may be a Point of Interest (POI), such as an airport or train station. In this case, the results will also show the details of the POI and any special meeting instructions (such as parking restrictions or Meet and Greet).","parameters":[{"name":"latitude","in":"query","required":true,"description":"The latitude in degrees. It must be in the range [-90.0, +90.0]","schema":{"type":"number","format":"double","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":true,"description":"The longitude in degrees. It must be in the range [-180.0, +180.0]","schema":{"type":"number","format":"double","minimum":-180,"maximum":180}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429RateLimit"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}},"security":[{"Bearer":[]}]}},"/healthcheck":{"get":{"tags":["Healthcheck"],"summary":"Check Services","responses":{"204":{"description":"Success response, no content. Service is ok"}}}}},"servers":[{"url":"https://rest.sandbox.karhoo.com/v1/locations"}],"components":{"responses":{"400InvalidInput":{"description":"Bad Request. The request was invalid.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0002","description":"Error number"},"message":{"type":"string","example":"Invalid request payload","description":"Details of the error"}}}}}},"401Unauthorized":{"description":"Unauthorized. The request requires user authentication (not logged in).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K6001","description":"Error number"},"message":{"type":"string","example":"Could not authenticate","description":"Details of the error"}}}}}},"403Forbidden":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request. Please request access by emailing [API Support](api@karhoo.com?subject=API%20Access%20Request).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0005","description":"Error number"},"message":{"type":"string","example":"Missing required role for this request","description":"Details of the error"}}}}}},"404NotFound":{"description":"Not found.  Booking not found, or following information is not available anymore.","content":{"*/*":{"schema":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error","example":"K4003"},"message":{"type":"string","description":"Details of the actual error","example":"Could not book trip (could not find specified quote)"}}}}}},"429RateLimit":{"description":"Error. Too Many Requests. Exceeded the rate limit for requests.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0006","description":"Error number"},"message":{"type":"string","example":"Rate limit exceeded","description":"Details of the error"}}}}}},"500InternalServerErr":{"description":"Internal server error. Something has gone wrong on the website's server, but the server could not be more specific on what the exact problem is.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0001","description":"Error number"},"message":{"type":"string","example":"General request error","description":"Details of the error"}}}}}},"502BadGateway":{"description":"Bad Gateway. The server, which was acting as a gateway or proxy, received an invalid response from the upstream server.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0000","description":"Error number"},"message":{"type":"string","example":"Bad Gateway error","description":"Details of the error"}}}}}}},"securitySchemes":{"Bearer":{"description":"For accessing the API a valid JWT token must be passed in all the queries in the 'Authorization' header.\nA valid JWT token is generated by the /v1/auth/token API.\nThe following syntax must be used in the 'Authorization' header :\n`Bearer: xxxxxx.yyyyyyy.zzzzzz`","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"Address":{"type":"object","description":"Specifies the address of a geographic location","required":["display_address","line_1","city"],"properties":{"display_address":{"type":"string","description":"An full address for the location","example":"Terminal 5, Wallis Rd, Longford, Hounslow TW6 2GA, UK"},"line_1":{"type":"string","description":"First line of the address","example":"Wallis Road"},"line_2":{"type":"string","description":"Second line of the address","example":"TW62GA"},"building_number":{"type":"string","description":"Building number","example":""},"street_name":{"type":"string","description":"Street name of the address","example":"Wallis Road"},"city":{"type":"string","description":"City of the address","example":"Longford"},"postal_code":{"type":"string","description":"Postal code","example":"TW62GA"},"postal_code_ext":{"type":"string","description":"Postal code extension","example":""},"region":{"type":"string","description":"Region","example":"England"},"country_code":{"type":"string","description":"Country code","example":"GB"}}},"AutoCompleteLocation":{"type":"object","description":"A geographic location","required":["place_id"],"properties":{"place_id":{"type":"string","description":"Unique Place ID","example":"ChIJ3QD47p1xdkgRytPI0DjT6SU"},"display_address":{"type":"string","description":"A human readable representation of the location","example":"Terminal 5, Longford, Hounslow, UK"},"type":{"$ref":"#/components/schemas/DetailsType"}}},"Details":{"type":"object","description":"Defines additional properties of a POI","properties":{"iata":{"type":"string","description":"if POI is an Airport this is its IATA code","example":"LHR"},"terminal":{"type":"string","example":5},"type":{"$ref":"#/components/schemas/DetailsType"}}},"DetailsType":{"type":"string","description":"A secondary POI type for more detailed categorization\n  - NOT_SET_DETAILS_TYPE\n  - AIRPORT\n  - TRAIN_STATION\n  - METRO_STATION\n  - PORT\n  - HOTEL\n  - OTHER\n","enum":["NOT_SET_DETAILS_TYPE","AIRPORT","TRAIN_STATION","METRO_STATION","PORT","HOTEL","OTHER"],"example":"AIRPORT"},"Error":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error"},"message":{"type":"string","description":"Details of the actual error"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}}},"ErrorDetails":{"type":"object","description":"Additional information about the error (such as which field failed validation)","properties":{"message":{"type":"string","description":"Summary of additional information"},"detail":{"type":"string","description":"Actual detail of the error"}}},"LatLong":{"type":"object","description":"Specifies a geographic location in terms of its Latitude and Longitude. For address autocompletion this location is used as bias to produce relevant Place IDs.","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","format":"double","maximum":90,"minimum":-90,"description":"The latitude in degrees. It must be in the range [-90.0, +90.0]","example":51.47},"longitude":{"format":"double","type":"number","maximum":180,"minimum":-180,"description":"The longitude in degrees. It must be in the range [-180.0, +180.0]","example":0.4543}}},"Location":{"type":"object","description":"A geographic location","required":["place_id"],"properties":{"position":{"$ref":"#/components/schemas/LatLong"},"place_id":{"type":"string","description":"Unique Place ID","example":"k_baadf8a7-7a1b-11e8-afe3-0a580a2c001b"},"poi_type":{"$ref":"#/components/schemas/POIType"},"address":{"$ref":"#/components/schemas/Address"},"time_zone":{"type":"string","description":"The timezone of the location","example":"Europe/London"},"current_local_time":{"type":"string","description":"The current local time at the location in RFC3339 format","example":"2018-06-28T11:44:00+01:00"},"details":{"$ref":"#/components/schemas/Details"},"meeting_point":{"$ref":"#/components/schemas/MeetingPoint"}}},"LocationAutocompleteRequest":{"type":"object","description":"Request for location-autocomplete; either query or position should be specified, but not both","required":["query"],"properties":{"query":{"type":"string","description":"The location search query","example":"Heathrow T5","minLength":1},"radius":{"type":"integer","format":"int32","minimum":1,"maximum":6371000,"description":"Radius in meters where search will be performed. if this parameter passed results will strictly restricted by circle with center defined in LatLong parameter","example":"50000"},"position":{"$ref":"#/components/schemas/LatLong"},"session_token":{"type":"string","description":"User session token to reduce api costs.","example":"73b5e655-d2c2-4ccb-b07d-22a0b097f24c"}}},"LocationAutocompleteResponse":{"type":"object","description":"Response for location-autocomplete","required":["locations"],"properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/AutoCompleteLocation"}}}},"LocationDetailsRequest":{"type":"object","description":"Request for location-details","required":["place_id"],"properties":{"place_id":{"type":"string","description":"Unique Place ID returned by the reverse-geocode or location-autocomplete endpoint.","example":"ChIJ3QD47p1xdkgRytPI0DjT6SU"}}},"PlaceDetailsRequest":{"type":"object","description":"Request for place-details","required":["place_id","session_token"],"properties":{"place_id":{"type":"string","description":"Unique Place ID returned by the reverse-geocode or location-autocomplete endpoint.","example":"ChIJ3QD47p1xdkgRytPI0DjT6SU"},"session_token":{"type":"string","description":"User session token to reduce api costs.","example":"73b5e655-d2c2-4ccb-b07d-22a0b097f24c"}}},"MeetingPoint":{"type":"object","description":"Specifies a geographic location in terms of its Latitude and Longitude","required":["position","type"],"properties":{"position":{"$ref":"#/components/schemas/LatLong"},"instructions":{"type":"string","description":"The meeting point instructions","example":"London Heathrow Airport, Terminal 5 Arrivals"},"type":{"$ref":"#/components/schemas/MeetingPointType"}}},"MeetingPointType":{"type":"string","description":"If being picked up at an Airport, the pickup type\n<ul>\n  <li>DEFAULT:  Standard driver behavior for pickup or dropoff</li>\n  <li>PICK_UP: This is a special pick up point for this location</li>\n  <li>DROP_OFF: This is a special dropoff up point for this location</li>\n  <li>MEET_AND_GREET: Usually when the driver will meet the passenger with a greeting sign</li>\n  <li>CURB_SIDE: The driver will wait curbside at a designated pickup point</li>\n  <li>STAND_BY: The passenger must call when they are ready. Usually with their luggage when an airport</li>\n</ul>\n","enum":["NOT_SET","DEFAULT","PICK_UP","DROP_OFF","MEET_AND_GREET","CURB_SIDE","STAND_BY"],"example":"DEFAULT"},"POIType":{"type":"string","description":"The type of Point of Interest: \n<ul>\n  <li>NOT_SET_POI_TYPE: Not specified</li>\n  <li>ENRICHED: Standard Karhoo POI Type that usually defines CURB_SIDE, MEET_AND_GREET or STAND_BY meeting points</li>\n  <li>REGULATED: POI usually defining restricted PICK_UP and DROP_OFF meeting points</li>\n  <li>NEAREST: POI usually defining recommended PICK_UP and DROP_OFF meeting points</li>\n</ul>\n","enum":["NOT_SET_POI_TYPE","ENRICHED","REGULATED","NEAREST"],"example":"ENRICHED"},"ReverseGeocodeRequestBody":{"type":"object","description":"The latitude and longitude to use in the reverse geocode lookup.","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","format":"double","description":"The latitude in degrees. It must be in the range [-90.0, +90.0]","example":51.5086692},"longitude":{"format":"double","type":"number","description":"The longitude in degrees. It must be in the range [-180.0, +180.0]","example":-0.1375291}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}