EVCoDriver API

The EVCoDriver API is a routing API designed specifically for EVs (electric vehicles) with the goal of reducing range anxiety and charging anxiety during trips. The API allows you to search for an optimized route by specifying a car model, current battery level (SOC, State of Charge), start and end points, and other optional parameters as well. It will then return the best route with the lowest energy consumption from starting point to each specified destination, including the best available charging stations along the route. Routes are calculated based on the total duration of drive time, expected wait times & charge times at charging stations, and the energy required to leave the destination for another trip. To learn more, visit https://evcodriver.com.

Contact

API Support

[email protected]

https://evcodriver.com/index.php/contact/

Terms of Service

https://evcodriver.com/index.php/terms-of-use/

API Endpoints
# Endpoint:
https://example:{port}/graphql
Version

1.2.0

Queries

authorizationNetworks

Description

Requires authorization token with "authorizationNetwork" role.
This returns the list of Authorization networks Please call this API to get the list of auth network id and name that can be used to filter car and route API.

Response

Returns [AuthorizationNetworks]

Example

Query
query AuthorizationNetworks {
  authorizationNetworks {
    id
    name
  }
}
Response
{
  "data": {
    "authorizationNetworks": [
      {"id": 4, "name": "example string"}
    ]
  }
}
Queries

car

Description

Requires authorization token with "car" role.
This returns the details of the selected car.
See cars endpoint to get a list of usable IDs.

Response

Returns a Car

Arguments
Name Description
id - ID! Unique key

Example

Query
query Car($id: ID!) {
  car(id: $id) {
    id
    make
    model
    year
    range
    trim
    option
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "car": {
      "id": 4,
      "make": "example string",
      "model": "example string",
      "year": 987,
      "range": 123,
      "trim": "example string",
      "option": "example string"
    }
  }
}
Queries

cars

Description

Requires authorization token with "car" role.
This returns the list of the supported Cars in EVCoDriver.
Can optionally provide car make, model, year, and/or VIN to filter the results. VIN must be 17 alphanumeric digits only.
Please call this API to get the ID assigned per car and call route API.

Response

Returns [Car]

Arguments
Name Description
make - String Car make
model - String Car model
year - Int Car year

Example

Query
query Cars(
  $make: String,
  $model: String,
  $year: Int,
) {
  cars(
    make: $make,
    model: $model,
    year: $year
  ) {
    id
    make
    model
    year
    range
    trim
    option
  }
}
Variables
{
  "make": "example string",
  "model": "example string",
  "year": 987,
}
Response
{
  "data": {
    "cars": [
      {
        "id": 4,
        "make": "example string",
        "model": "example string",
        "year": 987,
        "range": 123,
        "trim": "example string",
        "option": "example string"
      }
    ]
  }
}
Queries

carsTest

Description

Requires authorization token with "car" role.
This is a dummy Api interface for cars It returns only dummy list of the cars.

Response

Returns [Car]

Arguments
Name Description
make - String Car make
model - String Car model
year - Int Car year

Example

Query
query CarsTest(
  $make: String,
  $model: String,
  $year: Int
) {
  carsTest(
    make: $make,
    model: $model,
    year: $year
  ) {
    id
    make
    model
    year
    range
    trim
    option
  }
}
Variables
{
  "make": "example string",
  "model": "example string",
  "year": 987
}
Response
{
  "data": {
    "carsTest": [
      {
        "id": "4",
        "make": "example string",
        "model": "example string",
        "year": 123,
        "range": 123,
        "trim": "example string",
        "option": "example string"
      }
    ]
  }
}
Queries

discharge

Description

Requires authorization token with "discharge" role.
Returns estimated energy consumption value “energyConsumption”
for a short distance (e.g. several hundred meters or 1-3 km)
from Point A to Point B for the purpose of calculating
the latest SOC value in EV turn-by-turn navigation app while navigating.
A different rate will be applied to this API.

Response

Returns a Discharge!

Arguments
Name Description
start - LocationInput! Start point
destination - LocationInput! Destination
carId - ID! Car ID to use in route retrieval. See cars endpoint to get a list of usable IDs.
averageGradient - Float (Optional) Average road gradient of a splitted distance out of the EV trip route. Value must be set between -1.000 to maximum 1.000. “0.0” means flat. If averageGradient is not specified, default setting in EVCoDriver API server is used. In the case of using discharge API to calculate the estimated energy consumption while navigating, averageGradient should be specified. If averageGradient is not specified, 0 is used.
averageAcceleration - Float (Optional) Average acceleration (m/s2) from start location to destination location of a splitted distance out of the EV trip route.
averageSpeed - Float (Optional) Average speed (km/h) from start location to destination location of a splitted distance out of the EV trip route.
additionalWeight - Float (Optional) Weight of passengers and luggage in kg.

Example

Query
query Discharge(
  $start: LocationInput!,
  $destination: LocationInput!,
  $carId: ID!,
  $averageGradient: Float,
  $averageAcceleration: Float,
  $averageSpeed: Float,
  $additionalWeight: Float
) {
  discharge(
    start: $start,
    destination: $destination,
    carId: $carId,
    averageGradient: $averageGradient,
    averageAcceleration: $averageAcceleration,
    averageSpeed: $averageSpeed,
    additionalWeight: $additionalWeight
  ) {
    energyConsumption
    origin {
      lat
      lng
    }
    destination {
      distance
    }
  }
}
Variables
{
  "start": LocationInput,
  "destination": LocationInput,
  "carId": 4,
  "averageGradient": 123.45,
  "averageAcceleration": 987.65,
  "averageSpeed": 123.45,
  "additionalWeight": 987.65
}
Response
{
  "data": {
    "discharge": {
      "energyConsumption": 123.45,
      "origin": Location,
      "destination": DischargeDestination
    }
  }
}
Queries

networkBrands

Description

Requires authorization token with "networkBrands" role.
Get the list of supported EV charging network brands which you might want to use for filtering in route API.

Response

Returns [NetworkBrand]

Example

Query
query NetworkBrands {
  networkBrands {
    name
  }
}
Response
{
  "data": {
    "networkBrands": [
      {"name": "example string"}
    ]
  }
}
Queries

route

Description

Requires authorization token with "route" role.
Route retrieval API will return a single route from start to destination.

Response

Returns a Route!

Arguments
Name Description
start - LocationInput! Start point
destination - LocationInput! Destination
waypoints - [LocationInput!] Waypoints if any
startSoc - Float! Battery level to start. The value must be greater than 0 to maximum 1.
carId - ID! Car ID to use in route retrieval. See cars endpoint to get a list of usable IDs.
batteryBuffer - BatteryBuffer! See BatteryBuffer for details.
brands - [String] To specify EV network brands to use (By default it uses all).
Please check networkBrands query for the list of supported brands.
authNetworkId - [Int] Authorization network id to filter auth networks by IDs.
avoid - [Avoid] See Avoid for details.
soh - Float Battery State of Health. The value must be greater than 0.75 to maximum 1.
additionalWeight - Float Additional weight of passengers and passengers' luggage in kilograms.
minBatteryLevel - Float To specify remaining battery at a destination. The value must be greater than 0 to maximum 0.70.

Example

Query
query Route(
  $start: LocationInput!,
  $destination: LocationInput!,
  $waypoints: [LocationInput!],
  $startSoc: Float!,
  $carId: ID!,
  $batteryBuffer: BatteryBuffer!,
  $brands: [String],
  $authNetworkId: [Int],
  $avoid: [Avoid],
  $soh: Float,
  $additionalWeight: Float,
  $minBatteryLevel: Float
) {
  route(
    start: $start,
    destination: $destination,
    waypoints: $waypoints,
    startSoc: $startSoc,
    carId: $carId,
    batteryBuffer: $batteryBuffer,
    brands: $brands,
    authNetworkId: $authNetworkId,
    avoid: $avoid,
    soh: $soh,
    additionalWeight: $additionalWeight,
    minBatteryLevel: $minBatteryLevel
  ) {
    totalDistance
    totalTime
    legs {
      totalDistance
      totalTime
      start {
        lat
        lng
      }
      destination {
        lat
        lng
      }
      startSoc
      endSoc
      charges {
        estimatedSoc
        plannedSoc
        station {
          ...StationFragment
        }
        chargeTime
      }
    }
    message
    batteryBuffer
    polyLine {
      points
    }
  }
}
Variables
{
  "start": LocationInput,
  "destination": LocationInput,
  "waypoints": [LocationInput],
  "startSoc": 123.45,
  "carId": "4",
  "batteryBuffer": "HIGH",
  "brands": ["example string"],
  "authNetworkId": [987],
  "avoid": ["TOLLS"],
  "soh": 123.45,
  "additionalWeight": 123.45,
  "minBatteryLevel": 987.65
}
Response
{
  "data": {
    "route": {
      "totalDistance": 123.45,
      "totalTime": 987.65,
      "legs": [Leg],
      "message": "example string",
      "batteryBuffer": "HIGH",
      "polyLine": PolyLine
    }
  }
}
Queries

routes

Description

Requires authorization token with "routes" role.
Routes retrieval API will return a single routes from start to destination.
A different rate will be applied to this API.

Response

Returns [RankedRoute]!

Arguments
Name Description
start - LocationInput! Start point
destination - LocationInput! Destination
waypoints - [LocationInput!] Waypoints if any
startSoc - Float! Battery level to start. The value must be greater than 0 to maximum 1.
carId - ID! Car ID to use in routes retrieval. See cars endpoint to get a list of usable IDs.
batteryBuffer - BatteryBuffer! See BatteryBuffer for details.
brands - [String] To specify EV network brands to use (By default it uses all).
Please check networkBrands query for the list of supported brands.
authNetworkId - [Int] Authorization network id to filter auth networks by IDs.
avoid - [Avoid] See Avoid for details.
soh - Float Battery State of Health. The value must be greater than 0.75 to maximum 1.
additionalWeight - Float Additional weight of passengers and passengers' luggage in kilograms.
minBatteryLevel - Float To specify remaining battery at a destination. The value must be greater than 0 to maximum 0.70.

Example

Query
query Routes(
  $start: LocationInput!,
  $destination: LocationInput!,
  $waypoints: [LocationInput!],
  $startSoc: Float!,
  $carId: ID!,
  $batteryBuffer: BatteryBuffer!,
  $brands: [String],
  $authNetworkId: [Int],
  $avoid: [Avoid],
  $soh: Float,
  $additionalWeight: Float,
  $minBatteryLevel: Float
) {
  routes(
    start: $start,
    destination: $destination,
    waypoints: $waypoints,
    startSoc: $startSoc,
    carId: $carId,
    batteryBuffer: $batteryBuffer,
    brands: $brands,
    authNetworkId: $authNetworkId,
    avoid: $avoid,
    soh: $soh,
    additionalWeight: $additionalWeight,
    minBatteryLevel: $minBatteryLevel
  ) {
    rank
    totalDistance
    totalTime
    legs {
      totalDistance
      totalTime
      start {
        lat
        lng
      }
      destination {
        lat
        lng
      }
      startSoc
      endSoc
      charges {
        estimatedSoc
        plannedSoc
        station {
          ...StationFragment
        }
        chargeTime
      }
    }
    message
    batteryBuffer
    polyLine {
      points
    }
  }
}
Variables
{
  "start": LocationInput,
  "destination": LocationInput,
  "waypoints": [LocationInput],
  "startSoc": 987.65,
  "carId": 4,
  "batteryBuffer": "HIGH",
  "brands": ["example string"],
  "authNetworkId": [123],
  "avoid": ["TOLLS"],
  "soh": 123.45,
  "additionalWeight": 987.65,
  "minBatteryLevel": 987.65
}
Response
{
  "data": {
    "routes": [
      {
        "rank": 987,
        "totalDistance": 987.65,
        "totalTime": 123.45,
        "legs": [Leg],
        "message": "example string",
        "batteryBuffer": "HIGH",
        "polyLine": PolyLine
      }
    ]
  }
}

Types

AuthorizationNetworks

Fields
Field Name Description
id - ID Unique ID assigned per Authorization Networks
name - String Authorization network name
Example
{"id": 4, "name": "example string"}
Types

Avoid

Description

To specify what type/s of route to avoid.

Values
Enum Value Description

TOLLS

 Avoid tolls

HIGHWAYS

 Avoid highways/motorways

FERRIES

 Avoid ferries
Example
"TOLLS"
Types

BatteryBuffer

Description

Desired battery level on arrival at destination.

Values
Enum Value Description

HIGH

 Enough battery level will be left to reach two stations after arriving at the destination.

MID

 Enough battery level will be left to reach one station after arriving at the destination.

LOW

 Minimal battery level upon arrival at the destination.
It is strongly recommended that the destination is equipped with charging facilities as a minimal battery level does not guarantee the vehicle will reach a charging station.
Example
"HIGH"
Types

Boolean

Description

The Boolean scalar type represents true or false.

Example
true
Types

Car

Fields
Field Name Description
id - ID! Unique ID assigned per car model.
make - String! Brand name
model - String! Model name
year - Int! Model year
range - Int! Driving range announced by the car manufacturer in miles.
trim - String Model trim
option - String Car option
Example
{
  "id": "4",
  "make": "example string",
  "model": "example string",
  "year": 123,
  "range": 987,
  "trim": "example string",
  "option": "example string"
}
Types

ChargeStation

Fields
Field Name Description
estimatedSoc - Float! Estimated arrival battery level at this station
plannedSoc - Float Suggested battery level to charge to at this station.
station - Station Station details. Please see Station for more details.
chargeTime - Float Required time in seconds to charge up to the planned battery level at the station.
Example
{
  "estimatedSoc": 987.65,
  "plannedSoc": 987.65,
  "station": Station,
  "chargeTime": 123.45
}
Types

Charger

Fields
Field Name Description
id - ID! Unique ID assigned per charger.
status - ChargerAvailability! Status of this charger. Please see ChargerAvailability for more details.
connectors - [Connector!] Connectors linked to this charger. Please see Connector for more details.
Example
{
  "id": 4,
  "status": "AVAILABLE",
  "connectors": [Connector]
}
Types

ChargerAvailability

Description

Type of charger status. Please check OCPI charging status list for more details.

Values
Enum Value Description

AVAILABLE

BLOCKED

CHARGING

INOPERATIVE

OUTOFORDER

PLANNED

REMOVED

RESERVED

UNKNOWN

NODATA

UNAVAILABLE
Example
"AVAILABLE"
Types

Connector

Fields
Field Name Description
id - ID! Unique ID assigned per connector
plugType - PlugType! Plug type. Please see PlugType for details.
description - String Optional note for this connector
powerType - PowerType! Power delivery type
maxPowerLevel - Float Max power level (kW). Could be null if there is no data.
Example
{
  "id": "4",
  "plugType": "CHADEMO",
  "description": "example string",
  "powerType": "DC",
  "maxPowerLevel": 987.65
}
Types

Discharge

Fields
Field Name Description
energyConsumption - Float! Estimated energy consumption (kWh) from start to destination.
origin - Location
destination - DischargeDestination
Example
{
  "energyConsumption": 123.45,
  "origin": Location,
  "destination": DischargeDestination
}
Types

DischargeDestination

Fields
Field Name Description
distance - Float distance travelled
Example
{"distance": 123.45}
Types

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
123.45
Types

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example
"4"
Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
987
Types

JWTResponse

Description

Token should be set in the request header as "authorization" property.
ex)
header: {
...other_header_properties,
authorization: "{set_token_here}"
}

Fields
Field Name Description
token - String JSON Web Token style string
Example
{"token": "example string"}
Types

Leg

Fields
Field Name Description
totalDistance - Float! Total distance for this leg (km).
totalTime - Float! Total time in seconds for this leg
start - Location Start point of this leg
destination - Location Destination of this leg
startSoc - Float Battery level at the start of the leg
endSoc - Float Estimated arrival battery level at the end of this leg.
charges - [ChargeStation] Stations to stop by between the start and end of this leg. Please see ChargeStation for more details.
Example
{
  "totalDistance": 123.45,
  "totalTime": 987.65,
  "start": Location,
  "destination": Location,
  "startSoc": 987.65,
  "endSoc": 123.45,
  "charges": [ChargeStation]
}
Types

Location

Fields
Field Name Description
lat - Float! latitude
lng - Float! longitude
Example
{"lat": 123.45, "lng": 987.65}
Types

LocationInput

Fields
Input Field Description
lat - Float! latitude
lng - Float! longitude
Example
{"lat": 987.65, "lng": 987.65}
Types

NetworkBrand

Fields
Field Name Description
name - String! EV station network or group brand name.
Example
{"name": "example string"}
Types

PlugType

Description

String identifying each plug type

Values
Enum Value Description

CHADEMO

DOMESTIC_A

DOMESTIC_B

DOMESTIC_C

DOMESTIC_D

DOMESTIC_E

DOMESTIC_F

DOMESTIC_G

DOMESTIC_H

DOMESTIC_I

DOMESTIC_J

DOMESTIC_K

DOMESTIC_L

IEC_60309_2_single_16

IEC_60309_2_three_16

IEC_60309_2_three_32

IEC_60309_2_three_64

IEC_62196_T1

IEC_62196_T1_COMBO

IEC_62196_T2

IEC_62196_T2_COMBO

IEC_62196_T3A

IEC_62196_T3C

PANTOGRAPH_BOTTOM_UP

PANTOGRAPH_TOP_DOWN

TESLA_R

TESLA_S

UNKNOWN
Example
"CHADEMO"
Types

PolyLine

Fields
Field Name Description
points - String! Google Maps format polyline string.
Example
{"points": "example string"}
Types

PowerType

Description

Power delivery type

Values
Enum Value Description

DC

 DC

AC

 AC

EMPTY

 Power type not specified
Example
"DC"
Types

RankedRoute

Fields
Field Name Description
rank - Int! A number indicating which is the best route and which are the alternatives (1 is the best, 2 and 3 are alternatives)
totalDistance - Float! Total distance from the start point to the destination. (km)
totalTime - Float! Total time in seconds from the start point to the destination.
legs - [Leg]! See Leg type.
message - String Optional route note.
batteryBuffer - BatteryBuffer (Deprecated) Desired battery level on arrival at destination. Please see BatteryBufferfor more details.
polyLine - PolyLine! See Polyline type.
Example
{
  "rank": 123,
  "totalDistance": 123.45,
  "totalTime": 123.45,
  "legs": [Leg],
  "message": "example string",
  "batteryBuffer": "HIGH",
  "polyLine": PolyLine
}
Types

Route

Fields
Field Name Description
totalDistance - Float! Total distance from the start point to the destination. (km)
totalTime - Float! Total time in seconds from the start point to the destination.
legs - [Leg]! See Leg type.
message - String Optional route note.
batteryBuffer - BatteryBuffer (Deprecated) Desired battery level on arrival at destination. Please see BatteryBufferfor more details.
polyLine - PolyLine! See Polyline type.
Example
{
  "totalDistance": 987.65,
  "totalTime": 123.45,
  "legs": [Leg],
  "message": "example string",
  "batteryBuffer": "HIGH",
  "polyLine": PolyLine
}
Types

StaticLocation

Fields
Field Name Description
location - Location See Location for more details.
timeZone - String timeZone of this location
address - String! Address of this location
Example
{
  "location": Location,
  "timeZone": "example string",
  "address": "example string"
}
Types

Station

Fields
Field Name Description
id - ID! Unique ID per station
label - String Name of the station
staticLocation - StaticLocation See StaticLocation for more details
stationInfo - StationInfo See StationInfo for more details
stationStatus - StationStatus See StationStatus for more details
chargers - [Charger!] See Charger for more details
displayLabel - String Short name of the station
authNetwork - [AuthorizationNetworks] Authorization network name
Example
{
  "id": 4,
  "label": "example string",
  "staticLocation": StaticLocation,
  "stationInfo": StationInfo,
  "stationStatus": StationStatus,
  "chargers": [Charger],
  "displayLabel": "example string",
  "authNetwork": [AuthorizationNetworks]
}
Types

StationAvailability

Description

Type of station status.

Values
Enum Value Description

AVAILABLE

 At least one charger is available

CHARGING

 All chargers are in use

NODATA

 Cannot get status data

OUTOFORDER

 All chargers are out of order
Example
"AVAILABLE"
Types

StationInfo

Fields
Field Name Description
owner - String Station owner
operator - String Station operator
Example
{
  "owner": "example string",
  "operator": "example string"
}
Types

StationStatus

Fields
Field Name Description
waitTime - Float! Estimated wait time in seconds to access a charger.
status - StationAvailability! Status of this station. Please see StationAvailability for more details.
Example
{"waitTime": 123.45, "status": "AVAILABLE"}
Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"example string"
Documentation by Anvil SpectaQL