Getting Started with EVPassport's API

Short introduction to our API and OCPI

The API documented in this site, is based on a protocol named OCPI (Open Charge Point Interface), which is a standard currently maintained by the EVRoaming Foundation (Go check them out at: https://evroaming.org/ocpi-background).

The aim of this standard is to keep a well supported communication system between those providers wanting to bring charging services to their end customers / drivers (EMSPs) and those systems that actually manage and control the operations of the Charging Devices (CPO).

In this case, EVPassport's system and API would constitute the CPO (Charge Point Operator) role, and if you are interested in using our API, you are most likely to fall under the EMSP (eMovility Service Provider) role, or any other identified by the OCPI Specification.

As a summary, most of the operations available in our API, may be quickly identified as those exposed in the OCPI Specification, as those to be implemented by a CPO (RECEIVER), and your role or expected usage of the API will most of the type be recognized by that of an EMSP (SENDER). So, if you want to deeply understand the inner workings of the system, we recommend that you check out the OCPI Specification itself (We are currently using version 2.2.1 of the Protocol).

Signing Up

To be able to access most of our our API's Operations, you will first need to get into contact with us ([email protected]) in order to get a registration Token (Well Known as Token A in OCPI) with which you might register yourself as a consumer of our API Services (Most likely, as what is well known in OCPI as EMSP).

With this private token (Token A), you may register as a third party consumer of our API, using the https://docs.evpassport.com/p/reference/register endpoint, supplying your own business data with it. In this request, you, as an EMSP, would provide us with the Token B, which will be the one we would use as CPO to contact your system from there onwards.

By doing this, we would, as CPO, generate another Token (Known as Token C in OCPI), which would be the one you need to use to access all other operations in the API. You may at any point use the Credentials module to consult or modify this information, or even to deregister from our CPO as a consumer / provider.

Summary of available operations

Locations

A location is the basic and most important unit on data when wanting to gather information on the Charge Stations available for use in our CPO. A location represents a physical place (Almost always, with its own corresponding coordinates), in which there are some EVSEs installed.

An EVSE (Electric Vehicle Supply Equipment) is considered as an independent Charge Unit, capable of charging at least and at most a single Electric Vehicle (EV). This means that, for most chargers, the EVSE represents the physical charger itself, but for those chargers capable of charging more than one EV at a time, we usually have it split as 2 independent EVSEs in the location (Again, each one of these may independently charge and have their own ongoing charging sessions at the same time, even if they are physically attached to the same charging unit).

With this module of the API, you may consult all information regarding a whole location, or any of its available EVSEs, with their charging specifications, their current state and availability, etc. This is usually data that you would present to your own customers, so that they may choose an EVSE they would like to use in any location.

Commands

These commands would allow your system to send the required operations to the specific EVSEs, for example, to initiate or stop a charging session for one of our customers.

Sessions

Allow you to get further information on ongoing charging sessions, or those that have already finished. If you want to get receipt-like data, for finished sessions, we suggest that you rather use the CDRS module, even if the information will be quite similar to the one presented in this module.

Tokens

Allow you to handle the Identifiers for your drivers / customers making use of the CPO, in a way that you may correlate which session correspond to which user. This will also allow you to control which users are authorized for charging in our CPO.

CDRS

Contains information on finished sessions and their payment information. Similar to a charging session invoice. This is the kind of information that you may want to sent to your own users as a finishing step for their charging sessions, or maybe as monthly invoice, and so on.