Route Planning

Route Planning Protocol

The following document describes the communication protocol for a route planning service provided by a route planner to a vehicle or a vehicle owner. It includes the format for both the request for a route plan (also referred to as need) and the response sent by route planners that bid on providing the service.

For example, an autonomous drone that needs to fly to a destination in the Nevada desert would send a request for a route plan for drones, along with the start and end coordinates, and the maximum altitude it can reach.

Need

curl "discovery_endpoint_here" \
  --data "{ \
    \"start_at\": \"1513005534000\", \
    \"start_latitude\": \"38.802610\", \
    \"start_longitude\": \"-116.419389\", \
    \"end_latitude\": \"38.807643\", \
    \"end_longitude\": \"-116.587960\", \
    \"vehicle_type\": \"drone\", \
    \"max_altitude\": \"400\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    start_at: '1513005534000',
    start_latitude: '38.802610',
    start_longitude: '-116.419389',
    end_latitude: '38.807643',
    end_longitude: '-116.587960',
    vehicle_type: 'drone',
    max_altitude: '400',
  }),
});

import requests
payload = {
    "start_at": "1513005534000",
    "start_latitude": "38.802610",
    "start_longitude": "-116.419389",
    "end_latitude": "38.807643",
    "end_longitude": "-116.587960",
    "vehicle_type": "drone",
    "max_altitude": "400",
  }
requests.post("discovery_endpoint_here", data=payload)

In response, a route planner might send back a bid with the price for the service, and the estimated time of when the route plan will be delivered.

Bid

curl "bidding_endpoint_here" \
--data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"100000000000000000\", \
    \"price_type\": \"flat\", \
    \"price_description\": \"Total price\", \
    \"eta\": \"1513178334000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '100000000000000000',
    price_type: 'flat',
    price_description: 'Total price',
    eta: '1513178334000',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "100000000000000000",
    "price_type": "flat",
    "price_description": "Total price",
    "eta": "1513178334000",
  }
requests.post("bidding_endpoint_here", data=payload)

Need

A statement of need for a route planning service. Typically this will be sent by a vehicle or a vehicle owner that plans to travel from one point to another.

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 "{ \
    \"start_at\": \"1513005534000\", \
    \"start_latitude\": \"38.802610\", \
    \"start_longitude\": \"-116.419389\", \
    \"end_latitude\": \"38.807643\", \
    \"end_longitude\": \"-116.587960\", \
    \"vehicle_type\": \"drone\", \
    \"max_altitude\": \"400\", \
    \"height\": \"11\", \
    \"width\": \"22\", \
    \"length\": \"28\", \
    \"weight\": \"2\" \
  }"

const discoveryEndPoint = 'discovery_endpoint_here';

fetch(discoveryEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    start_at: '1513005534000',
    start_latitude: '38.802610',
    start_longitude: '-116.419389',
    end_latitude: '38.807643',
    end_longitude: '-116.587960',
    vehicle_type: 'drone',
    max_altitude: '400',
    height: '11',
    width: '22',
    length: '28',
    weight: '2',
  }),
});

import requests
payload = {
    "start_at": "1513005534000",
    "start_latitude": "38.802610",
    "start_longitude": "-116.419389",
    "end_latitude": "38.807643",
    "end_longitude": "-116.587960",
    "vehicle_type": "drone",
    "max_altitude": "400",
    "height": "11",
    "width": "22",
    "length": "28",
    "weight": "2",
  }
requests.post("discovery_endpoint_here", data=payload)

`start_at` optional	The time at which the requester would like to start the trip (if undefined, start time will be set by the route planner). This should be Specified as time in seconds since Epoch/Unix Time
`start_latitude` required	The latitude coordinate of the starting point, from where the vehicle plans to start the trip
`start_longitude` required	The longitude coordinate of the starting point, from where the vehicle plans start the trip
`end_latitude` required	The latitude coordinate of the ending point, where the vehicle plans end the trip
`end_longitude` required	The longitude coordinate of the ending point, where the vehicle plans end the trip
`vehicle_type` required	The type of vehicle used for the trip. See full list of options here
`max_altitude` optional	In case the vehicle is a drone, `max_altitude` represents the maximum reachable altitude of the drone. Specified as an integer representing meters
`height` optional	The height of the vehicle. Specified as an integer representing centimeters
`width` optional	The width of the vehicle. Specified as an integer representing centimeters
`length` optional	The length of the vehicle. Specified as an integer representing centimeters
`weight` optional	The weight of the vehicle. Specified as an integer representing kilograms

Bid

A bid to provide a route plan. Typically sent by a route planner to a vehicle or a vehicle owner.

Arguments

Post request to a local/remote bidding endpoint

curl "bidding_endpoint_here" \
  --data "{ \
    \"need_id\": \"ae7bd8f67f3089c\", \
    \"expires_at\": \"1513005539000\", \
    \"price\": \"100000000000000000\", \
    \"price_type\": \"flat\", \
    \"price_description\": \"Total price\", \
    \"eta\": \"1513178334000\" \
  }"

const biddingEndPoint = 'bidding_endpoint_here';

fetch(biddingEndPoint, {
  method: 'POST',
  body: JSON.stringify({
    need_id: 'ae7bd8f67f3089c',
    expires_at: '1513005539000',
    price: '100000000000000000',
    price_type: 'flat',
    price_description: 'Total price',
    eta: '1513178334000',
  }),
});

import requests
payload = {
    "need_id": "ae7bd8f67f3089c",
    "expires_at": "1513005539000",
    "price": "100000000000000000",
    "price_type": "flat",
    "price_description": "Total price",
    "eta": "1513178334000",
  }
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
`eta` required	The estimated time of when the route plan will be delivered. Specified as time in seconds since Epoch/Unix Time

Vehicle Types

The type of vehicles and their unique identifier.

Vehicle Type
`drone`
`car`
`truck`
`van`
`ship`
`robot`
`bike`

Price Types

Price types and their unique identifier.

Price Type	Description
`km`	The listed `price` is per km
`mile`	The listed `price` is per mile
`flat`	The listed `price` is a flat price