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