{"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), this list must be polled via the separate `retrieve quotes list` endpoint to receive a complete list of quotes.\nPlease note that whilst the `display_address` field is marked optional, we strongly recommend providing this where possible to help ensure the best level of service.","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":[]}]}},"/test":{"post":{"tags":["Quotes"],"summary":"Request Quotes","description":"This endpoint will return a list of quotes by the fleets (limited to this fleets who matched requested fleet_id) 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), this list must be polled via the separate `retrieve quotes list` endpoint to receive a complete list of quotes.\nPlease note that whilst the `display_address` field is marked optional, we strongly recommend providing this where possible to help ensure the best level of service.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestQuoteRequest"}}},"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 type of vehicle and its capacity (maximum number of passengers and luggage) and other properties like whether it's electric or wheelchair accessible listed as tags. 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":[]}]}},"/coverage":{"get":{"tags":["Coverage"],"summary":"Check Coverage","description":"Use this API endpoint to check the coverage of fleets available to you. This will only check the fleets service area, you must use /quotes to see which fleets have vehicles that are available to book.","parameters":[{"name":"latitude","in":"query","required":true,"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","schema":{"type":"string","pattern":"^-?\\d{1,2}\\.\\d{4,}$"}},{"name":"longitude","in":"query","required":true,"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","schema":{"type":"string","pattern":"^-?\\d{1,3}\\.\\d{4,}$"}},{"name":"local_time_of_pickup","in":"query","required":false,"description":"Date/time of the required pickup (in YYYY-MM-DDTHH:MM format). You can leave this empty for an immediate availability.","example":"2020-06-23T09:04","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageResponse"}}}},"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/coverage 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":300,"type":"string","description":"Descriptive name of the address pointed by `latitude` and `longitude`. This can greatly assist suppliers in determining the drop-off point.","example":"Buckingham Palace, London SW1A 1AA"}}},"Fleet":{"type":"object","required":["id","name","capabilities"],"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"},"capabilities":{"type":"array","items":{"type":"string"},"description":"A set of capabilities supported by a fleet:\n\nThe list might be extended in future.\n","example":["gps_tracking","vehicle_details"]}}},"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"},"driving_distance_metres":{"type":"integer","format":"uint32","description":"Driving distance in metres between origin and destination.","example":"1000"}}},"TestQuoteRequest":{"allOf":[{"$ref":"#/components/schemas/NewQuoteRequest"},{"type":"object","required":["fleet_id"],"properties":{"fleet_id":{"type":"string","description":"The fleet ID to be used for the test request","example":"385468a9-98fb-4267-a6c8-e324dee13714"},"dfa_id":{"type":"string","description":"dynamic fleet account ID","example":"123456"}}}]},"CoverageResponse":{"type":"object","properties":{"coverage":{"type":"boolean","description":"Returns `false` if no fleets are available for quotes. When `true` then request quotes to see which fleets are available.","example":true,"x-omitempty":false}}},"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":300,"description":"Descriptive name of the address pointed by `latitude` and `longitude`. This can greatly assist suppliers with locating passengers.","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"},"service_level_agreements":{"$ref":"#/components/schemas/SLASummary"},"metadata":{"type":"object","description":"Additional information about the quote","example":{"key":"value"}}}},"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"},"internal_quotes_list_id":{"type":"string","description":"The internal quotes list 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"]},"tags":{"type":"array","items":{"type":"string"},"example":["child-seat","hybrid","electric"]},"types":{"type":"array","items":{"type":"string"},"example":["standard","mpv","bus"]}}}}},"QuoteSource":{"type":"string","description":"The source of the quote\n\n","enum":["FLEET","MARKET"],"example":"FLEET"},"Vehicle":{"type":"object","required":["class","type","tags"],"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":"This property is deprecated and intended to be used by legacy implementations only.\nFor new implementations please use type/tags properties instead\n(see [our changelog](https://developer.karhoo.com/changelog/introducing-vehicle-type-tags) for details).\n\n","example":"Saloon"},"type":{"type":"string","description":"Represents the physical description of a vehicle. Next to passenger capacity and luggage capacity\ndetails overall capacity transit capabilities.\n\n","example":"standard"},"passenger_capacity":{"type":"number","format":"int32","example":3},"luggage_capacity":{"type":"number","format":"int32","example":2},"tags":{"type":"array","description":"A set of vehicle's attributes: The list may be extended in future.\n","example":["electric"],"items":{"type":"string"}},"vehicle_list":{"type":"array","x-omitempty":true,"description":"List of vehicles make and model (feature is still under development and available only for specific users)","example":["Mercedes E Class","BMW 5 Series","Audi A7"],"items":{"type":"string"}},"image":{"type":"string","description":"URL of the vehicle's image (feature is still under development and available only for specific users)","example":"https://cdn.karhoo.com/s/images/shared/exec_saloon.jpg"}}},"SLASummary":{"type":"object","description":"Service level agreement information for the quote","properties":{"free_cancellation":{"$ref":"#/components/schemas/FreeCancellationInformation"},"free_waiting_time":{"$ref":"#/components/schemas/FreeWaitingTime"}}},"FreeCancellationInformation":{"type":"object","description":"Information about the free cancellation policy. If the\n\"type\" is set to TimeBeforePickup then minutes field\nwill contain information about the free cancellation period.\nThe cancellation will be free up till X minutes before the\nscheduled arrival for the pre booked trips and X minutes after\nmaking a booking for ASAP trips\n\nIf the type is set to BeforeDriverEnRoute, then the cancellation\nis free until the driver is en route to the pickup point.\n","required":["type"],"properties":{"type":{"type":"string","enum":["TimeBeforePickup","BeforeDriverEnRoute"]},"minutes":{"type":"integer","minimum":0}}},"FreeWaitingTime":{"type":"object","required":["minutes"],"description":"Information about the free waiting time included in the fare","properties":{"minutes":{"type":"integer","minimum":0}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}