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 a date_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