{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"version":"1.0","title":"Services API 2.0","x-hugo-values":{"tags":["api"],"categories":["Services","Healthcheck"],"public":true,"weight":70}},"paths":{"/{id}":{"get":{"tags":["Services"],"summary":"Retrieve Services List","description":"This endpoint will return a list of services for the given services_list_id.\nThe response will contain list of services that can be booked.","parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the Services-list","example":"e9e6c9ca-72fa-11e8-82da-0a580a2c041d","schema":{"type":"string"}},{"in":"query","name":"seats","description":"Minimum number of seats the vehicle should have available for passengers","schema":{"type":"integer"}},{"in":"query","name":"locale","description":"Get services based on locale","schema":{"type":"integer"}}],"responses":{"200":{"description":"The reqeust was successful. The response body will contain a list of services.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceResponse"}}}},"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":[]}]}},"/":{"post":{"tags":["Services"],"summary":"Request Services","description":"This endpoint will return a list of services offered in the chosen location. You can either request a trip for a future date-time or ASAP (by leaving the date-time blank).\nThe response will contain services list ID and empty services list. Retrieving available quotes may take some time and for this reason there is latency_budget parameter that allows to define how long it will take to retrieve valid quotes. The longer the budget the more accurate prices will be returned. If latency_budget is not provided, the response will contain services list ID and empty services list.\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/ServiceRequest"}}},"description":"Request body","required":true},"responses":{"201":{"description":"The reqeust was successful. The response body will contain a service_id which should be used when calling the booking endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceResponse"}}}},"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/services"}],"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.","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"}}},"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"}}},"ServiceItem":{"type":"object","required":["type"],"properties":{"id":{"type":"string","description":"A unique identifier for this specific service","example":"9361d590-7472-11e8-82da-0a580a2c041d:TAXI_ECO"},"type":{"type":"string","example":"TAXI_ECO"},"price":{"properties":{"currency_code":{"type":"string","example":"GBP"},"high":{"type":"integer","example":1500,"description":"High end of estimated price."},"low":{"type":"integer","example":1200,"description":"Low end of estimated price."},"display_price":{"type":"integer","example":1400}}},"qta":{"type":"object","required":["high_minutes","low_minutes"],"properties":{"display":{"type":"string","example":"2-5"},"high_minutes":{"type":"integer","example":5},"low_minutes":{"type":"integer","example":2}}},"seats":{"type":"string","example":"3-4"},"quote_type":{"type":"string","description":"Type of quote that can be found within service type:\n"},"status":{"type":"string","description":"The status of the specific service type:\n","enum":["available","waiting_for_response","no_availability","no_quotes_within_thresholds","blocked_by_partner_service_id"],"example":"available"}}},"ExpectedServiceItem":{"type":"object","required":["partner_service_type"],"description":"Object representing specific service requested by the Demand Partner. It can contain additional requirements such as expected price range.","properties":{"partner_service_type":{"type":"string","example":"TAXI","description":"Service type that the Demand partner expects offers for."},"partner_service_id":{"type":"string","example":"2sI1fX8pQTVH08ZqGSGaXQ==","description":"Id representing client context of the request. It's possible to alter service behaviour based on specific partner_service_id."},"description":{"type":"string","example":"Taxi, 4 seats.","description":"Any additional information describing specific service."},"price_low":{"type":"integer","format":"uint32","description":"Minimum service price accepted by the Demand Partner.","example":1800},"price_high":{"type":"integer","format":"uint32","description":"Maximum service price accepted by the Demand Partner.","example":2200},"currency_code":{"type":"string","example":"GBP"}}},"ServiceResponse":{"type":"object","required":["services"],"properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/ServiceItem"}},"services_list_id":{"type":"string","example":"e9e6c9ca-72fa-11e8-82da-0a580a2c041d"},"status":{"type":"string","description":"The status of the Service Request:\n","enum":["COMPLETED","PROGRESSING"],"example":"COMPLETED"}}},"ServiceRequest":{"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},"driving_time_minutes":{"type":"integer","format":"uint32","description":"Driving time in minutes.","example":35},"latency_budget":{"type":"integer","format":"uint32","description":"Time in milliseconds defining how long it will take to retrieve valid quotes.","example":3000},"seats":{"type":"integer","format":"uint32","description":"Minimum number of seats the vehicle should have available for passengers.","example":3},"services_list_id":{"type":"string","example":"e9e6c9ca-72fa-11e8-82da-0a580a2c041d"},"services":{"type":"array","description":"Array of demanded services. Leave empty to get a list of all available services for the chosen route.","items":{"$ref":"#/components/schemas/ExpectedServiceItem"}}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}