{"openapi":"3.0.0","info":{"description":"A Karhoo API for Points of Interest","version":"0.0.1","title":"Karhoo POI API","contact":{"email":"api@karhoo.com"},"x-hugo-values":{"tags":["api"],"categories":["poi"],"public":true,"weight":60}},"paths":{"/":{"get":{"tags":["poi"],"summary":"Get all Karhoo POIs","description":"Get all POIs. Note this does not return associated FPOIs.","operationId":"List POIs","parameters":[{"in":"query","name":"pagination_row_count","required":true,"description":"Number of POIs to return","schema":{"type":"number"}},{"in":"query","name":"pagination_offset","required":true,"description":"Number of POIs to skip","schema":{"type":"number"}},{"in":"query","name":"search_term","required":false,"description":"Allows searching in 'name', 'display_address' and 'city'. Requires at least 3 characters","schema":{"type":"string"}},{"in":"query","name":"search_key","required":false,"description":"Allows searching by additional reference key assigned to POI.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIList"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]},"post":{"tags":["poi"],"summary":"Create a new POI","description":"Creates a New POI identified by a Geo-JSON area","operationId":"Create POI","requestBody":{"$ref":"#/components/requestBodies/POI"},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POI"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]}},"/{id}":{"get":{"tags":["poi"],"summary":"Get the details of a POI","description":"Get the details for a POI","operationId":"Get POI","parameters":[{"in":"path","name":"id","description":"the id received from the create poi request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POI"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]},"put":{"tags":["poi"],"summary":"Update a POI by overwriting all of its elements","description":"Update the entire POI object","operationId":"Update POI","parameters":[{"in":"path","name":"id","description":"the id received from the create poi request","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/POI"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POI"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]},"delete":{"tags":["poi"],"summary":"Delete a POI","description":"Delete a POI","operationId":"deletePoi","parameters":[{"in":"path","name":"id","description":"the id received from the create poi request","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Successfully deleted, no response body"},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]}},"/{id}/fleet-poi":{"get":{"tags":["poi"],"summary":"Get the all the Fleet POIs associated with a Karhoo POI","description":"Get all Fleet POIs","operationId":"Get Fleet POI","parameters":[{"in":"path","name":"id","description":"the id received from the create poi request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIList"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]},"post":{"tags":["poi"],"summary":"Create a New Fleet POI","description":"Create a New Fleet POI under a Karhoo POI","operationId":"Create Fleet POI","parameters":[{"in":"path","name":"id","description":"the id received from the create poi request","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/POI"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POI"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]}},"/fleet-poi/{fid}":{"put":{"tags":["poi"],"summary":"Update a Fleet POI by overwriting all of its elements","description":"Update Fleet POI","operationId":"Update Fleet POI","parameters":[{"in":"path","name":"fid","description":"the fleet poi id received from the create fleet poi request","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/POI"},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POI"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]},"delete":{"tags":["poi"],"summary":"Delete a Fleet POI","description":"Delete a Fleet POI that resides under a POI","operationId":"Delete Fleet POI","parameters":[{"in":"path","name":"fid","description":"the fleet poi id received from the create fleet poi request","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Successfully deleted, no response body"},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]}},"/fleet/{fleet_id}":{"get":{"tags":["poi"],"summary":"Get Fleet POIs by Fleet ID","description":"Get all Fleet POIs belonging to a Fleet. Control pagination by providing 'pagination_row_count' and 'pagination_offset' values in the request.","operationId":"List Fleet POIs by Fleet ID","parameters":[{"in":"path","name":"fleet_id","description":"the id received from the create poi request","required":true,"schema":{"type":"string"}},{"in":"query","name":"pagination_offset","required":true,"schema":{"type":"number"}},{"in":"query","name":"pagination_row_count","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIList"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]}},"/poi/reverse-geocode":{"get":{"tags":["poi"],"summary":"Get the details of a POI","description":"Get the details for a POI. Note this does not return any associated fleet-defined POIs with any matches, which means some details such as external or fleet IDs are not returned; in order to obtain these for any given POI, use the GET /poi/{id}/fleet-poi endpoint","operationId":"Reverse Geocode","parameters":[{"name":"latitude","in":"query","description":"The latitude in degrees. It must be in the range [-90.0, +90.0]","required":true,"schema":{"type":"number","format":"double"}},{"name":"longitude","in":"query","description":"The longitude in degrees. It must be in the range [-180.0, +180.0]","required":true,"schema":{"type":"number","format":"double"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POIList"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]}},"/poi/validate/{id}":{"post":{"tags":["poi"],"summary":"Validate a KPOI","description":"For KPOIs to show up in the /reverse-geocode response they must be validated. By default KPOIs are invalid. You can only validate at a KPOI, validating a FPOI doesnt do anything","operationId":"Validate","parameters":[{"in":"path","name":"id","description":"the id received from the create poi request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POI"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized. Invalid credentials provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found. The specific Id was not found inside the system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"Bearer":[]}]}}},"servers":[{"url":"https://rest.karhoo.com/v1/poi"}],"components":{"requestBodies":{"POI":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/POI"}}},"description":"request body","required":true}},"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"],"properties":{"display_address":{"type":"string","description":"A human readable representation of the location. Is used to display location name and on autocomplete.","example":"Heathrow T5 (Arrivals)"},"line_1":{"type":"string"},"line_2":{"type":"string"},"building_number":{"type":"string"},"street_name":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"postal_code_ext":{"type":"string"},"region":{"type":"string"},"country_code":{"type":"string"}}},"DetailsType":{"type":"string","description":"A secondary POI type for more detailed categorization\n","example":"AIRPORT","enum":["UNSPECIFIED","AIRPORT","TRAIN_STATION","METRO_STATION","PORT","HOTEL","OTHER"]},"Details":{"type":"object","description":"Defines additional properties of a POI","properties":{"external_id":{"type":"string","description":"Fleet or DMS External ID for this POI"},"iata":{"type":"string","description":"if POI is an Airport this is its IATA code","example":"LHR"},"terminal":{"type":"string","example":5},"dispatch_id":{"type":"string","description":"the dispatch platform UUID for this POI"},"fleet_id":{"type":"string","description":"the fleet UUID for this POI"},"type":{"$ref":"#/components/schemas/DetailsType"}}},"MeetingPointType":{"type":"string","example":"MEET_AND_GREET","description":"If being picked up at an Airport, the pickup type\n\n `DEFAULT` - Standard driver behavior for pickup or dropoff. Maximum one DEFAULT POI is allowed\n\n `PICK_UP` - This is a special pick up point for this location\n\n `DROP_OFF` - This is a special dropoff up point for this location\n\n `MEET_AND_GREET` - Usually when the driver will meet the passenger with a greeting sign\n\n `CURB_SIDE` - The driver will wait curbside at a designated pickup point\n\n `STAND_BY` - The passenger must call when they are ready. Usually with their luggage when an airport\n","enum":["DEFAULT","PICK_UP","DROP_OFF","MEET_AND_GREET","CURB_SIDE","STAND_BY"]},"LatLng":{"type":"object","description":"Specifies a geographic location in terms of its Latitude and Longitude","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","format":"double","description":"The latitude in degrees. It must be in the range [-90.0, +90.0]","minimum":-90,"maximum":90,"example":51.5086692},"longitude":{"format":"double","type":"number","minimum":-180,"maximum":180,"description":"The longitude in degrees. It must be in the range [-180.0, +180.0]","example":-0.1375291}}},"MeetingPoint":{"type":"object","description":"Specifies a geographic location in terms of its Latitude and Longitude","required":["position","type"],"properties":{"id":{"type":"string","description":"UUID identifying meeting point"},"position":{"$ref":"#/components/schemas/LatLng"},"instructions":{"type":"string","description":"The meeting point instructions","maxLength":512},"type":{"$ref":"#/components/schemas/MeetingPointType"}}},"SearchKey":{"type":"string","description":"Additional references to a POI","example":"Great West Aerodrome"},"POI":{"type":"object","description":"A Poi identified by the Geo-JSON together with optional metadata such as address, airport","required":["address","geojson","name","position","meeting_points","details"],"properties":{"id":{"type":"string","description":"id of a POI","example":"k_1234567"},"type":{"$ref":"#/components/schemas/POIType"},"description":{"type":"string","description":"Internal use only. Should not be shown to end users."},"name":{"type":"string","description":"Internal use only. A human readable representation of the location.","example":"Heathrow T5 (Arrivals)"},"address":{"$ref":"#/components/schemas/Address"},"details":{"$ref":"#/components/schemas/Details"},"geojson":{"type":"string","format":"string","description":"A GeoJSON \"Feature\", encoded as a base64 string","example":"eyJ0eXBlIjoiRmVhdHVyZSIsInByb3BlcnRpZXMiOnt9LCJnZW9tZXRyeSI6eyJ0eXBlIjoiUG9seWdvbiIsImNvb3JkaW5hdGVzIjpbW1stMC4xMzI4NjU5MDU3NjE3MTg3NSw1MS41MTgzNTcxNTM4OTMxNF0sWy0wLjEzODcwMjM5MjU3ODEyNSw1MS41MDk0OTAzNDEyMDI3NV0sWy0wLjEyNDk2OTQ4MjQyMTg3NSw1MS40OTk2NjAwNTAwMTQ0MzRdLFstMC4xMTMyOTY1MDg3ODkwNjI0OSw1MS41MTY4NjE2Njc5NDA1OV0sWy0wLjEzMjg2NTkwNTc2MTcxODc1LDUxLjUxODM1NzE1Mzg5MzE0XV1dfX0="},"meeting_points":{"type":"array","items":{"$ref":"#/components/schemas/MeetingPoint"}},"position":{"$ref":"#/components/schemas/LatLng"},"is_valid":{"type":"boolean","description":"Determines wether or not a KPOI is valid or not. Only valid KPOIs will end up in the platform and returned in reverse-geocode"},"search_keys":{"type":"array","items":{"$ref":"#/components/schemas/SearchKey"}}}},"POIType":{"type":"string","example":"ENRICHED","description":"The type of Point of Interest\n\n`UNSET` - The POI type hasn't been set\n\n`ENRICHED` - Standard Karhoo POI Type that usually defines CURB_SIDE, MEET_AND_GREET or STAND_BY meeting points\n\n`REGULATED` - POI usually defining restricted PICK_UP and DROP_OFF meeting points\n\n`NEAREST` - POI usually defining recommended PICK_UP and DROP_OFF meeting points\n","enum":["UNSET","ENRICHED","REGULATED","NEAREST"]},"POIList":{"type":"object","description":"List of POIs","required":["pois"],"properties":{"pois":{"type":"array","items":{"$ref":"#/components/schemas/POI"}}}},"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"}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}