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

support@evcodriver.com

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

Queries

authorizationNetworks

Description

Requires authorization token with "authrizationNetwork" 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": 123,
      "range": 987,
      "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.
Please call this API to get the ID assigned per car and call route API.

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

Example

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

Mutations

refreshToken

Description

Create (or refresh) jwt.
Created token should be set in the request header as "authorization" property for each API call.
ex)
header: {
...other_header_properties,
authorization: "{set_token_here}"
}

Response

Returns a JWTResponse

Arguments
Name Description
id - String! User id (uuid)
key - String! Encrypted api key

Example

Query
mutation RefreshToken(
  $id: String!,
  $key: String!
) {
  refreshToken(
    id: $id,
    key: $key
  ) {
    token
  }
}
Variables
{
  "id": "example string",
  "key": "example string"
}
Response
{
  "data": {
    "refreshToken": {
      "token": "example string"
    }
  }
}

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": 987,
  "range": 123,
  "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": 123.45,
  "plannedSoc": 123.45,
  "station": Station,
  "chargeTime": 987.65
}
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
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

Float

Description

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

Example
987.65
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": 987.65,
  "totalTime": 123.45,
  "start": Location,
  "destination": Location,
  "startSoc": 123.45,
  "endSoc": 123.45,
  "charges": [ChargeStation]
}
Types

Location

Fields
Field Name Description
lat - Float! latitude
lng - Float! longitude
Example
{"lat": 987.65, "lng": 123.45}
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

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 Desired battery level on arrival at destination. Please see BatteryBufferfor more details.
polyLine - PolyLine! See Polyline type
Example
{
  "totalDistance": 987.65,
  "totalTime": 987.65,
  "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