NAV Navbar
shell javascript python
  • Route Planning Protocol
  • Need
  • Bid
  • Vehicle Types
  • Price Types
  • 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