Ride Hailing

Ride Hailing Protocol

The communication protocol for ride hailing describes the format of a request for a ride (also referred to as need) sent by a user, and the response (bid) sent by vehicle, driver, or car owner.

For example, a user might search for a ride together with her pet dog, within a radius of 3 km of the given coordinates to a destination 2 km away.

Need

curl "discovery_endpoint_here" \
  --data "{ \
    \"pickup_at\": \"1513005534000\", \
    \"pickup_latitude\": \"32.787793\", \
    \"pickup_longitude\": \"-79.935005\", \
    \"destination_latitude\": \"32.7693531\", \
    \"destination_longitude\": \"-79.9296352\", \
    \"radius\": \"3000\", \
    \"additional_features\": \"pet_transport\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    pickup_at: '1513005534000',
    pickup_latitude: '32.787793',
    pickup_longitude: '-79.935005',
    destination_latitude: '32.7693531',
    destination_longitude: '-79.9296352',
    radius: '3000',
    additional_features: 'pet_transport',
  }),
});

import requests
payload = {
    "pickup_at": "1513005534000",
    "pickup_latitude": "32.787793",
    "pickup_longitude": "-79.935005",
    "destination_latitude": "32.7693531",
    "destination_longitude": "-79.9296352",
    "radius": "3000",
    "additional_features": "pet_transport",
  }
requests.post("discovery_endpoint_here", data=payload)

In response, an autonomous vehicle might send back a bid with a price for the ride, the vehicle type and model, and the estimated time of arrival.

Bid

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"20000000000000000,20000000000000000\", \
    \"price_type\": \"km,flat\", \
    \"price_description\": \"Price per km,City tax\", \
    \"current_latitude\": \"32.785889\", \
    \"current_longitude\": \"-79.935569\", \
    \"pickup_at\": \"1513005534000\", \
    \"vehicle_type\": \"suv\", \
    \"vehicle_manufacturer\": \"Luxor\", \
    \"vehicle_model\": \"Suave\", \
    \"vehicle_color\": \"Sapphire\", \
    \"vehicle_license_number\": \"92 321 87\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '20000000000000000,20000000000000000',
    price_type: 'km,flat',
    price_description: 'Price per km,City tax',
    current_latitude: '32.785889',
    current_longitude: '-79.935569',
    pickup_at: '1513005534000',
    vehicle_type: 'suv',
    vehicle_manufacturer: 'Luxor',
    vehicle_model: 'Suave',
    vehicle_color: 'Sapphire',
    vehicle_license_number: '92 321 87',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "20000000000000000,20000000000000000",
    "price_type": "km,flat",
    "price_description": "Price per km,City tax",
    "current_latitude": "32.785889",
    "current_longitude": "-79.935569",
    "pickup_at": "1513005534000",
    "vehicle_type": "suv",
    "vehicle_manufacturer": "Luxor",
    "vehicle_model": "Suave",
    "vehicle_color": "Sapphire",
    "vehicle_license_number": "92 321 87",
  }
requests.post("bidding_endpoint_here", data=payload)

Need

A statement of need for a ride. Typically this will be sent by a user that is looking for a ride to a certain destination.

This request is sent to the decentralized discovery engine which responds with status 200 and a unique identifier for this request. The details of this request are then broadcasted to DAV entities that can provide this service. Bids are later received as separate calls.

Arguments

Post request to a local/remote discovery endpoint

curl "discovery_endpoint_here" \
  --data "{ \
    \"pickup_at\": \"1513005534000\", \
    \"pickup_latitude\": \"32.787793\", \
    \"pickup_longitude\": \"-79.935005\", \
    \"pickup_street\": \"King\", \
    \"pickup_house_number\": \"372\", \
    \"pickup_city\": \"Charleston\", \
    \"pickup_postal_code\": \"29401\", \
    \"pickup_county\": \"Charleston\", \
    \"pickup_state\": \"SC\", \
    \"pickup_country\": \"USA\", \
    \"pickup_location_name\": \"IKEA parking lot B\", \
    \"pickup_location_name_lang\": \"eng\", \
    \"radius\": \"1500\", \
    \"destination_latitude\": \"32.7693531\", \
    \"destination_longitude\": \"-79.9296352\", \
    \"destination_street\": \"Murray Blvd\", \
    \"destination_house_number\": \"2\", \
    \"destination_city\": \"Charleston\", \
    \"destination_postal_code\": \"29401\", \
    \"destination_county\": \"Charleston\", \
    \"destination_state\": \"SC\", \
    \"destination_country\": \"USA\", \
    \"destination_location_name\": \"Oyster Point\", \
    \"destination_location_name_lang\": \"eng\", \
    \"vehicle_type\": \"suv\", \
    \"passengers\": \"3\", \
    \"additional_features\": \"assisted\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    pickup_at: '1513005534000',
    pickup_latitude: '32.787793',
    pickup_longitude: '-79.935005',
    pickup_street: 'King',
    pickup_house_number: '372',
    pickup_city: 'Charleston',
    pickup_postal_code: '29401',
    pickup_county: 'Charleston',
    pickup_state: 'SC',
    pickup_country: 'USA',
    pickup_location_name: 'IKEA parking lot B',
    pickup_location_name_lang: 'eng',
    radius: '1500',
    destination_latitude: '32.7693531',
    destination_longitude: '-79.9296352',
    destination_street: 'Murray Blvd',
    destination_house_number: '2',
    destination_city: 'Charleston',
    destination_postal_code: '29401',
    destination_county: 'Charleston',
    destination_state: 'SC',
    destination_country: 'USA',
    destination_location_name: 'Oyster Point',
    destination_location_name_lang: 'eng',
    vehicle_type: 'suv',
    passengers: '3',
    additional_features: 'assisted',
  }),
});

import requests
payload = {
    "pickup_at": "1513005534000",
    "pickup_latitude": "32.787793",
    "pickup_longitude": "-79.935005",
    "pickup_street": "King",
    "pickup_house_number": "372",
    "pickup_city": "Charleston",
    "pickup_postal_code": "29401",
    "pickup_county": "Charleston",
    "pickup_state": "SC",
    "pickup_country": "USA",
    "pickup_location_name": "IKEA parking lot B",
    "pickup_location_name_lang": "eng",
    "radius": "1500",
    "destination_latitude": "32.7693531",
    "destination_longitude": "-79.9296352",
    "destination_street": "Murray Blvd",
    "destination_house_number": "2",
    "destination_city": "Charleston",
    "destination_postal_code": "29401",
    "destination_county": "Charleston",
    "destination_state": "SC",
    "destination_country": "USA",
    "destination_location_name": "Oyster Point",
    "destination_location_name_lang": "eng",
    "vehicle_type": "suv",
    "passengers": "3",
    "additional_features": "assisted",
  }
requests.post("discovery_endpoint_here", data=payload)

`pickup_at` optional	The time at which the requester would like to be picked up (if undefined, pick up time will be ASAP). Specified as time in seconds since Epoch/Unix Time
`pickup_latitude` required	The latitude coordinate of the pickup location
`pickup_longitude` required	The longitude coordinate of the pickup location
`pickup_street` optional	The street name of the pick up location
`pickup_house_number` optional	The house number of the pick up location
`pickup_city` optional	The city of the pick up location
`pickup_postal_code` optional	The postal code of the pick up location
`pickup_county` optional	The county of the pick up location
`pickup_state` optional	The state of the pick up location
`pickup_country` optional	The country of the pick up location
`pickup_location_name` optional	A human readable name/description of the pick up location (e.g., Bayonne Crossing Shopping Center New Jersey)
`pickup_location_name_lang` optional	The language used in `pickup_location_name`. Specified using the 3 letter ISO 639-3 language code
`radius` optional	Radius in meters around the search coordinates to limit the search to. Specified as an integer
`destination_latitude` required	The latitude coordinate of the dropoff destination
`destination_longitude` required	The longitude coordinate of the dropoff destination
`destination_street` optional	The street name of the destination
`destination_house_number` optional	The house number of the destination
`destination_city` optional	The city of the destination
`destination_postal_code` optional	The postal code of the destination
`destination_county` optional	The county of the destination
`destination_state` optional	The state of the destination
`destination_country` optional	The country of the destination
`destination_location_name` optional	A human readable name/description of the destination location (e.g., Stadium Plaza Shopping Center New Jersey)
`destination_location_name_lang` optional	The language used in `destination_location_name_lang`. Specified using the 3 letter ISO 639-3 language code
`vehicle_type` optional	The type of vehicle required for the ride. See full list of options here
`passengers` required	The total number of passengers the vehicle should accommodate
`additional_features` optional	Vehicles may provide additional features. See full list of options here

Bid

A bid to provide a ride service. Typically sent by a car owner with the price for the ride, the distance from the pick up location and the estimated time of arrival.

Arguments

Post request to a local/remote bidding endpoint

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"20000000000000000,4000000000000000\", \
    \"price_type\": \"km,km\", \
    \"price_description\": \"Price per km,VAT per km\", \
    \"current_latitude\": \"32.785889\", \
    \"current_longitude\": \"-79.935569\", \
    \"pickup_at\": \"1513005534000\", \
    \"vehicle_type\": \"suv\", \
    \"vehicle_manufacturer\": \"Luxor\", \
    \"vehicle_model\": \"Suave\", \
    \"vehicle_color\": \"Sapphire\", \
    \"vehicle_license_number\": \"92 321 87\", \
    \"vehicle_contact\": \"James McGill, mobile: 555-338-5943\", \
    \"additional_features\": \"assisted\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '20000000000000000,4000000000000000',
    price_type: 'km,km',
    price_description: 'Price per km,VAT per km',
    current_latitude: '32.785889',
    current_longitude: '-79.935569',
    pickup_at: '1513005534000',
    vehicle_type: 'suv',
    vehicle_manufacturer: 'Luxor',
    vehicle_model: 'Suave',
    vehicle_color: 'Sapphire',
    vehicle_license_number: '92 321 87',
    vehicle_contact: 'James McGill, mobile: 555-338-5943',
    additional_features: 'assisted',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "20000000000000000,4000000000000000",
    "price_type": "km,km",
    "price_description": "Price per km,VAT per km",
    "current_latitude": "32.785889",
    "current_longitude": "-79.935569",
    "pickup_at": "1513005534000",
    "vehicle_type": "suv",
    "vehicle_manufacturer": "Luxor",
    "vehicle_model": "Suave",
    "vehicle_color": "Sapphire",
    "vehicle_license_number": "92 321 87",
    "vehicle_contact": "James McGill, mobile: 555-338-5943",
    "additional_features": "assisted",
  }
requests.post("bidding_endpoint_here", data=payload)

`need_id` required	The unique identifier of the 'need' this bid is for. This ID arrives as part of the 'need' request
`expires_at` required	This bid will expire at this time. Specified as time in seconds since Epoch/Unix Time
`price` required	A comma separated list of prices. Each price is specified as an integer representing Vinci 1 DAV == 1e18 Vinci == 1000000000000000000 Vinci
`price_type` required	A list of price types describing the `price` parameter(s). Specified as a comma separated list. See Price Types for available values
`price_description` required	A comma separated list of strings describing the `price` parameter(s) in human readable terms
`current_latitude` required	The latitude coordinate of of where the vehicle is currently located
`current_longitude` required	The longitude coordinate of where the vehicle is currently located
`pickup_at` required	The estimated time of arrival at the pick up location. Specified as time in seconds since Epoch/Unix Time
`vehicle_type` required	The type of vehicle used for the ride. See full list of options here
`vehicle_manufacturer` optional	Name of the manufacturer of the vehicle
`vehicle_model` optional	Name of the model of the vehicle
`vehicle_color` optional	The color of the vehicle
`vehicle_license_number` optional	The license plate number of the vehicle
`vehicle_contact` optional	Human readable information regarding the vehicle (e.g `James McGill, mobile: 555-338-5943`)
`additional_features` optional	Vehicles may provide additional features. See full list of options here

Vehicle Types

The type of vehicles and their unique identifier.

Vehicle Type	Description
`sedan`	Standard private car
`station`	Extended Sedan with extra room for luggage
`suv`	A kind of station wagon with off-road vehicle features such as raised ground clearance and ruggedness
`luxury`	A vehicle with higher quality equipment, better performance and enhanced comfort

Additional Features

Vehicles may provide additional features such as wheelchair access etc., below are the available features and their unique identifier.

Requirement	Description
`assisted`	Wheelchair access available
`pet_transport`	Pet transport is allowed
`ride_share`	Ride sharing is allowed

Price Types

Price types and their unique identifier.

Price Type	Description
`second`	Cost per second
`minute`	Cost per minute
`hour`	Cost per hour
`day`	Cost per day
`week`	Cost per week
`km`	Cost per km
`mile`	Cost per mile
`flat`	The listed `price` is a flat price