Quotes
Quote requests
Endpoint: POST https://supply-partner.com/quote
Quote requests fall in to one of two categories. those intended for a date in the future and those that require a ride ASAP (As soon as possible). We distinguish these two types of requests through the date_scheduled
parameter. Any requests that includes a date_scheduled
value is intended as a pre-book quote request. Otherwise it should be treated as an ASAP booking.
Don't support ASAP bookings?
If you do not support ASAP bookings (all booking must be pre-booked) then you should return a
400
response as described in the API documentation for any request that does not contain adate_scheduled
value.
Here is the most commonly used properties of our quote request.
{
"origin": {
"position": {
"latitude": 51.5086692,
"longitude": -0.1375291
},
},
"destination": {
"position": {
"latitude": 40.7587711,
"longitude": -73.9952016
},
}
}
Additional request parameters
Above is the minimal possible quotes request. It doesn’t contain information about vehicle type or fleet id, it doesn’t contain information about booking date (so it means that we request ASAP trip) and doesn’t contain address information (except for lat/long).
What are additional properties we also send?
- External information about vehicle type and fleet id (i.e. vehicle type name and fleet id in your system). We do it if you need fleet id and\or vehicle type to be provided in order to return quotes in specific area.
"external_info": {
"fleet_id": "f9dcd72d-640d-4124-ae0d-8f54262a152b",
"vehicle_type": "R4"
}
- We also send more details about origin or destination if we properly recognized it: address, building number and street name, city and state. We can also provide a meeting point info and position there which is useful when calculating price if available and possible:
"origin": {
"position": {
"latitude": 51.5086692,
"longitude": -0.1375291
},
"address": {
"display_address": "407 W 42nd St New York, NY, 10036",
"building_number": "407",
"street_name": "W 42nd St",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country_code": "US"
},
"meeting_point": {
"position": {
"latitude": 51.5086692,
"longitude": -0.1375291
},
"instructions": "string"
}
}
- Scheduled date. If your API supports pre-booked trip we provide you scheduled date as part of our quote request (format: RFC3339). Absence of the value means the request is ASAP (immediate):
"date_scheduled": "2016-04-21T21:57:48Z"
Quote Batching
Karhoo has three different quote batching options:
- Per DMS;
- Per fleet;
- Per vehicle type.
"Per DMS" is useful when DMS has information about all the fleets which use this software. In this case Karhoo sends a single request and expect to receive quote price for all fleets and all vehicle types in response (see below).
"Per fleet" is useful when DMS doesn't have information about vehicles and quotes among fleets which use their software. In this scenario Karhoo sends a single HTTP request to the fleet API and asks quotes for all available vehicle types. In this case we expect to receive an array with quotes for different vehicle types, for example:
{
"quotes": [
{
"external_info": {
"vehicle_type": "R1",
"fleet_id": "1234-1234-1234"
},
"quote": {
"currency": "USD",
"total": 72660
}
},
{
"external_info": {
"vehicle_type": "R4",
"fleet_id": "1234-1234-1234"
},
"quote": {
"currency": "USD",
"total": 50000
}
}
]
}
In this example DMS returns two vehicle types (R1 and R2) with different prices.
While we prefer to make a single request for all fleets and vehicle types available, if needed Karhoo can request per specific vehicle type. In this scenario fleet_id
and vehicle_type
will be present in the request within the external_info
object.
Be careful with "Per Vehicle" configuration option
Keep in mind that when you choose this option we send you a separate HTTP request per each vehicle type you have. This increases amount of requests to your API. For example, if fleet has five different vehicle types, Karhoo sends x5 more requests to their API comparing to "Per Fleet" batching option.
Quote batching is a platform configuration option that can be discussed more by contacting the Karhoo team.
Full Example
{
"external_info": {
"fleet_id": "f9dcd72d-640d-4124-ae0d-8f54262a152b",
"vehicle_type": "R4"
},
"origin": {
"position": {
"latitude": 51.5086692,
"longitude": -0.1375291
},
"address": {
"display_address": "407 W 42nd St New York, NY, 10036",
"building_number": "407",
"street_name": "W 42nd St",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country_code": "US"
}
},
"destination": {
"position": {
"latitude": 40.7587711,
"longitude": -73.9952016
},
"address": {
"display_address": "407 W 42nd St New York, NY, 10036",
"building_number": "407",
"street_name": "W 42nd St",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country_code": "US"
}
},
"date_scheduled": "2016-04-21T21:57:48Z"
}
Minimal acceptable quotes response
We expect that the Supply partner returns us an object which contains a list of quotes objects. Each object must contain:
- Partner fleet id
- Partner vehicle type
- Fare value
- Fare currency
{
"quotes": [
{
"external_info": {
"vehicle_type": "R4",
"fleet_id": "1234-1234-1234"
},
"quote": {
"currency": "USD",
"total": 72660
}
}
]
}
Zero Values
Quote with a value of zero (which have total = 0) won’t be shown.
Additional response parameters
You can add more properties under the external_info object: driver_id
, fare_id
, fleet_phone_number
and vehicle_id
. This external_info
field represents supply partner values, so here you provide your internal IDs and such. More information is available in the Supply API swagger definition.
Also information about vehicle might be specified via vehicle property:
"vehicle": {
"description": "Red BMW 5-Series", // Color, Make and Model of the vehicle
"direction": {
"heading":10.2, // degrees clockwise from due north
"kph":15.6
},
"driver": {
"first_name":"John",
"last_name":"",
"license_number":"l1c3",
"phone_number":"+14155552671", // E.164 formatted phone
"photo_content":"", // Driver photo encoded as bas64 string. The image should have a 1:1 aspect ratio and can be a gif, jpg or png.
"photo_url":"" // same format as above: 1:1 gif, jpg, png.
},
"eta":{
"distance":100, // in meters
"minutes":1 // estimated time of arrival in minutes
},
"position": {
"latitude": 50.124534,
"longitude": -12.5234
},
"state": 0, // 0 - not set, 1 - available, 2 - n/a
"vehicle_registration": "AB1234" // The legal registration of the vehicle
}
Driver Phone Number
The Driver object requires the
phone_number
field to be set in order to be accepted\updated.
ETA
If you specified eta object inside the vehicle of the quotes response, we can use this value instead of calling for ETA\Availability (See ETA & Availability section for more details).
Empty Quotes Response
In some cases the fleet doesn’t have any quotes in the specific area (for example - there are no available drivers for ASAP bookings). This is an absolutely normal scenario so we don’t expect any error in the response. The best option is to return an empty quotes array:
{
"quotes": []
}
Availability or ETA for ASAP Bookings
To display quotes for ASAP rides we need to know how far away the driver from the passenger. We have a few ways of working:
- You provide us driver ETA information as part of the quote object (see vehicle -> ETA above).
- You implement a separate endpoint
/eta
which expose information about vehicles ETAs (described below) - You implement a separate endpoint
/availability
which exposes information about vehicles positions (described below). In that case Karhoo does distance and time calculation for you. - You use Karhoo Supply API to push information about available vehicles. In this case Karhoo does distance and time calculation for you.
You need to implement only one of these. If you push availability using Supply API or send ETA as part of the quotes response you can skip this section and move on to implementing the trip endpoints.
ETA Endpoint
We expect that supply partners return a list of ETAs for requested origin.
Here is the request object for ETA, which is the same as for quotes:
{
"external_info": {
"fleet_id": "f9dcd72d-640d-4124-ae0d-8f54262a152b",
"vehicle_type": "R4" // just an example - give us your types
},
"origin": {
"position": {
"latitude": 51.5086692,
"longitude": -0.1375291
},
"address": {
"display_address": "407 W 42nd St New York, NY, 10036",
"building_number": "407",
"street_name": "W 42nd St",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country_code": "US"
}
},
"destination": {
"position": {
"latitude": 40.7587711,
"longitude": -73.9952016
},
"address": {
"display_address": "407 W 42nd St New York, NY, 10036",
"building_number": "407",
"street_name": "W 42nd St",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country_code": "US"
}
},
}
Each response object must contain:
- Partner fleet id
- Partner vehicle type
- ETA distance
- ETA minutes
Here is the minimal acceptable response:
{
"etas":[
{
"eta":{
"distance":100 // in meters
"minutes":1
}
"external_info":{
"fleet_id":"string"
"vehicle_type":"string"
}
}
]
}
Availability endpoint
We expect that supply partners return a list of vehicles closest to the requested origin.
Here is the full Availability request object we'll send to you, which is the same as for quotes.
{
"external_info": {
"fleet_id": "f9dcd72d-640d-4124-ae0d-8f54262a152b",
"vehicle_type": "R4" // just an example - give us your types
},
"origin": {
"position": {
"latitude": 51.5086692,
"longitude": -0.1375291
},
"address": {
"display_address": "407 W 42nd St New York, NY, 10036",
"building_number": "407",
"street_name": "W 42nd St",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country_code": "US"
}
},
"destination": {
"position": {
"latitude": 40.7587711,
"longitude": -73.9952016
},
"address": {
"display_address": "407 W 42nd St New York, NY, 10036",
"building_number": "407",
"street_name": "W 42nd St",
"city": "New York",
"region": "NY",
"postal_code": "10036",
"country_code": "US"
}
},
}
Each response object must contain:
- Partner fleet id
- Partner vehicle type
- Vehicle position
Here is the minimal acceptable response:
{
"vehicles":[
{
"position":{
"latitude":40.7587711,
"longitude":-73.9952016
}
"external_info":{
"fleet_id":"string",
"vehicle_type":"string"
}
}
]
}
Alternative Push Endpoint
Another way to provide availability is to implement a push to Karhoo's hosted Availability Endpoint. This should be pushed every 30 seconds or more where you would like to provide ASAP coverage.
Reference
Service | API reference | Errors reference |
---|---|---|
Quotes | [DMS Endpoint] Quote Request |
Updated 12 months ago