{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"version":"1.0","title":"Quotes API 1.0","x-hugo-values":{"tags":["api"],"categories":["Quotes","Availability","Healthcheck"],"public":true,"weight":70}},"paths":{"/":{"post":{"tags":["Quotes"],"summary":"Request Quotes","description":"This endpoint will return a list of quotes by the fleets who serve the location. You can either request a trip for a future date-time or ASAP (by leaving the date-time blank). You can also, optionally, specify the number of passengers and luggage.\nThe response will contain a quote list `id` and a `validity` period in seconds (presently the defaults for ASAP and prebooks are 300 and 600 seconds, respectively).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewQuoteRequest"}}},"description":"Request body","required":true},"responses":{"201":{"description":"The request was successful. The backend server will begin to collate quotes from the fleets who operate in the specified area. The response body will contain an `id` which can be used when calling the quotes/{id} endpoint, to retrieve these quotes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewQuoteResponse"}}}},"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":[]}]}},"/{id}":{"get":{"tags":["Quotes"],"summary":"Retrieve Quote List","description":"Get the trip quotes for the given ID.\nThe response payload will contain a list of quotes that is asynchronously populated. It will be updated with additional records as more responses are received from our fleet partners. This should happen reasonably quickly but demand partners may have constraints on their side that cause delays. So you should poll for updates for the longest period that your service performance allows.\nYou could keep polling while the status is “Progressing”. After 30 seconds the status will change to “Complete”, and the quote list items will no longer be updated. The status of “Complete” might occur before 30 seconds, if the Karhoo system has received a quote from all available fleets in the area.\nEach line in the quote list will contain features of the quoted vehicle. Such as the class of vehicle and its capacity (maximum number of passengers and luggage). So, if you want a feature or minimum capacity you will need to filter this list.","parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the Quote-list","example":"1c5d8791dd22064a","schema":{"type":"string"}},{"in":"query","name":"passengers","description":"Filter out vehicles incapable of carrying this number of passengers","schema":{"type":"integer"}}],"responses":{"200":{"description":"The request was successful. The backend service has recognised the `id` as a valid identifier. The response will contain the currently available quotes from the fleets. It will also contain a `status` field which shows whether the quotes are still being populated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"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":[]}]}},"/verify/{quote_id}":{"get":{"tags":["Quotes"],"summary":"Verify quote price with DMS before booking","description":"Verify a predicted quote with the fleet. This endpoint should only be used for exceptional situations and usage will be restricted. ","parameters":[{"name":"quote_id","in":"path","required":true,"description":"The ID of the quote to verify","example":"c8c070b3-696d-11ea-89b1-422da9542425:1c5d8791dd22064a","schema":{"type":"string"}}],"responses":{"200":{"description":"The request was successful. The backend service has recognised the `id` as a valid identifier. The response will contain the updated quote from the fleet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteItem"}}}},"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":[]}]}},"/availability":{"post":{"tags":["Availability"],"summary":"Check Availability","description":"Returns a list of available vehicles for a specified trip.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityRequest"}}},"description":"request body","required":true},"responses":{"201":{"description":"Successful request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"}}}},"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","description":"This allows you to monitor the health and performance of the Auth API.","responses":{"204":{"description":"Success response, no content. Service is ok"}}}}},"servers":[{"url":"https://rest.sandbox.karhoo.com/v1/quotes"}],"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. No availability in the requested area. There might not be any fleet coverage in the specified area. You can check the availability in the area by calling the quotes/availability endpoint. It could also indicate no vehicles available matching your passenger or luggage requirements; in which case, try getting quotes for two or more vehicles.","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":"K3002"},"message":{"type":"string","description":"Details of the actual error","example":"Could not get estimates (no availability found within requested area)"}}}}}},"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":"To access all endpoints in this API a valid Bearer Token must be passed in the 'Authorization' header.\nA Bearer Token is generated by the /v1/auth/token API.\n
The following syntax must be used in the 'Authorization' header :\n`Bearer: xxxxxx.yyyyyyy.zzzzzz`","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"Availability":{"type":"object","properties":{"availability_id":{"type":"string","description":"Unique identifier for this availability item. It is a Base64 encoding of the fleet_id and the category.","example":"Mzg1NDY4YTktOThmYi00MjY3LWE2YzgtZTMyNGRlZTEzNzE0O3NhbG9vbg=="},"fleet_id":{"type":"string","description":"Global Unique Identifier (GUID) for the fleet.","example":"385468a9-98fb-4267-a6c8-e324dee13714"},"vehicle_class":{"$ref":"#/components/schemas/VehicleClass"},"supplier_name":{"type":"string","description":"Business name of the fleet","example":"Karhoo Cabs"},"logo_url":{"type":"string","description":"URL for the logo of the fleet","example":"https://karhoo.com/logo/cab.png"},"description":{"type":"string","description":"Description of the fleet","example":""},"phone_number":{"type":"string","description":"Phone number for the fleet operator.","example":"+44123456789"},"rating":{"type":"number","format":"float","example":0},"terms_conditions_url":{"type":"string","description":"URL to get the fleet terms-and-conditions from","example":"https://karhoo.com/"},"category_name":{"type":"string","example":"Taxi"},"integrated_fleet":{"type":"boolean","example":true}}},"AvailabilityRequest":{"type":"object","required":["origin_place_id"],"properties":{"origin_place_id":{"type":"string","description":"Internal place identifier for a location of pickup. You can find the id for a place using the location endpoints.","example":"EhpCcm93bmVsbCBTdCwgU2hlZmZpZWxkLCBVSw","minLength":1,"maxLength":255,"pattern":"^[a-zA-Z0-9-_]*$"},"destination_place_id":{"type":"string","description":"Internal identifier for a location of destination. Note that the destination_place_id should be different from the origin_place_id","example":"EhdUaGUgTW9vciwgU2hlZmZpZWxkLCBVSw","minLength":1,"maxLength":255,"pattern":"^[a-zA-Z0-9-_]*$"},"date_required":{"type":"string","description":"Date/time of the required pickup (in YYYY-MM-DDTHH:MM format). You can leave this empty for an immediate trip. Please note that this is UTC time. If you want the local time you will need to convert it to the timezone of the pickup point.","example":"2019-01-31T15:04"}}},"AvailabilityResponse":{"type":"object","properties":{"availabilities":{"type":"array","description":"A list of available fleets in the requested area","items":{"$ref":"#/components/schemas/Availability"}},"categories":{"type":"array","description":"A list of available vehicle-categories in the requested area","items":{"type":"string"}}}},"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"}}},"FleetRating":{"type":"object","description":"Fleet weighted rating calculated by trip reviews","properties":{"count":{"type":"integer","description":"Number of single reviews","format":"int32"},"score":{"type":"integer","description":"Weighted fleet rating","format":"int32"}}},"NewQuoteRequest":{"type":"object","required":["origin_place_id","destination_place_id"],"properties":{"origin_place_id":{"type":"string","description":"Internal place identifier for a location of pickup. You can find the id for a place using the location endpoints.","example":"EhpCcm93bmVsbCBTdCwgU2hlZmZpZWxkLCBVSw","minLength":1,"maxLength":255,"pattern":"^[a-zA-Z0-9-_]*$"},"destination_place_id":{"type":"string","description":"Internal identifier for a location of destination. Note that the destination_place_id should be different from the origin_place_id","example":"EhdUaGUgTW9vciwgU2hlZmZpZWxkLCBVSw","minLength":1,"maxLength":255,"pattern":"^[a-zA-Z0-9-_]*$"},"local_time_of_pickup":{"type":"string","description":"Date/time of the required pickup (in YYYY-MM-DDTHH:MM format). You can leave this empty for an immediate trip.","example":"2019-01-31T15:04"}}},"NewQuoteResponse":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"The Karhoo generated Quote Request ID","example":"e9e6c9ca-72fa-11e8-82da-0a580a2c041d"},"status":{"$ref":"#/components/schemas/QuoteRequestState"},"quote_items":{"type":"array","items":{"$ref":"#/components/schemas/QuoteItem"}},"validity":{"type":"integer","description":"Validity of this quote request, in seconds (-1 means it has expired)","example":299}}},"PickUpType":{"type":"string","description":"The pick up type\n\n","enum":["DEFAULT","STAND_BY","CURB_SIDE","MEET_AND_GREET"],"example":"MEET_AND_GREET"},"QuoteSource":{"type":"string","description":"The source of the quote\n\n","enum":["FLEET","MARKET"],"example":"FLEET"},"QuoteItem":{"type":"object","required":["fleet_name","quote_type","quote_id"],"properties":{"quote_id":{"type":"string","description":"A unique identifier for this specific quote","example":"9361d590-7472-11e8-82da-0a580a2c041d:NDgyOWY0MjctZmI4MC00OWQxLWFlZDUtY2U5ZmFiNGI1MjM1O3RheGk="},"fleet_id":{"type":"string","example":"385468a9-98fb-4267-a6c8-e324dee13714"},"fleet_description":{"type":"string","example":"This fleet offers great discounts in the evening"},"availability_id":{"type":"string","example":"ABC123DEF"},"fleet_name":{"type":"string","example":"Karhoo Cabs"},"phone_number":{"type":"string","example":"+44123456789"},"pick_up_type":{"$ref":"#/components/schemas/PickUpType"},"supplier_logo_url":{"type":"string","example":"https://karhoo.com/logo/cab.png"},"vehicle_class":{"type":"string","example":"mpv"},"quote_type":{"type":"string","description":"Type of quote:\n"},"high_price":{"type":"integer","example":850,"description":"High end of estimated price. high_price will be equal to low_price for fixed quotes"},"low_price":{"type":"integer","example":850,"description":"Low end of estimated price. high_price will be equal to low_price for fixed quotes"},"currency_code":{"type":"string","example":"GBP"},"qta_high_minutes":{"type":"integer","example":4},"qta_low_minutes":{"type":"integer","example":4},"terms_conditions_url":{"type":"string","description":"URL to get the fleet terms-and-conditions from","example":"https://karhoo.com/terms/"},"category_name":{"type":"string","example":"MPV"},"vehicle_attributes":{"$ref":"#/components/schemas/VehicleAttributes"},"source":{"$ref":"#/components/schemas/QuoteSource"},"fleet_rating":{"$ref":"#/components/schemas/FleetRating"}}},"QuoteRequestState":{"type":"string","description":"The status of the Quote Request:\n","example":"COMPLETED"},"QuoteResponse":{"type":"object","required":["id","status","quote_items"],"properties":{"id":{"type":"string","description":"The Karhoo generated Quote Request ID","example":"12ABC55"},"status":{"$ref":"#/components/schemas/QuoteRequestState"},"quote_items":{"type":"array","items":{"$ref":"#/components/schemas/QuoteItem"}},"validity":{"type":"integer","description":"Validity of this quote request, in seconds (-1 means it has expired)"}}},"VehicleAttributes":{"type":"object","description":"A list of attributes a vehicle can have","properties":{"passenger_capacity":{"type":"number","format":"int32","example":3},"luggage_capacity":{"type":"number","format":"int32","example":2},"hybrid":{"type":"boolean","example":false},"electric":{"type":"boolean","example":true},"child_seat":{"type":"boolean"}}},"VehicleClass":{"type":"string","description":"The classification of a vehicle. Used for getting quotes or availabilities:\n","example":"Taxi"}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}