EVCoDriver API

The EVCoDriver API is a powerful routing engine designed specifically for EV applications. It allows you remove the complex task of pre-trip route planning, particularly for longer drives, and addresses both range anxiety and charging anxiety.

The API allows you to create an optimized route by specifying a car model, current battery level (SOC), and start & end coordinates. Other optional parameters can further improve results. EVCoDriver returns the best route with the lowest energy consumption, and automatically includes the best available charging stations along the route.

Find our demo app on your app store, and learn more at evcodriver.com.

Contact

API Support

support@evcodriver.com

Terms of Service

https://navagis.com/evcodriver-api/terms-of-service/

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

1.0.0

Queries

car

Description

Lookup the make, model, and range of a specific car id returned from the Cars query. This is also required when creating a route.

See the 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": 123,
      "range": 123,
      "trim": "example string",
      "option": "example string"
    }
  }
}
Queries

cars

Description

The cars endpoint returns the most recent list of the currently supported vehicles. Use the returned list to filter unwanted vehicles, or to find your match.

Use the cars query to return the most recent list of the currently supported vehicles in EVCoDriver. You can then use the returned list to filter unwanted vehicles, or to find the ID assigned for your interested vehicle.

Response

Returns [Car]

Example

Query
query Cars {
  cars {
    id
    make
    model
    year
    range
    trim
    option
  }
}
Response
{
  "data": {
    "cars": [
      {
        "id": "4",
        "make": "example string",
        "model": "example string",
        "year": 987,
        "range": 987,
        "trim": "example string",
        "option": "example string"
      }
    ]
  }
}
Queries

networkBrands

Description

Similar to the Cars endpoint, this returns a list of supported EV Charging Station brands. Use networkBrands to filter unwanted charge station brands and to match specific brands when creating a route.

Response

Returns [NetworkBrand]

Example

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

route

Description

The heart of the EVCoDriver API, querying the route endpoint returns a Route that is optimized for EV driving, and is customized according to the parameters you send it.

Vehicle-specific characteristics are determined by the Car id, overall route time and necessary charging stops are determined by the start, destination and waypoints in between, if any.

Wait times are determined by a live feed of station status data along the route, such as state of service (i.e. out of order), number of charge ports available, and more.

Response

Returns a Route!

Arguments
Name Description
start - LocationInput! Coordinates of the starting point
destination - LocationInput! Coordinates of the destination
waypoints - [LocationInput!] (Optional) Additional waypoints along the route, if any.
startSoc - Float! Battery level (or state of charge, SOC) at the start of the trip as a percentage. Value must be greater than 0 and a maximum of 1.
carId - ID! The specific Car ID to use for this route. See cars endpoint to get a list of usable IDs
batteryBuffer - BatteryBuffer! The desired battery level at the end of the route. See BatteryBuffer for details
brands - [String] (Optional) Specifies the charge station brands to consider for this route. By default all brands are included.

Check the networkBrands query for the list of supported brands.

Example

Query
query Route(
  $start: LocationInput!,
  $destination: LocationInput!,
  $waypoints: [LocationInput!],
  $startSoc: Float!,
  $carId: ID!,
  $batteryBuffer: BatteryBuffer!,
  $brands: [String]
) {
  route(
    start: $start,
    destination: $destination,
    waypoints: $waypoints,
    startSoc: $startSoc,
    carId: $carId,
    batteryBuffer: $batteryBuffer,
    brands: $brands
  ) {
    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": 0.65,
  "carId": 4,
  "batteryBuffer": "HIGH",
  "brands": ["example string"]
}
Response
{
  "data": {
    "route": {
      "totalDistance": 987.65,
      "totalTime": 123.45,
      "legs": [Leg],
      "message": "example string",
      "batteryBuffer": "HIGH",
      "polyLine": PolyLine
    }
  }
}

Types

BatteryBuffer

Description

A rough order of magnitude value of the 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

Car

Description

The Car type is used to represent a vehicle.

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": 214,
  "make": "BMW",
  "model": "i3s",
  "year": 2021,
  "range": 153,
  "trim": "example string",
  "option": "example string"
}
Types

ChargeStation

Description

The ChargeStation type is specific waypoint type that represents a charge station location. A charge station will have at least one charger and may have multiple chargers, similar to a gas station. The unique details of the actual station are returned in the station element.

Calculated SOC details are also returned, such as the estimated SOC at this waypoint, the suggested level to charge to before leaving, and the expected charge time needed.

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": 123.45,
  "plannedSoc": 123.45,
  "station": Station,
  "chargeTime": 123.45
}
Types

Charger

Description

The Charger type is used to represent an individual, physical charger. Similar to a fuel pump, chargers may have one connector or multiple connectors.

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

Live status of an individual charger. Check out the OCPI charging status list for more details.

NOTE: not all charge stations share their live status.

Values
Enum Value Description

AVAILABLE

BLOCKED

CHARGING

INOPERATIVE

OUTOFORDER

PLANNED

REMOVED

RESERVED

UNKNOWN

NODATA
Example
"AVAILABLE"
Types

Connector

Description

Charging stations have at least one connector, some have more. The Connector type describes the unique details of an individual connector at a charnge station.

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": 123.45
}
Types

Leg

Definition
Description

Routes are broken up into legs, or sections. Longer routes have more legs than shorter ones.

The Leg type provides key information about that part of the route, such as the length of that leg, the expected amount of time that will be spent driving that leg, and so on.

Fields
Field Name Description
totalDistance - Float! Total distance in meters for this leg
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": 123.45,
  "start": Location,
  "destination": Location,
  "startSoc": 987.65,
  "endSoc": 987.65,
  "charges": [ChargeStation]
}
Types

Location

Description

The Location type lets you easily define lat/long coordinates for easier use.

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

LocationInput

Description

The Location type lets you easily define lat/long coordinates for easier use.

Fields
Input Field Description
lat - Float!

latitude
lng - Float!

longitude
Example
{"lat": 987.65, "lng": 987.65}
Types

NetworkBrand

Description

The NetworkBrand type is used to represent charge point operator.

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
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

Route

Description

The Route type is returned in response to a route query, and defines all of the returnable elements of a route.

Fields
Field Name Description
totalDistance - Float! Total distance in meters from the start point to the destination.
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 Desired battery level on arrival at destination. Please see BatteryBufferfor more details.
polyLine - PolyLine! See Polyline type
Example
{
  "totalDistance": 123.45,
  "totalTime": 123.45,
  "legs": [Leg],
  "message": "example string",
  "batteryBuffer": "HIGH",
  "polyLine": PolyLine
}
Types

StaticLocation

Description

The StaticLocation type is used to provide real-world metadata about a unique location, such as a charge station. It uses a Locatoin type, as well as an address and timezone.

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

Description

Charging stations are represented by the Station type.

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
Example
{
  "id": 4,
  "label": "example string",
  "staticLocation": StaticLocation,
  "stationInfo": StationInfo,
  "stationStatus": StationStatus,
  "chargers": [Charger],
  "displayLabel": "example string"
}
Types

StationAvailability

Description

A string representing the current status of a station.

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

Description

A type used to represent ownership details of a charging station.

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

StationStatus

Description

The StationStatus type combines the current StationAvailability status with the estimated wait time before a charger is available.

This is useful when selecting the best location for a charge, or for presenting options to an end user.

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"}