NAV Navbar
shell javascript python
  • Ride Hailing Protocol
  • Need
  • Bid
  • Vehicle Types
  • Additional Features
  • Price Types
  • 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