{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"version":"1.0","title":"Quotes API 2.0","x-hugo-values":{"tags":["api"],"categories":["Quotes","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).\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/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":[]}]}},"/{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":"e9e6c9ca-72fa-11e8-82da-0a580a2c041d","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":[]}]}},"/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/v2/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":{"Destination":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"string","pattern":"^-?\\d{1,2}\\.\\d{4,}$","description":"The latitude in degrees. It must be in the range [-90.0, +90.0], with at least 4 decimal digits of precision.","example":"51.501364"},"longitude":{"type":"string","pattern":"^-?\\d{1,3}\\.\\d{4,}$","description":"The longitude in degrees. It must be in the range [-180.0, +180.0], with at least 4 decimal digits of precision.","example":"-0.14189"},"display_address":{"maxLength":255,"type":"string","description":"Descriptive name of the address pointed by `latitude` and `longitude`.","example":"Buckingham Palace, London SW1A 1AA"}}},"Fleet":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","example":"385468a9-98fb-4267-a6c8-e324dee13714"},"name":{"type":"string","example":"Karhoo Cabs"},"description":{"type":"string","example":"This fleet offers great discounts in the evening"},"rating":{"$ref":"#/components/schemas/FleetRating"},"logo_url":{"type":"string","example":"https://karhoo.com/logo/cab.png"},"terms_conditions_url":{"type":"string","description":"URL to get the fleet terms-and-conditions from","example":"https://karhoo.com/terms/"},"phone_number":{"type":"string","example":"+44123456789"}}},"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","destination"],"properties":{"origin":{"$ref":"#/components/schemas/Origin"},"destination":{"$ref":"#/components/schemas/Destination"},"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":"2020-06-23T09:04"}}},"Origin":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"string","pattern":"^-?\\d{1,2}\\.\\d{4,}$","description":"The latitude in degrees. It must be in the range [-90.0, +90.0], with at least 4 decimal digits of precision.","example":"51.5054564"},"longitude":{"type":"string","pattern":"^-?\\d{1,3}\\.\\d{4,}$","description":"The longitude in degrees. It must be in the range [-180.0, +180.0], with at least 4 decimal digits of precision.","example":"-0.0775452"},"display_address":{"type":"string","maxLength":255,"description":"Descriptive name of the address pointed by `latitude` and `longitude`.","example":"Tower Bridge Rd, London SE1 2UP"}}},"Price":{"type":"object","properties":{"currency_code":{"type":"string","example":"GBP"},"high":{"type":"integer","example":1500,"description":"High end of estimated price. `high` will be equal to `low` for fixed quotes"},"low":{"type":"integer","example":1500,"description":"Low end of estimated price. `high` will be equal to `low` for fixed quotes"},"net":{"type":"object","properties":{"high":{"type":"integer","example":1350,"description":"High end of estimated price before tax"},"low":{"type":"integer","example":900,"description":"Low end of estimated price before tax"}}}}},"PickUpType":{"type":"string","description":"The pick up type\n\n","enum":["DEFAULT","STAND_BY","CURB_SIDE","MEET_AND_GREET"],"example":"MEET_AND_GREET"},"QuoteItem":{"type":"object","required":["id","price","quote_type","fleet"],"properties":{"id":{"type":"string","description":"A unique identifier for this specific quote","example":"9361d590-7472-11e8-82da-0a580a2c041d:NDgyOWY0MjctZmI4MC00OWQxLWFlZDUtY2U5ZmFiNGI1MjM1O3RheGk="},"price":{"$ref":"#/components/schemas/Price"},"pick_up_type":{"$ref":"#/components/schemas/PickUpType"},"quote_type":{"type":"string","description":"Type of quote:\n"},"source":{"$ref":"#/components/schemas/QuoteSource"},"fleet":{"$ref":"#/components/schemas/Fleet"},"vehicle":{"$ref":"#/components/schemas/Vehicle"}}},"QuoteRequestState":{"type":"string","description":"The status of the Quote Request:\n","example":"COMPLETED"},"QuoteResponse":{"type":"object","required":["id","status","quotes","availability"],"properties":{"id":{"type":"string","description":"The Karhoo generated Quote Request ID","example":"79316201-f007-451e-8af3-350b3c628214"},"availability":{"$ref":"#/components/schemas/Availability"},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/QuoteItem"}},"status":{"$ref":"#/components/schemas/QuoteRequestState"},"validity":{"type":"integer","description":"Validity of this quote request, in seconds (-1 means it has expired)"}}},"Availability":{"type":"object","properties":{"vehicles":{"type":"object","properties":{"classes":{"type":"array","items":{"type":"string"},"example":["Saloon","MVP","Taxi"]}}}}},"QuoteSource":{"type":"string","description":"The source of the quote\n\n","enum":["FLEET","MARKET"],"example":"FLEET"},"Vehicle":{"type":"object","required":["class"],"properties":{"qta":{"type":"object","required":["high_minutes","low_minutes"],"properties":{"high_minutes":{"type":"integer","example":5},"low_minutes":{"type":"integer","example":2}}},"class":{"type":"string","description":"","example":"Saloon"},"passenger_capacity":{"type":"number","format":"int32","example":3},"luggage_capacity":{"type":"number","format":"int32","example":2}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}