NAV Navbar
shell javascript python
  • Electric Vehicle Charging Protocol
  • Need
  • Bid
  • Connector Types
  • Charging Levels
  • Energy Sources
  • Amenities
  • Price Types
  • Electric Vehicle Charging

    Electric Vehicle Charging Protocol

    The communication protocol for electric vehicle charging describes the format of a request for a charging service (need), and the response sent by a charging provider (bid).

    For example, an electric vehicle might search for charging stations within 1 km of the given coordinates that support a Tesla supercharger plug, and also have restrooms.

    Need

    curl "discovery_endpoint_here" \
      --data "{ \
        \"start_at\": \"1513005534000\", \
        \"latitude\": \"32.787793\", \
        \"longitude\": \"-79.935005\", \
        \"radius\": \"1000\", \
        \"connector\": \"tesla_supercharger\", \
        \"amenities\": \"3\" \
      }"
    
    const discoveryEndPoint = 'discovery_endpoint_here';
    
    fetch(discoveryEndPoint, {
      method: 'POST',
      body: JSON.stringify({
        start_at: '1513005534000',
        latitude: '32.787793',
        longitude: '-79.935005',
        radius: '1000',
        connector: 'tesla_supercharger',
        amenities: '3',
      }),
    });
    
    import requests
    payload = {
        "start_at": "1513005534000",
        "latitude": "32.787793",
        "longitude": "-79.935005",
        "radius": "1000",
        "connector": "tesla_supercharger",
        "amenities": "3",
      }
    requests.post("discovery_endpoint_here", data=payload)
    

    In response, a charging station might send back a bid with a price per kWh, and the full details of the services it offers.

    Bid

    curl "bidding_endpoint_here" \
      --data "{ \
        \"need_id\": \"ae7bd8f67f3089c\", \
        \"expires_at\": \"1513005539000\", \
        \"price\": \"2300000000000000000,30000000000000000\", \
        \"price_type\": \"kwh,kwh\", \
        \"price_description\": \"Price per kWh,VAT per kWh\", \
        \"latitude\": \"32.785889\", \
        \"longitude\": \"-79.935569\", \
        \"available_from\": \"1513005534000\", \
        \"available_until\": \"1513091934000\", \
        \"connectors\": \"tesla_hpwc,tesla_supercharger\", \
        \"charging_levels\": \"2,3\", \
        \"amenities\": \"2,3,4,7,9\" \
      }"
    
    const biddingEndPoint = 'bidding_endpoint_here';
    
    fetch(biddingEndPoint, {
      method: 'POST',
      body: JSON.stringify({
        need_id: 'ae7bd8f67f3089c',
        expires_at: '1513005539000',
        price: '2300000000000000000,30000000000000000',
        price_type: 'kwh,kwh',
        price_description: 'Price per kWh,VAT per kWh',
        latitude: '32.785889',
        longitude: '-79.935569',
        available_from: '1513005534000',
        available_until: '1513091934000',
        connectors: 'tesla_hpwc,tesla_supercharger',
        charging_levels: '2,3',
        amenities: '2,3,4,7,9',
      }),
    });
    
    import requests
    payload = {
        "need_id": "ae7bd8f67f3089c",
        "expires_at": "1513005539000",
        "price": "2300000000000000000,30000000000000000",
        "price_type": "kwh,kwh",
        "price_description": "Price per kWh,VAT per kWh",
        "latitude": "32.785889",
        "longitude": "-79.935569",
        "available_from": "1513005534000",
        "available_until": "1513091934000",
        "connectors": "tesla_hpwc,tesla_supercharger",
        "charging_levels": "2,3",
        "amenities": "2,3,4,7,9",
      }
    requests.post("bidding_endpoint_here", data=payload)
    

    Need

    A statement of need for charging stations. Typically this will be sent by an electric vehicle that is looking for a charging station around certain coordinates.

    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\", \
        \"latitude\": \"32.787793\", \
        \"longitude\": \"-79.935005\", \
        \"radius\": \"10000\", \
        \"height\": \"200\", \
        \"width\": \"120\", \
        \"length\": \"330\", \
        \"weight\": \"1200\", \
        \"connector\": \"tesla_supercharger\", \
        \"charging_level\": \"3\", \
        \"battery_capacity\": \"56\", \
        \"current_battery_charge\": \"26\", \
        \"energy_source\": \"solar\", \
        \"amenities\": \"2,3\" \
      }"
    
    const discoveryEndPoint = 'discovery_endpoint_here';
    
    fetch(discoveryEndPoint, {
      method: 'POST',
      body: JSON.stringify({
        start_at: '1513005534000',
        latitude: '32.787793',
        longitude: '-79.935005',
        radius: '10000',
        height: '200',
        width: '120',
        length: '330',
        weight: '1200',
        connector: 'tesla_supercharger',
        charging_level: '3',
        battery_capacity: '56',
        current_battery_charge: '26',
        energy_source: 'solar',
        amenities: '2,3',
      }),
    });
    
    import requests
    payload = {
        "start_at": "1513005534000",
        "latitude": "32.787793",
        "longitude": "-79.935005",
        "radius": "10000",
        "height": "200",
        "width": "120",
        "length": "330",
        "weight": "1200",
        "connector": "tesla_supercharger",
        "charging_level": "3",
        "battery_capacity": "56",
        "current_battery_charge": "26",
        "energy_source": "solar",
        "amenities": "2,3",
      }
    requests.post("discovery_endpoint_here", data=payload)
    
    start_at
    optional
    The time at which the requester would like to arrive at charging station (if undefined, the arrival time will be ASAP). Specified as time in seconds since Epoch/Unix Time
    latitude
    required
    The latitude coordinate around which to search
    longitude
    required
    The longitude coordinate around which to search
    radius
    required
    Radius in meters around the search coordinates to limit the search to. Specified as an integer
    height
    optional
    The minimum height clearance that this vehicle requires from the station. Specified as an integer representing centimeters
    width
    optional
    The minimum width clearance that this vehicle requires from the station. Specified as an integer representing centimeters
    length
    optional
    The minimum length clearance that this vehicle requires from the station. Specified as an integer representing centimeters
    weight
    optional
    The weight of this vehicle. Stations that cannot support a vehicle weighing this much should not respond. Specified as an integer representing kilograms
    connector
    required
    The connector type required by the EV. Specified as a connector id. See Connector Types for available values
    charging_level
    optional
    The charging level as defined by SAE standards. Specified as an integer. See Charging Levels
    battery_capacity
    optional
    The vehicle's total battery capacity, specified in kWh
    current_battery_charge
    optional
    The vehicle's current battery charge level, as it was at the time the request was sent. Specified as an integer denoting percentage of full capacity
    energy_source
    optional
    Limit the request to only receive bids from stations using a specific source of the energy. Specified as an energy source id. See Energy Sources
    amenities
    optional
    A list of amenities that need to be present at charging station. Specified as a comma separated list of amenity ids. See Amenities

    Bid

    A bid to provide a charging service. Typically sent from a charging station to an electric vehicle.

    Arguments

    Post request to a local/remote bidding endpoint

    curl "bidding_endpoint_here" \
      --data "{ \
        \"need_id\": \"ae7bd8f67f3089c\", \
        \"expires_at\": \"1513005539000\", \
        \"price\": \"2300000000000000000,30000000000000000\", \
        \"price_type\": \"kwh,kwh\", \
        \"price_description\": \"Price per kWh,VAT per kWh\", \
        \"latitude\": \"32.785889\", \
        \"longitude\": \"-79.935569\", \
        \"entrance_latitude\": \"32.785878\", \
        \"entrance_longitude\": \"-79.935558\", \
        \"exit_latitude\": \"32.785878\", \
        \"exit_longitude\": \"-79.935558\", \
        \"location_floor\": \"2\", \
        \"location_name\": \"IKEA parking lot B\", \
        \"location_name_lang\": \"eng\", \
        \"location_house_number\": \"372\", \
        \"location_street\": \"King\", \
        \"location_city\": \"Charleston\", \
        \"location_postal_code\": \"29401\", \
        \"location_county\": \"Charleston\", \
        \"location_state\": \"SC\", \
        \"location_country\": \"USA\", \
        \"available_from\": \"1513005534000\", \
        \"available_until\": \"1513091934000\", \
        \"height\": \"300\", \
        \"width\": \"200\", \
        \"length\": \"580\", \
        \"weight\": \"10000\", \
        \"connectors\": \"tesla_hpwc,tesla_supercharger\", \
        \"charging_levels\": \"2,3\", \
        \"energy_source\": \"solar\", \
        \"amenities\": \"2,3,4,7,9\", \
        \"provider\": \"Tesla\", \
        \"manufacturer\": \"Tesla\", \
        \"model\": \"Supercharger\" \
      }"
    
    const biddingEndPoint = 'bidding_endpoint_here';
    
    fetch(biddingEndPoint, {
      method: 'POST',
      body: JSON.stringify({
        need_id: 'ae7bd8f67f3089c',
        expires_at: '1513005539000',
        price: '2300000000000000000,30000000000000000',
        price_type: 'kwh,kwh',
        price_description: 'Price per kWh,VAT per kWh',
        latitude: '32.785889',
        longitude: '-79.935569',
        entrance_latitude: '32.785878',
        entrance_longitude: '-79.935558',
        exit_latitude: '32.785878',
        exit_longitude: '-79.935558',
        location_floor: '2',
        location_name: 'IKEA parking lot B',
        location_name_lang: 'eng',
        location_house_number: '372',
        location_street: 'King',
        location_city: 'Charleston',
        location_postal_code: '29401',
        location_county: 'Charleston',
        location_state: 'SC',
        location_country: 'USA',
        available_from: '1513005534000',
        available_until: '1513091934000',
        height: '300',
        width: '200',
        length: '580',
        weight: '10000',
        connectors: 'tesla_hpwc,tesla_supercharger',
        charging_levels: '2,3',
        energy_source: 'solar',
        amenities: '2,3,4,7,9',
        provider: 'Tesla',
        manufacturer: 'Tesla',
        model: 'Supercharger',
      }),
    });
    
    import requests
    payload = {
        "need_id": "ae7bd8f67f3089c",
        "expires_at": "1513005539000",
        "price": "2300000000000000000,30000000000000000",
        "price_type": "kwh,kwh",
        "price_description": "Price per kWh,VAT per kWh",
        "latitude": "32.785889",
        "longitude": "-79.935569",
        "entrance_latitude": "32.785878",
        "entrance_longitude": "-79.935558",
        "exit_latitude": "32.785878",
        "exit_longitude": "-79.935558",
        "location_floor": "2",
        "location_name": "IKEA parking lot B",
        "location_name_lang": "eng",
        "location_house_number": "372",
        "location_street": "King",
        "location_city": "Charleston",
        "location_postal_code": "29401",
        "location_county": "Charleston",
        "location_state": "SC",
        "location_country": "USA",
        "available_from": "1513005534000",
        "available_until": "1513091934000",
        "height": "300",
        "width": "200",
        "length": "580",
        "weight": "10000",
        "connectors": "tesla_hpwc,tesla_supercharger",
        "charging_levels": "2,3",
        "energy_source": "solar",
        "amenities": "2,3,4,7,9",
        "provider": "Tesla",
        "manufacturer": "Tesla",
        "model": "Supercharger",
      }
    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
    latitude
    required
    The latitude coordinate of the charging station
    longitude
    required
    The longitude coordinate of the charging station
    entrance_latitude
    optional
    The latitude coordinate of the entrance to the charging station
    entrance_longitude
    optional
    The longitude coordinate of the entrance to the charging station
    exit_latitude
    optional
    The latitude coordinate of the exit from the charging station
    exit_longitude
    optional
    The longitude coordinate of the exit from the charging station
    location_floor
    optional
    Which floor/level is the charging stations located on (for multistory buildings)
    location_name
    optional
    A human readable name/description of the charging station location (e.g., Lund Train Station parking)
    location_name_lang
    optional
    The language used in location_name. Specified using the 3 letter ISO 639-3 language code
    location_house_number
    optional
    The house number where the station is located
    location_street
    optional
    The street name where the station is located
    location_city
    optional
    The city where the station is located
    location_postal_code
    optional
    The postal code where the station is located
    location_county
    optional
    The county where the station is located
    location_state
    optional
    The state where the station is located
    location_country
    optional
    The country where the station is located
    available_from
    required
    The time from which the charging station can be made available for the vehicle requesting a charge. Specified as time in seconds since Epoch/Unix Time
    available_until
    optional
    The time until which the charging station can be made available for the vehicle requesting a charge. Specified as time in seconds since Epoch/Unix Time
    height
    optional
    The maximum vehicle height this station can accommodate. Specified as an integer representing centimeters
    width
    optional
    The maximum vehicle width this station can accommodate. Specified as an integer representing centimeters
    length
    optional
    The maximum vehicle length this station can accommodate. Specified as an integer representing centimeters
    weight
    optional
    The maximum vehicle weight this station can accommodate. Specified as an integer representing kilograms
    connectors
    required
    A list of connector types available at this charging station. Specified as a comma separated list of connector ids. See Connector Types for available values
    charging_levels
    optional
    A list of charging levels as defined by SAE standards available at this charging station. Specified as a comma separated list of integers. See Charging Levels
    energy_source
    optional
    The source of the energy used by this charging station. Specified as an energy source id. See Energy Sources
    amenities
    optional
    A list of amenities that are present at this charging station. Specified as a comma separated list of amenity ids. See Amenities
    provider
    optional
    Name of the service provider or charging network operating this charging station
    manufacturer
    optional
    Name of the manufacturer of this charging station
    model
    optional
    Name of the model of this charging station

    Connector Types

    Connector types and their unique identifier.

    Connector ID Name Charging Level
    nema_5_15 NEMA 5-15 Wall Outlet 1
    nema_5_20 NEMA 5-20 Wall Outlet 1
    j1772 SAE J1772 2
    mennekes SAE J3068 / IEC 62196 (Mennekes) 2
    nema_14_50 NEMA 14-50 (RV plug) 2
    chademo CHAdeMO 3
    ccs SAE Combined Charging System (CCS) 3
    tesla_hpwc Tesla HPWC 2
    tesla_supercharger Tesla supercharger 3

    Charging Levels

    Available charging levels.

    Level Description
    1 Standard house outlet
    2 240 volt AC charging
    3 DC fast charging

    Energy Sources

    The energy source used by the station.

    Level Description
    grid Connected to the electrical grid and using an unspecified energy source, or an unspecified mix of energy source
    renewable Uses 100% renewable energy of an unspecified source, or a mix of different renewable energy sources
    solar Uses 100% solar energy
    wind Uses 100% wind energy
    hydro Uses 100% hydro power energy
    geothermal Uses 100% geothermal energy

    Amenities

    A list of amenities can be included in both requests and responses.

    ID Description
    1 Lodging
    2 Dining
    3 Restrooms
    4 Parking
    5 Valet Parking
    6 Park
    7 WiFi
    8 Shopping
    9 Grocery

    Price Types

    Price types and their unique identifier.

    Price Type Description
    kwh Cost per kWh
    second Cost per second
    minute Cost per minute
    hour Cost per hour
    day Cost per day
    week Cost per week
    flat The listed price is a flat price