API docs by Redocly

OCPI 2.3.0 - CPO Interface (2.3.0)

Download OpenAPI specification:

License: OCPI
OCPI 2.3.0 Specification

Credentials

Get credentials

Retrieves the credentials object to access the server's platform. The request body is empty, the response contains the credentials object to access the server's platform. This credentials object also contains extra information about the server such as its business details.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {}
}

Register (credentials exchange)

Provides the server with credentials to access the client's system. This credentials object also contains extra information about the client such as its business details.

A POST initiates the registration process for this endpoint's version. The server must also fetch the client's endpoints for this version.

If successful, the server must generate a new credentials token and respond with the client's new credentials to access the server's system.

This method MUST return a HTTP status code 405: method not allowed if the client has already been registered before.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

Request Body schema: application/json
required

Credentials object containing the client's credentials and business details.

token
required
string <= 64 characters

The credentials token for the other party to authenticate in your system. It should only contain printable non-whitespace ASCII characters, that is, characters with Unicode code points from the range of U+0021 up to and including U+007E.

url
required
string <uri>

The URL to your API versions endpoint.

hub_party_id
string = 5 characters

The Hub party of this platform. The two-letter country code and three-character party ID are concatenated together in this field as one five-character string (CiString).

required
Array of objects (CredentialsRole) non-empty

List of the roles this party provides. A platform can have the same role more than once, each with its own unique party_id and country_code, for example when a CPO provides 'white-label' services for 'virtual' CPOs.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {}
}

Update credentials

Provides the server with updated credentials to access the client's system. This credentials object also contains extra information about the client such as its business details.

A PUT will switch to the version that contains this credentials endpoint if it's different from the current version. The server must fetch the client's endpoints again, even if the version has not changed.

If successful, the server must generate a new credentials token for the client and respond with the client's updated credentials to access the server's system.

This method MUST return a HTTP status code 405: method not allowed if the client has not been registered yet.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

Request Body schema: application/json
required

Updated credentials object.

token
required
string <= 64 characters

The credentials token for the other party to authenticate in your system. It should only contain printable non-whitespace ASCII characters, that is, characters with Unicode code points from the range of U+0021 up to and including U+007E.

url
required
string <uri>

The URL to your API versions endpoint.

hub_party_id
string = 5 characters

The Hub party of this platform. The two-letter country code and three-character party ID are concatenated together in this field as one five-character string (CiString).

required
Array of objects (CredentialsRole) non-empty

List of the roles this party provides. A platform can have the same role more than once, each with its own unique party_id and country_code, for example when a CPO provides 'white-label' services for 'virtual' CPOs.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {}
}

Unregister (invalidate credentials)

Informs the server that its credentials to access the client's system are now invalid and can no longer be used. Both parties must end any automated communication. This is the unregistration process.

This method MUST return a HTTP status code 405: method not allowed if the client has not been registered before.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

Versions

Get supported OCPI versions

This endpoint lists all the available OCPI versions and the corresponding URLs to where version specific details such as the supported endpoints can be found.

The exact URL to the implemented version endpoint should be given (offline) to parties that want to communicate with your OCPI implementation.

Both, CPOs and eMSPs MUST implement such a version endpoint.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": []
}

Get version details

Via the version details, the parties can exchange which modules are implemented for a specific version of OCPI, which interface role is implemented, and what the endpoint URL is for this interface.

Parties that are both CPO and eMSP (or a Hub) can implement one version endpoint that covers both roles. With the information that is available in the version details, parties don’t need to implement a separate endpoint per role (CPO or eMSP) anymore. In practice this means that when a company is both a CPO and an eMSP and it connects to another party that implements both interfaces, only one OCPI connection is needed.

No structure defined. This is open for every party to define themselves.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Locations

Get list of Locations

Fetch a list of Locations (paginated) and optionally filter on last_updated using date_from/date_to.

If the optional parameters date_from and/or date_to are provided, only Locations with last_updated between the given date_from (including) and date_to (excluding) will be returned.

In order for this to work properly, the following logic MUST be implemented accordingly: If an EVSE is updated, also the 'parent' Location's last_updated field needs to be updated. Similarly, if a Connector is updated, the EVSE's last_updated and the Location's last_updated fields need to be updated.

Authorizations:
ocpiAuthorization
query Parameters
date_from
string <date-time>

Only return objects that have last_updated after or equal to this Date/Time (inclusive).

date_to
string <date-time>

Only return objects that have last_updated up to this Date/Time, but not including (exclusive).

limit
integer >= 1

Maximum number of objects to GET.

offset
integer >= 0
Default: 0

The offset of the first object returned. Default is 0.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": [
    ]
}

Get a Location

Retrieve a specific Location object by its location_id.

Authorizations:
ocpiAuthorization
path Parameters
location_id
required
string <= 36 characters

Location.id of the Location object to retrieve or update.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Get an EVSE

Retrieve a specific EVSE object by its location_id and evse_uid.

Authorizations:
ocpiAuthorization
path Parameters
location_id
required
string <= 36 characters

Location.id of the Location object to retrieve or update.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE object to retrieve or update.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Get a Connector

Retrieve a specific Connector object by its location_id, evse_uid and connector_id.

Authorizations:
ocpiAuthorization
path Parameters
location_id
required
string <= 36 characters

Location.id of the Location object to retrieve or update.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE object to retrieve or update.

connector_id
required
string <= 36 characters

Connector.id of the Connector object to retrieve or update.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Sessions

Get list of Sessions

Fetch a list of Sessions from the CPO system (paginated).

Only Sessions with last_updated between the given date_from (including) and date_to (excluding) will be returned.

Authorizations:
ocpiAuthorization
query Parameters
date_from
string <date-time>

Only return objects that have last_updated after or equal to this Date/Time (inclusive).

date_to
string <date-time>

Only return objects that have last_updated up to this Date/Time, but not including (exclusive).

limit
integer >= 1

Maximum number of objects to GET.

offset
integer >= 0
Default: 0

The offset of the first object returned. Default is 0.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": [
    ]
}

Set Charging Preferences

Set/update the driver's Charging Preferences for this charging session.

The /charging_preferences URL suffix is required when setting Charging Preferences.

Authorizations:
ocpiAuthorization
path Parameters
session_id
required
string <= 36 characters

Session.id of the Session object.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

Updated Charging Preferences of the driver for this Session.

profile_type
required
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Type of Smart Charging Profile selected by the driver. The ProfileType has to be supported at the Connector and for every supported ProfileType, a Tariff MUST be provided. This gives the EV driver the option between different pricing options.

departure_time
string <date-time>

Expected departure. The driver has given this Date/Time as expected departure moment. It is only an estimation and not necessarily the Date/Time of the actual departure.

energy_need
number

Requested amount of energy in kWh. The EV driver wants to have this amount of energy charged.

discharge_allowed
boolean

The driver allows their EV to be discharged when needed, as long as the other preferences are met: EV is charged with the preferred energy (energy_need) until the preferred departure moment (departure_time). Default if omitted: false.

Responses

Request samples

Content type
application/json
{
  • "profile_type": "CHEAP",
  • "departure_time": "2019-08-24T14:15:22Z",
  • "energy_need": 0,
  • "discharge_allowed": true
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": "ACCEPTED"
}

CDRs

Get list of CDRs

Fetch CDRs from the CPO's system. If additional parameters date_from and/or date_to are provided, only CDRs with last_updated between the given date_from (including) and date_to (excluding) will be returned. This request is paginated.

Authorizations:
ocpiAuthorization
query Parameters
date_from
string <date-time>

Only return objects that have last_updated after or equal to this Date/Time (inclusive).

date_to
string <date-time>

Only return objects that have last_updated up to this Date/Time, but not including (exclusive).

offset
integer >= 0
Default: 0

The offset of the first object returned. Default is 0.

limit
integer >= 1

Maximum number of objects to GET.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": [
    ]
}

Tariffs

Get list of Tariffs

Fetch information about all Tariffs. If additional parameters date_from and/or date_to are provided, only Tariffs with last_updated between the given date_from (including) and date_to (excluding) will be returned. This request is paginated.

Authorizations:
ocpiAuthorization
query Parameters
date_from
string <date-time>

Only return objects that have last_updated after or equal to this Date/Time (inclusive).

date_to
string <date-time>

Only return objects that have last_updated up to this Date/Time, but not including (exclusive).

offset
integer >= 0
Default: 0

The offset of the first object returned. Default is 0.

limit
integer >= 1

Maximum number of objects to GET.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": [
    ]
}

Tokens

Retrieve a Token

If the eMSP wants to check the status of a Token in the CPO system it might GET the object from the CPO system for validation purposes. The eMSP is the owner of the objects, so it would be illogical if the CPO system had a different status or was missing an object.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

token_uid
required
string <= 36 characters

Token.uid of the Token object.

query Parameters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Token.type of the Token to retrieve. Default if omitted: RFID

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Create or update a Token

New or updated Token objects are pushed from the eMSP to the CPO.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

token_uid
required
string <= 36 characters

Token.uid of the Token object.

query Parameters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Token.type of the Token to retrieve. Default if omitted: RFID

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

New or updated Token object.

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the MSP that 'owns' this Token.

party_id
required
string = 3 characters

ID of the eMSP that 'owns' this Token (following the ISO-15118 standard).

uid
required
string <= 36 characters

Unique ID by which this Token, combined with the Token type, can be identified. This is the field used by CPO system (RFID reader on the Charge Point) to identify this token. Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the RFID reader, but that is not a requirement. If this is a APP_USER or AD_HOC_USER Token, it will be a uniquely, by the eMSP, generated ID. This field is named uid instead of id to prevent confusion with: contract_id.

type
required
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Type of the token

contract_id
required
string <= 36 characters

Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/).

visual_number
string <= 64 characters

Visual readable number/identification as printed on the Token (RFID card), might be equal to the contract_id.

issuer
required
string <= 64 characters

Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP.

group_id
string <= 36 characters

This ID groups a couple of tokens. This can be used to make two or more tokens work as one, so that a session can be started with one token and stopped with another, handy when a card and key-fob are given to the EV-driver. Beware that OCPP 1.5/1.6 only support group_ids (it is called parentId in OCPP 1.5/1.6) with a maximum length of 20.

valid
required
boolean

Is this Token valid

whitelist
required
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Indicates what type of white-listing is allowed.

language
string = 2 characters

Language Code ISO 639-1. This optional field indicates the Token owner's preferred interface language. If the language is not provided or not supported then the CPO is free to choose its own language.

default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

The default Charging Preference. When this is provided, and a charging session is started on an Charge Point that support Preference base Smart Charging and support this ProfileType, the Charge Point can start using this ProfileType, without this having to be set via: Set Charging Preferences.

object (EnergyContract)

When the Charge Point supports using your own energy supplier/contract at a Charge Point, information about the energy supplier/contract is needed so the CPO knows which energy supplier to use. NOTE: In a lot of countries it is currently not allowed/possible to use a drivers own energy supplier/contract at a Charge Point.

last_updated
required
string <date-time>

Timestamp when this Token was last updated (or created).

Responses

Request samples

Content type
application/json
{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

Partially update a Token

Same as the PUT method, but only the fields/objects that have to be updated have to be present, other fields/objects that are not specified are considered unchanged. Any request to the PATCH method SHALL contain the last_updated field.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

token_uid
required
string <= 36 characters

Token.uid of the Token object.

query Parameters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Token.type of the Token to retrieve. Default if omitted: RFID

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

Partial Token object with only the fields to update.

country_code
string = 2 characters
party_id
string = 3 characters
uid
string <= 36 characters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

The type of token.

contract_id
string <= 36 characters
visual_number
string <= 64 characters
issuer
string <= 64 characters
group_id
string <= 36 characters
valid
boolean
whitelist
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Defines when authorization of a Token by the CPO is allowed.

language
string = 2 characters
default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Different smart charging profile types.

object (EnergyContract)

Information about an energy contract that belongs to a Token so a driver could use his/her own energy contract when charging at a Charge Point.

last_updated
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

Commands

Cancel a reservation

Request the Charge Point to cancel a specific reservation.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between CancelReservation requests.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Charge Point already has a reservation that matches this reservationId the Charge Point will replace the reservation.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Reserve an EVSE

Request the Charge Point to reserve a (specific) EVSE for a Token.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between ReserveNow requests.

required
object (Token)

Token object for how to reserve this Charge Point (and specific EVSE).

expiry_date
required
string <date-time>

The Date/Time when this reservation ends, in UTC.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Receiver (typically CPO) Point already has a reservation that matches this reservationId for that Location it will replace the reservation.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) for which to reserve an EVSE.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location if a specific EVSE has to be reserved.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

Responses

Request samples

Content type
application/json
{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "expiry_date": "2019-08-24T14:15:22Z",
  • "reservation_id": "string",
  • "location_id": "string",
  • "evse_uid": "string",
  • "authorization_reference": "string"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Start a session

Request the Charge Point to start a transaction on the given EVSE/Connector.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StartSession requests.

required
object (Token)

Token object the Charge Point has to use to start a new session. The Token provided in this request is authorized by the eMSP.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) on which a session is to be started.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location on which a session is to be started. Required when connector_id is set.

connector_id
string <= 36 characters

Optional Connector.id of the Connector of the EVSE on which a session is to be started. This field is required when the capability START_SESSION_CONNECTOR_REQUIRED is set on the EVSE.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

Responses

Request samples

Content type
application/json
{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string",
  • "authorization_reference": "string"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Stop a session

Request the Charge Point to stop an ongoing session.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StopSession requests.

session_id
required
string <= 36 characters

Session.id of the Session that is requested to be stopped.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Unlock a connector

Request the Charge Point to unlock the connector.

Authorizations:
ocpiAuthorization
header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required
response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between UnlockConnector requests.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) of which it is requested to unlock the connector.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE of this Location of which it is requested to unlock the connector.

connector_id
required
string <= 36 characters

Connector.id of the Connector of this Location of which it is requested to unlock.

Responses

Request samples

Content type
application/json
{
  • "response_url": "http://example.com",
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

ChargingProfiles

Get the ActiveChargingProfile for a session

Retrieves the ActiveChargingProfile as it is currently planned for the the given session.

Authorizations:
ocpiAuthorization
path Parameters
session_id
required
string <= 36 characters

Session.id of the Session object.

query Parameters
duration
required
integer

Length of the requested ActiveChargingProfile in seconds. Balance the duration between maximizing the information gained and the data usage and computation to execute on the request. Warning: asking for longer duration than necessary might result in additional data costs, while its added value diminishes with every change in the schedule.

response_url
required
string <uri>

URL that the ActiveChargingProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between GET ActiveChargingProfile requests.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Create or update a ChargingProfile for a session

Creates a new ChargingProfile on a session, or replaces an existing ChargingProfile on the EVSE.

Authorizations:
ocpiAuthorization
path Parameters
session_id
required
string <= 36 characters

Session.id of the Session object.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

SetChargingProfile object with information needed to set/update the Charging Profile for a session.

required
object (ChargingProfile)

Contains limits for the available power or current over time.

response_url
required
string <uri>

URL that the ChargingProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between GET ActiveChargingProfile requests.

Responses

Request samples

Content type
application/json
{
  • "charging_profile": {
    },
  • "response_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Clear a ChargingProfile for a session

Clears the ChargingProfile set by the eMSP on the given session.

Authorizations:
ocpiAuthorization
path Parameters
session_id
required
string <= 36 characters

Session.id of the Session object.

query Parameters
response_url
required
string <uri>

URL that the ClearProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between DELETE ChargingProfile requests.

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Schemas

OCPIResponse

status_code
required
integer

OCPI status code, 1000 for success.

status_message
string

An optional status message which may help when debugging.

timestamp
required
string <date-time>

The time this message was generated.

data
any

Response data object or list of objects.

{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

Role

string <enum> (Role)
Enum Description
CPO

Charge Point Operator Role.

EMSP

eMobility Service Provider Role.

NAP

National Access Point Role (national Database with all Location information of a country).

NSP

Navigation Service Provider Role, role like an eMSP (probably only interested in Location information).

OTHER

Other role.

SCSP

Smart Charging Service Provider Role.

The role of a party in the OCPI ecosystem.

"CPO"

ImageCategory

string <open-enum> (ImageCategory)
Enum Description
CHARGER

Photo of the physical device that contains one or more EVSEs.

ENTRANCE

Location entrance photo. Should show the car entrance to the location from street side.

LOCATION

Location overview photo.

NETWORK

Logo of an associated roaming network to be displayed with the EVSE for example in lists, maps and detailed information views.

OPERATOR

Logo of the charge point operator, for example a municipality, to be displayed in the EVSEs detailed information view or in lists and maps, if no network logo is present.

OTHER

Other

OWNER

Logo of the charge point owner, for example a local store, to be displayed in the EVSEs detailed information view.

The category of an image to obtain the correct usage in a user presentation. The category has to be set accordingly to the image content in order to guarantee the right usage.

"CHARGER"

Image

url
required
string <uri>

URL from where the image data can be fetched through a web browser.

thumbnail
string <uri>

URL from where a thumbnail of the image can be fetched through a web browser.

category
required
string <open-enum> (ImageCategory)
Enum Description
CHARGER

Photo of the physical device that contains one or more EVSEs.

ENTRANCE

Location entrance photo. Should show the car entrance to the location from street side.

LOCATION

Location overview photo.

NETWORK

Logo of an associated roaming network to be displayed with the EVSE for example in lists, maps and detailed information views.

OPERATOR

Logo of the charge point operator, for example a municipality, to be displayed in the EVSEs detailed information view or in lists and maps, if no network logo is present.

OTHER

Other

OWNER

Logo of the charge point owner, for example a local store, to be displayed in the EVSEs detailed information view.

Describes what the image is used for.

type
required
string <= 4 characters

Image type like: gif, jpeg, png, svg.

width
integer

Width of the full scale image.

height
integer

Height of the full scale image.

{}

BusinessDetails

name
required
string <= 100 characters

Name of the operator.

website
string <uri>

Link to the operator's website.

object (Image)

Image link to the operator's logo.

{}

CredentialsRole

role
required
string <enum> (Role)
Enum Description
CPO

Charge Point Operator Role.

EMSP

eMobility Service Provider Role.

NAP

National Access Point Role (national Database with all Location information of a country).

NSP

Navigation Service Provider Role, role like an eMSP (probably only interested in Location information).

OTHER

Other role.

SCSP

Smart Charging Service Provider Role.

Type of role.

required
object (BusinessDetails)

Details of this party.

party_id
required
string = 3 characters

CPO, eMSP (or other role) ID of this party (following the ISO-15118 standard).

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the country this party is operating in.

{}

Credentials

token
required
string <= 64 characters

The credentials token for the other party to authenticate in your system. It should only contain printable non-whitespace ASCII characters, that is, characters with Unicode code points from the range of U+0021 up to and including U+007E.

url
required
string <uri>

The URL to your API versions endpoint.

hub_party_id
string = 5 characters

The Hub party of this platform. The two-letter country code and three-character party ID are concatenated together in this field as one five-character string (CiString).

required
Array of objects (CredentialsRole) non-empty

List of the roles this party provides. A platform can have the same role more than once, each with its own unique party_id and country_code, for example when a CPO provides 'white-label' services for 'virtual' CPOs.

{}

VersionNumber

string <open-enum> (VersionNumber)
Enum Description
2.0

OCPI version 2.0

2.1

OCPI version 2.1 (DEPRECATED, do not use, use 2.1.1 instead)

2.1.1

OCPI version 2.1.1

2.2

OCPI version 2.2 (DEPRECATED, do not use, use 2.2.1 instead)

2.2.1

OCPI version 2.2.1

2.3.0

OCPI version 2.3.0 (this version)

List of known versions.

"2.0"

Version

version
required
string <open-enum> (VersionNumber)
Enum Description
2.0

OCPI version 2.0

2.1

OCPI version 2.1 (DEPRECATED, do not use, use 2.1.1 instead)

2.1.1

OCPI version 2.1.1

2.2

OCPI version 2.2 (DEPRECATED, do not use, use 2.2.1 instead)

2.2.1

OCPI version 2.2.1

2.3.0

OCPI version 2.3.0 (this version)

The version number.

url
required
string <uri>

URL to the endpoint containing version specific information.

{}

ModuleID

string <open-enum> (ModuleID)
Enum Description
cdrs

CDRs module

chargingprofiles

Charging Profiles module

commands

Commands module

credentials

Credentials & Registration module (required for all implementations). The role field has no function for this module.

hubclientinfo

Hub Client Info module

locations

Locations module

sessions

Sessions module

tariffs

Tariffs module

tokens

Tokens module

bookings

Bookings module

payments

Payments module

The Module identifiers for each endpoint. Most modules (except Credentials & Registration) are optional, but there might be dependencies between modules. Parties are allowed to create custom modules with additional custom moduleIDs.

"cdrs"

InterfaceRole

string <enum> (InterfaceRole)
Enum Description
SENDER

Sender Interface implementation. Interface implemented by the owner of data, so the Receiver can Pull information from the data Sender/owner.

RECEIVER

Receiver Interface implementation. Interface implemented by the receiver of data, so the Sender/owner can Push information to the Receiver.

The interface role of an endpoint.

"SENDER"

Endpoint

identifier
required
string <open-enum> (ModuleID)
Enum Description
cdrs

CDRs module

chargingprofiles

Charging Profiles module

commands

Commands module

credentials

Credentials & Registration module (required for all implementations). The role field has no function for this module.

hubclientinfo

Hub Client Info module

locations

Locations module

sessions

Sessions module

tariffs

Tariffs module

tokens

Tokens module

bookings

Bookings module

payments

Payments module

Endpoint identifier.

role
required
string <enum> (InterfaceRole)
Enum Description
SENDER

Sender Interface implementation. Interface implemented by the owner of data, so the Receiver can Pull information from the data Sender/owner.

RECEIVER

Receiver Interface implementation. Interface implemented by the receiver of data, so the Sender/owner can Push information to the Receiver.

Interface role this endpoint implements.

url
required
string <uri>

URL to the endpoint.

{}

VersionDetails

version
required
string <open-enum> (VersionNumber)
Enum Description
2.0

OCPI version 2.0

2.1

OCPI version 2.1 (DEPRECATED, do not use, use 2.1.1 instead)

2.1.1

OCPI version 2.1.1

2.2

OCPI version 2.2 (DEPRECATED, do not use, use 2.2.1 instead)

2.2.1

OCPI version 2.2.1

2.3.0

OCPI version 2.3.0 (this version)

The version number.

required
Array of objects (Endpoint) non-empty

A list of supported endpoints for this version.

{
  • "version": "2.0",
  • "endpoints": []
}

TokenType

string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

The type of token.

"AD_HOC_USER"

PublishTokenType

uid
string <= 36 characters

Unique ID by which this Token can be identified.

type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Type of the token.

visual_number
string <= 64 characters

Visual readable number/identification as printed on the Token (RFID card).

issuer
string <= 64 characters

Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP.

group_id
string <= 36 characters

This ID groups a couple of tokens. This can be used to make two or more tokens work as one.

{
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string"
}

GeoLocation

latitude
required
string <= 10 characters ^-?[0-9]{1,2}\.[0-9]{5,7}$

Latitude of the point in decimal degree. Example 50.770774. Decimal separator "." required.

longitude
required
string <= 11 characters ^-?[0-9]{1,3}\.[0-9]{5,7}$

Longitude of the point in decimal degree. Example -126.104965. Decimal separator "." required.

{
  • "latitude": "string",
  • "longitude": "string"
}

DisplayText

language
required
string = 2 characters

Language Code ISO 639-1.

text
required
string <= 512 characters

Text to be displayed to an end user. No markup, html etc. allowed.

{
  • "language": "st",
  • "text": "string"
}

AdditionalGeoLocation

latitude
required
string <= 10 characters ^-?[0-9]{1,2}\.[0-9]{5,7}$

Latitude of the point in decimal degree. Example 50.770774. Decimal separator "." required.

longitude
required
string <= 11 characters ^-?[0-9]{1,3}\.[0-9]{5,7}$

Longitude of the point in decimal degree. Example -126.104965. Decimal separator "." required.

object (DisplayText)

Name of the point in local language or as written at the location. For example the street name of a parking lot entrance or its number.

{
  • "latitude": "string",
  • "longitude": "string",
  • "name": {
    }
}

ParkingType

string <open-enum> (ParkingType)
Enum Description
ALONG_MOTORWAY

Location on a parking facility/rest area along a motorway, freeway, interstate, highway etc.

PARKING_GARAGE

Multistorey car park.

PARKING_LOT

A cleared area that is intended for parking vehicles, i.e. at super markets, bars, etc.

ON_DRIVEWAY

Location is on the driveway of a house/building.

ON_STREET

Parking in public space along a street.

UNDERGROUND_GARAGE

Multistorey car park, mainly underground.

Reflects the general type of the charge point's location. May be used for user information.

"ALONG_MOTORWAY"

Status

string <enum> (Status)
Enum Description
AVAILABLE

The EVSE/Connector is able to start a new charging session.

BLOCKED

The EVSE/Connector is not accessible because of a physical barrier, i.e. a car.

CHARGING

The EVSE/Connector is in use.

INOPERATIVE

The EVSE/Connector is not yet active, or temporarily not available for use, but not broken or defect.

OUTOFORDER

The EVSE/Connector is currently out of order, some part/components may be broken/defect.

PLANNED

The EVSE/Connector is planned, will be operating soon.

REMOVED

The EVSE/Connector was discontinued/removed.

RESERVED

The EVSE/Connector is reserved for a particular EV driver and is unavailable for other drivers.

UNKNOWN

No status information available (also used when offline).

The status of an EVSE.

"AVAILABLE"

StatusSchedule

period_begin
required
string <date-time>

Begin of the scheduled period.

period_end
string <date-time>

End of the scheduled period, if known.

status
required
string <enum> (Status)
Enum Description
AVAILABLE

The EVSE/Connector is able to start a new charging session.

BLOCKED

The EVSE/Connector is not accessible because of a physical barrier, i.e. a car.

CHARGING

The EVSE/Connector is in use.

INOPERATIVE

The EVSE/Connector is not yet active, or temporarily not available for use, but not broken or defect.

OUTOFORDER

The EVSE/Connector is currently out of order, some part/components may be broken/defect.

PLANNED

The EVSE/Connector is planned, will be operating soon.

REMOVED

The EVSE/Connector was discontinued/removed.

RESERVED

The EVSE/Connector is reserved for a particular EV driver and is unavailable for other drivers.

UNKNOWN

No status information available (also used when offline).

Status value during the scheduled period.

{
  • "period_begin": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z",
  • "status": "AVAILABLE"
}

Capability

string <open-enum> (Capability)
Enum Description
CHARGING_PROFILE_CAPABLE

The EVSE supports charging profiles.

CHARGING_PREFERENCES_CAPABLE

The EVSE supports charging preferences.

CHIP_CARD_SUPPORT

EVSE has a payment terminal that supports chip cards.

CONTACTLESS_CARD_SUPPORT

EVSE has a payment terminal that supports contactless cards.

CREDIT_CARD_PAYABLE

EVSE has a payment terminal that makes it possible to pay for charging using a credit card.

DEBIT_CARD_PAYABLE

EVSE has a payment terminal that makes it possible to pay for charging using a debit card.

PED_TERMINAL

EVSE has a payment terminal with a pin-code entry device.

REMOTE_START_STOP_CAPABLE

The EVSE can remotely be started/stopped.

RESERVABLE

The EVSE can be reserved.

RFID_READER

Charging at this EVSE can be authorized with an RFID token.

START_SESSION_CONNECTOR_REQUIRED

When a StartSession is sent to this EVSE, the MSP is required to add the optional connector_id field in the StartSession object.

TOKEN_GROUP_CAPABLE

This EVSE supports token groups, two or more tokens work as one, so that a session can be started with one token and stopped with another (handy when a card and key-fob are given to the EV-driver).

UNLOCK_CAPABLE

Connectors have mechanical lock that can be requested by the eMSP to be unlocked.

The capabilities of an EVSE.

"CHARGING_PROFILE_CAPABLE"

ConnectorType

string <open-enum> (ConnectorType)
Enum Description
CHADEMO

The connector type is CHAdeMO, DC.

CHAOJI

The ChaoJi connector. The new generation charging connector, harmonized between CHAdeMO and GB/T. DC.

DOMESTIC_A

Standard/Domestic household, type "A", NEMA 1-15, 2 pins.

DOMESTIC_B

Standard/Domestic household, type "B", NEMA 5-15, 3 pins.

DOMESTIC_C

Standard/Domestic household, type "C", CEE 7/17, 2 pins.

DOMESTIC_D

Standard/Domestic household, type "D", 3 pin.

DOMESTIC_E

Standard/Domestic household, type "E", CEE 7/5 3 pins.

DOMESTIC_F

Standard/Domestic household, type "F", CEE 7/4, Schuko, 3 pins.

DOMESTIC_G

Standard/Domestic household, type "G", BS 1363, Commonwealth, 3 pins.

DOMESTIC_H

Standard/Domestic household, type "H", SI-32, 3 pins.

DOMESTIC_I

Standard/Domestic household, type "I", AS 3112, 3 pins.

DOMESTIC_J

Standard/Domestic household, type "J", SEV 1011, 3 pins.

DOMESTIC_K

Standard/Domestic household, type "K", DS 60884-2-D1, 3 pins.

DOMESTIC_L

Standard/Domestic household, type "L", CEI 23-16-VII, 3 pins.

DOMESTIC_M

Standard/Domestic household, type "M", BS 546, 3 pins.

DOMESTIC_N

Standard/Domestic household, type "N", NBR 14136, 3 pins.

DOMESTIC_O

Standard/Domestic household, type "O", TIS 166-2549, 3 pins.

GBT_AC

Guobiao GB/T 20234.2 AC socket/connector.

GBT_DC

Guobiao GB/T 20234.3 DC connector.

IEC_60309_2_single_16

IEC 60309-2 Industrial Connector single phase 16 amperes (usually blue).

IEC_60309_2_three_16

IEC 60309-2 Industrial Connector three phases 16 amperes (usually red).

IEC_60309_2_three_32

IEC 60309-2 Industrial Connector three phases 32 amperes (usually red).

IEC_60309_2_three_64

IEC 60309-2 Industrial Connector three phases 64 amperes (usually red).

IEC_62196_T1

IEC 62196 Type 1 "SAE J1772".

IEC_62196_T1_COMBO

Combo Type 1 based, DC.

IEC_62196_T2

IEC 62196 Type 2 "Mennekes".

IEC_62196_T2_COMBO

Combo Type 2 based, DC.

IEC_62196_T3A

IEC 62196 Type 3A.

IEC_62196_T3C

IEC 62196 Type 3C "Scame".

MCS

The MegaWatt Charging System (MCS) connector as developed by CharIN.

NEMA_5_20

NEMA 5-20, 3 pins.

NEMA_6_30

NEMA 6-30, 3 pins.

NEMA_6_50

NEMA 6-50, 3 pins.

NEMA_10_30

NEMA 10-30, 3 pins.

NEMA_10_50

NEMA 10-50, 3 pins.

NEMA_14_30

NEMA 14-30, 3 pins, rating of 30 A.

NEMA_14_50

NEMA 14-50, 3 pins, rating of 50 A.

PANTOGRAPH_BOTTOM_UP

On-board Bottom-up-Pantograph typically for bus charging.

PANTOGRAPH_TOP_DOWN

Off-board Top-down-Pantograph typically for bus charging.

SAE_J3400

SAE J3400, also known as North American Charging Standard (NACS), developed by Tesla, Inc in 2021.

TESLA_R

Tesla Connector "Roadster"-type (round, 4 pin).

TESLA_S

Tesla Connector "Model-S"-type (oval, 5 pin). Mechanically compatible with SAE J3400 but uses CAN bus for communication instead of power line communication.

The socket or plug standard of the charging point.

"CHADEMO"

ConnectorFormat

string <enum> (ConnectorFormat)
Enum Description
SOCKET

The connector is a socket; the EV user needs to bring a fitting plug.

CABLE

The connector is an attached cable; the EV users car needs to have a fitting inlet.

The format of the connector, whether it is a socket or a plug.

"SOCKET"

PowerType

string <enum> (PowerType)
Enum Description
AC_1_PHASE

AC single phase.

AC_2_PHASE

AC two phases, only two of the three available phases connected.

AC_2_PHASE_SPLIT

AC two phases using split phase system.

AC_3_PHASE

AC three phases.

DC

Direct Current.

The type of power at the connector.

"AC_1_PHASE"

ConnectorCapability

string <open-enum> (ConnectorCapability)
Enum Description
ISO_15118_2_PLUG_AND_CHARGE

The Connector supports authentication of the Driver using a contract certificate stored in the vehicle according to ISO 15118-2.

ISO_15118_20_PLUG_AND_CHARGE

The Connector supports authentication of the Driver using a contract certificate stored in the vehicle according to ISO 15118-20.

Functionalities that a Connector may or may not support.

"ISO_15118_2_PLUG_AND_CHARGE"

Connector

id
required
string <= 36 characters

Identifier of the Connector within the EVSE. Two Connectors may have the same id as long as they do not belong to the same EVSE object.

standard
required
string <open-enum> (ConnectorType)
Enum Description
CHADEMO

The connector type is CHAdeMO, DC.

CHAOJI

The ChaoJi connector. The new generation charging connector, harmonized between CHAdeMO and GB/T. DC.

DOMESTIC_A

Standard/Domestic household, type "A", NEMA 1-15, 2 pins.

DOMESTIC_B

Standard/Domestic household, type "B", NEMA 5-15, 3 pins.

DOMESTIC_C

Standard/Domestic household, type "C", CEE 7/17, 2 pins.

DOMESTIC_D

Standard/Domestic household, type "D", 3 pin.

DOMESTIC_E

Standard/Domestic household, type "E", CEE 7/5 3 pins.

DOMESTIC_F

Standard/Domestic household, type "F", CEE 7/4, Schuko, 3 pins.

DOMESTIC_G

Standard/Domestic household, type "G", BS 1363, Commonwealth, 3 pins.

DOMESTIC_H

Standard/Domestic household, type "H", SI-32, 3 pins.

DOMESTIC_I

Standard/Domestic household, type "I", AS 3112, 3 pins.

DOMESTIC_J

Standard/Domestic household, type "J", SEV 1011, 3 pins.

DOMESTIC_K

Standard/Domestic household, type "K", DS 60884-2-D1, 3 pins.

DOMESTIC_L

Standard/Domestic household, type "L", CEI 23-16-VII, 3 pins.

DOMESTIC_M

Standard/Domestic household, type "M", BS 546, 3 pins.

DOMESTIC_N

Standard/Domestic household, type "N", NBR 14136, 3 pins.

DOMESTIC_O

Standard/Domestic household, type "O", TIS 166-2549, 3 pins.

GBT_AC

Guobiao GB/T 20234.2 AC socket/connector.

GBT_DC

Guobiao GB/T 20234.3 DC connector.

IEC_60309_2_single_16

IEC 60309-2 Industrial Connector single phase 16 amperes (usually blue).

IEC_60309_2_three_16

IEC 60309-2 Industrial Connector three phases 16 amperes (usually red).

IEC_60309_2_three_32

IEC 60309-2 Industrial Connector three phases 32 amperes (usually red).

IEC_60309_2_three_64

IEC 60309-2 Industrial Connector three phases 64 amperes (usually red).

IEC_62196_T1

IEC 62196 Type 1 "SAE J1772".

IEC_62196_T1_COMBO

Combo Type 1 based, DC.

IEC_62196_T2

IEC 62196 Type 2 "Mennekes".

IEC_62196_T2_COMBO

Combo Type 2 based, DC.

IEC_62196_T3A

IEC 62196 Type 3A.

IEC_62196_T3C

IEC 62196 Type 3C "Scame".

MCS

The MegaWatt Charging System (MCS) connector as developed by CharIN.

NEMA_5_20

NEMA 5-20, 3 pins.

NEMA_6_30

NEMA 6-30, 3 pins.

NEMA_6_50

NEMA 6-50, 3 pins.

NEMA_10_30

NEMA 10-30, 3 pins.

NEMA_10_50

NEMA 10-50, 3 pins.

NEMA_14_30

NEMA 14-30, 3 pins, rating of 30 A.

NEMA_14_50

NEMA 14-50, 3 pins, rating of 50 A.

PANTOGRAPH_BOTTOM_UP

On-board Bottom-up-Pantograph typically for bus charging.

PANTOGRAPH_TOP_DOWN

Off-board Top-down-Pantograph typically for bus charging.

SAE_J3400

SAE J3400, also known as North American Charging Standard (NACS), developed by Tesla, Inc in 2021.

TESLA_R

Tesla Connector "Roadster"-type (round, 4 pin).

TESLA_S

Tesla Connector "Model-S"-type (oval, 5 pin). Mechanically compatible with SAE J3400 but uses CAN bus for communication instead of power line communication.

The standard of the installed connector.

format
required
string <enum> (ConnectorFormat)
Enum Description
SOCKET

The connector is a socket; the EV user needs to bring a fitting plug.

CABLE

The connector is an attached cable; the EV users car needs to have a fitting inlet.

The format (socket/cable) of the installed connector.

power_type
required
string <enum> (PowerType)
Enum Description
AC_1_PHASE

AC single phase.

AC_2_PHASE

AC two phases, only two of the three available phases connected.

AC_2_PHASE_SPLIT

AC two phases using split phase system.

AC_3_PHASE

AC three phases.

DC

Direct Current.

The type of power at the connector.

max_voltage
required
integer

Maximum voltage of the connector (line to neutral for AC_3_PHASE), in volt [V]. For example DC Chargers might vary the voltage during charging when battery almost full.

max_amperage
required
integer

Maximum amperage of the connector, in ampere [A].

max_electric_power
integer

Maximum electric power that can be delivered by this connector, in Watts (W). When the maximum electric power is lower than the calculated value from voltage and amperage, this value should be set.

tariff_ids
Array of strings[ items <= 36 characters ]

Identifiers of the currently valid charging tariffs. Multiple tariffs are possible, but only one of each Tariff.type can be active at the same time. Tariffs with the same type are only allowed if they are not active at the same time: start_date_time and end_date_time period not overlapping. For a "free of charge" tariff, this field should be set and point to a defined "free of charge" tariff.

terms_and_conditions
string <uri>

URL to the operator's terms and conditions.

capabilities
Array of strings <open-enum> (ConnectorCapability) [ items <open-enum > ]
Items Enum Description
ISO_15118_2_PLUG_AND_CHARGE

The Connector supports authentication of the Driver using a contract certificate stored in the vehicle according to ISO 15118-2.

ISO_15118_20_PLUG_AND_CHARGE

The Connector supports authentication of the Driver using a contract certificate stored in the vehicle according to ISO 15118-20.

A list of functionalities that the connector is capable of.

last_updated
required
string <date-time>

Timestamp when this Connector was last updated (or created).

{
  • "id": "string",
  • "standard": "CHADEMO",
  • "format": "SOCKET",
  • "power_type": "AC_1_PHASE",
  • "max_voltage": 0,
  • "max_amperage": 0,
  • "max_electric_power": 0,
  • "tariff_ids": [
    ],
  • "terms_and_conditions": "http://example.com",
  • "capabilities": [
    ],
  • "last_updated": "2019-08-24T14:15:22Z"
}

ParkingRestriction

string <open-enum> (ParkingRestriction)
Enum Description
CUSTOMERS

Parking spot for customers or guests only, for example in case of a hotel or shop.

DISABLED

Reserved parking spot for disabled people with valid ID.

EMPLOYEES

Parking only for people who work at a site, building, or complex that the Location belongs to.

EV_ONLY

Reserved parking spot for electric vehicles.

MOTORCYCLES

Parking spot only suitable for (electric) motorcycles or scooters.

PLUGGED

Parking is only allowed while plugged in (charging).

TAXIS

Parking only for taxi vehicles.

TENANTS

Parking only for people who live in a complex that the Location belongs to.

This value, if provided, represents the restriction to the parking spot for different purposes.

"CUSTOMERS"

EVSEPosition

string <enum> (EVSEPosition)
Enum Description
LEFT

The EVSE is to the left of the vehicle.

RIGHT

The EVSE is to the right of the vehicle when parked.

CENTER

The EVSE is at the center of the impassable narrow end of a parking space.

The position of an EVSE relative to the EVSE's parking space.

"LEFT"

EVSEParking

parking_id
required
string <= 36 characters

Reference to Parking.id.

evse_position
string <enum> (EVSEPosition)
Enum Description
LEFT

The EVSE is to the left of the vehicle.

RIGHT

The EVSE is to the right of the vehicle when parked.

CENTER

The EVSE is at the center of the impassable narrow end of a parking space.

Position of the EVSE relative to the parking place.

{
  • "parking_id": "string",
  • "evse_position": "LEFT"
}

EVSE

uid
required
string <= 36 characters

Uniquely identifies the EVSE within the CPOs platform (and suboperator platforms). This field can never be changed, modified or renamed. This is the 'technical' identification of the EVSE, not to be used as 'human readable' identification, use the field evse_id for that.

evse_id
string <= 48 characters

Compliant with the following specification for EVSE ID: "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/). Optional because: if an evse_id is to be re-used in the real world, the evse_id can be removed from an EVSE object if the status is set to REMOVED.

status
required
string <enum> (Status)
Enum Description
AVAILABLE

The EVSE/Connector is able to start a new charging session.

BLOCKED

The EVSE/Connector is not accessible because of a physical barrier, i.e. a car.

CHARGING

The EVSE/Connector is in use.

INOPERATIVE

The EVSE/Connector is not yet active, or temporarily not available for use, but not broken or defect.

OUTOFORDER

The EVSE/Connector is currently out of order, some part/components may be broken/defect.

PLANNED

The EVSE/Connector is planned, will be operating soon.

REMOVED

The EVSE/Connector was discontinued/removed.

RESERVED

The EVSE/Connector is reserved for a particular EV driver and is unavailable for other drivers.

UNKNOWN

No status information available (also used when offline).

Indicates the current status of the EVSE.

Array of objects (StatusSchedule)

Indicates a planned status update of the EVSE.

capabilities
Array of strings <open-enum> (Capability) [ items <open-enum > ]
Items Enum Description
CHARGING_PROFILE_CAPABLE

The EVSE supports charging profiles.

CHARGING_PREFERENCES_CAPABLE

The EVSE supports charging preferences.

CHIP_CARD_SUPPORT

EVSE has a payment terminal that supports chip cards.

CONTACTLESS_CARD_SUPPORT

EVSE has a payment terminal that supports contactless cards.

CREDIT_CARD_PAYABLE

EVSE has a payment terminal that makes it possible to pay for charging using a credit card.

DEBIT_CARD_PAYABLE

EVSE has a payment terminal that makes it possible to pay for charging using a debit card.

PED_TERMINAL

EVSE has a payment terminal with a pin-code entry device.

REMOTE_START_STOP_CAPABLE

The EVSE can remotely be started/stopped.

RESERVABLE

The EVSE can be reserved.

RFID_READER

Charging at this EVSE can be authorized with an RFID token.

START_SESSION_CONNECTOR_REQUIRED

When a StartSession is sent to this EVSE, the MSP is required to add the optional connector_id field in the StartSession object.

TOKEN_GROUP_CAPABLE

This EVSE supports token groups, two or more tokens work as one, so that a session can be started with one token and stopped with another (handy when a card and key-fob are given to the EV-driver).

UNLOCK_CAPABLE

Connectors have mechanical lock that can be requested by the eMSP to be unlocked.

List of functionalities that the EVSE is capable of.

required
Array of objects (Connector) non-empty

List of available connectors on the EVSE.

floor_level
string <= 4 characters

Level on which the Charge Point is located (in garage buildings) in the locally displayed numbering scheme.

object (GeoLocation)

Coordinates of the EVSE.

physical_reference
string <= 16 characters

A number/string printed on the outside of the EVSE for visual identification.

Array of objects (DisplayText)

Multi-language human-readable directions when more detailed information on how to reach the EVSE from the Location is required.

parking_restrictions
Array of strings <open-enum> (ParkingRestriction) [ items <open-enum > ]
Items Enum Description
CUSTOMERS

Parking spot for customers or guests only, for example in case of a hotel or shop.

DISABLED

Reserved parking spot for disabled people with valid ID.

EMPLOYEES

Parking only for people who work at a site, building, or complex that the Location belongs to.

EV_ONLY

Reserved parking spot for electric vehicles.

MOTORCYCLES

Parking spot only suitable for (electric) motorcycles or scooters.

PLUGGED

Parking is only allowed while plugged in (charging).

TAXIS

Parking only for taxi vehicles.

TENANTS

Parking only for people who live in a complex that the Location belongs to.

All applicable restrictions on who can charge at the EVSE, apart from those related to the vehicle type.

Array of objects (EVSEParking)

List of parking place references for this EVSE. New in OCPI 2.3.0.

accepted_service_providers
Array of strings[ items <= 50 characters ]

List of service provider identifiers accepted at this EVSE. New in OCPI 2.3.0.

Array of objects (Image)

Links to images related to the EVSE such as photos or logos.

last_updated
required
string <date-time>

Timestamp when this EVSE or one of its Connectors was last updated (or created).

{
  • "uid": "string",
  • "evse_id": "string",
  • "status": "AVAILABLE",
  • "status_schedule": [
    ],
  • "capabilities": [
    ],
  • "connectors": [
    ],
  • "floor_level": "stri",
  • "coordinates": {
    },
  • "physical_reference": "string",
  • "directions": [
    ],
  • "parking_restrictions": [
    ],
  • "parking": [
    ],
  • "accepted_service_providers": [
    ],
  • "images": [],
  • "last_updated": "2019-08-24T14:15:22Z"
}

VehicleType

string <open-enum> (VehicleType)
Enum Description
MOTORCYCLE

A motorcycle.

PERSONAL_VEHICLE

A personal vehicle, a passenger car.

PERSONAL_VEHICLE_WITH_TRAILER

A personal vehicle with a trailer attached.

VAN

A light-duty van with a height smaller than 275 cm.

SEMI_TRACTOR

A heavy-duty tractor unit without a trailer.

RIGID

A heavy-duty truck without an articulation point.

TRUCK_WITH_TRAILER

A heavy-duty truck (tractor or rigid) with a trailer attached.

BUS

A bus or a motor coach.

DISABLED

A vehicle with a permit for parking spaces for people with disabilities.

A categorization of vehicles to indicate which type of vehicles can use a certain EVSE.

"MOTORCYCLE"

ParkingDirection

string <enum> (ParkingDirection)
Enum Description
PARALLEL

Parking happens parallel to the roadway on which vehicles approach the EVSE.

PERPENDICULAR

Parking happens perpendicular to the roadway on which vehicles approach the EVSE.

ANGLE

Parking happens at an angle to the roadway on which vehicles approach the EVSE (i.e. echelon parking).

Indicates the direction in which parking occurs relative to the roadway on which vehicles approach the EVSE.

"PARALLEL"

Parking

id
required
string <= 36 characters

Unique identifier of the parking place.

physical_reference
string <= 12 characters

Physical reference (e.g. parking spot number).

vehicle_types
required
Array of strings <open-enum> (VehicleType) non-empty [ items <open-enum > ]
Items Enum Description
MOTORCYCLE

A motorcycle.

PERSONAL_VEHICLE

A personal vehicle, a passenger car.

PERSONAL_VEHICLE_WITH_TRAILER

A personal vehicle with a trailer attached.

VAN

A light-duty van with a height smaller than 275 cm.

SEMI_TRACTOR

A heavy-duty tractor unit without a trailer.

RIGID

A heavy-duty truck without an articulation point.

TRUCK_WITH_TRAILER

A heavy-duty truck (tractor or rigid) with a trailer attached.

BUS

A bus or a motor coach.

DISABLED

A vehicle with a permit for parking spaces for people with disabilities.

Types of vehicles that can use this parking place.

max_vehicle_weight
number

Maximum vehicle weight in kg.

max_vehicle_height
number

Maximum vehicle height in centimeters.

max_vehicle_length
number

Maximum vehicle length in centimeters.

max_vehicle_width
number

Maximum vehicle width in centimeters.

parking_space_length
number

Length of the parking space in centimeters.

parking_space_width
number

Width of the parking space in centimeters.

dangerous_goods_allowed
boolean

Whether dangerous goods are allowed.

direction
string <enum> (ParkingDirection)
Enum Description
PARALLEL

Parking happens parallel to the roadway on which vehicles approach the EVSE.

PERPENDICULAR

Parking happens perpendicular to the roadway on which vehicles approach the EVSE.

ANGLE

Parking happens at an angle to the roadway on which vehicles approach the EVSE (i.e. echelon parking).

Parking direction/orientation.

drive_through
boolean

Whether drive-through is possible.

restricted_to_type
required
boolean

Whether access is restricted to specific vehicle types.

reservation_required
required
boolean

Whether reservation is required.

time_limit
number

Maximum parking duration in minutes.

roofed
boolean

Whether the parking place is roofed.

Array of objects (Image)
lighting
boolean

Whether the parking place has lighting.

refrigeration_outlet
boolean

Whether a refrigeration outlet is available.

standards
Array of strings[ items <= 36 characters ]

A list of standards that the parking space conforms to, e.g. PAS 1899.

apds_reference
string

Reference to an Alliance for Parking Data Standards (APDS) element describing this parking. The referenced element may be a Place, Space or other hierarchy element defined by APDS.

{
  • "id": "string",
  • "physical_reference": "string",
  • "vehicle_types": [
    ],
  • "max_vehicle_weight": 0,
  • "max_vehicle_height": 0,
  • "max_vehicle_length": 0,
  • "max_vehicle_width": 0,
  • "parking_space_length": 0,
  • "parking_space_width": 0,
  • "dangerous_goods_allowed": true,
  • "direction": "PARALLEL",
  • "drive_through": true,
  • "restricted_to_type": true,
  • "reservation_required": true,
  • "time_limit": 0,
  • "roofed": true,
  • "images": [],
  • "lighting": true,
  • "refrigeration_outlet": true,
  • "standards": [
    ],
  • "apds_reference": "string"
}

Facility

string <open-enum> (Facility)
Enum Description
HOTEL

A hotel.

RESTAURANT

A restaurant.

CAFE

A cafe.

MALL

A mall or shopping center.

SUPERMARKET

A supermarket.

SPORT

Sport facilities: gym, field etc.

RECREATION_AREA

A recreation area.

NATURE

Located in, or close to, a park, nature reserve etc.

MUSEUM

A museum.

BIKE_SHARING

A bike/e-bike/e-scooter sharing location.

BUS_STOP

A bus stop.

TAXI_STAND

A taxi stand.

TRAM_STOP

A tram stop/station.

METRO_STATION

A metro station.

TRAIN_STATION

A train station.

AIRPORT

An airport.

PARKING_LOT

A parking lot.

CARPOOL_PARKING

A carpool parking.

FUEL_STATION

A Fuel station.

WIFI

Wifi or other type of internet available.

Facilities available at or near the charging location.

"HOTEL"

RegularHours

weekday
required
integer [ 1 .. 7 ]

Number of day in the week, from Monday (1) till Sunday (7).

period_begin
required
string^([0-1][0-9]|2[0-3]):[0-5][0-9]$

Begin of the regular period, in local time, given in hours and minutes. Must be in 24h format with leading zeros. Example "18:15".

period_end
required
string^([0-1][0-9]|2[0-3]):[0-5][0-9]$

End of the regular period, in local time, syntax as for period_begin. Must be later than period_begin.

{
  • "weekday": 1,
  • "period_begin": "string",
  • "period_end": "string"
}

ExceptionalPeriod

period_begin
required
string <date-time>

Begin of the exception. In UTC, time_zone field of the Location can be used to convert to local time.

period_end
required
string <date-time>

End of the exception. In UTC, time_zone field of the Location can be used to convert to local time.

{
  • "period_begin": "2019-08-24T14:15:22Z",
  • "period_end": "2019-08-24T14:15:22Z"
}

Hours

twentyfourseven
required
boolean

True to represent 24 hours a day and 7 days a week, except the given exceptions.

Array of objects (RegularHours)

Regular hours, weekday-based. Only to be used if twentyfourseven=false, then this field needs to contain at least one RegularHours object.

Array of objects (ExceptionalPeriod)

Exceptions for specified calendar dates, time-range based. Periods the station is operating/accessible. Additional to regular_hours. May overlap regular rules.

Array of objects (ExceptionalPeriod)

Exceptions for specified calendar dates, time-range based. Periods the station is not operating/accessible. Overwriting regular_hours and exceptional_openings.

{
  • "twentyfourseven": true,
  • "regular_hours": [
    ],
  • "exceptional_openings": [
    ],
  • "exceptional_closings": [
    ]
}

EnergySourceCategory

string <enum> (EnergySourceCategory)
Enum Description
NUCLEAR

Nuclear power sources.

GENERAL_FOSSIL

All kinds of fossil power sources.

COAL

Fossil power from coal.

GAS

Fossil power from gas.

GENERAL_GREEN

All kinds of regenerative power sources.

SOLAR

Regenerative power from PV.

WIND

Regenerative power from wind turbines.

WATER

Regenerative power from water turbines.

Categories of energy sources.

"NUCLEAR"

EnergySource

source
required
string <enum> (EnergySourceCategory)
Enum Description
NUCLEAR

Nuclear power sources.

GENERAL_FOSSIL

All kinds of fossil power sources.

COAL

Fossil power from coal.

GAS

Fossil power from gas.

GENERAL_GREEN

All kinds of regenerative power sources.

SOLAR

Regenerative power from PV.

WIND

Regenerative power from wind turbines.

WATER

Regenerative power from water turbines.

The type of energy source.

percentage
required
number

Percentage of this source (0-100) in the mix.

{
  • "source": "NUCLEAR",
  • "percentage": 0
}

EnvironmentalImpactCategory

string <open-enum> (EnvironmentalImpactCategory)
Enum Description
NUCLEAR_WASTE

Produced nuclear waste in grams per kilowatthour.

CARBON_DIOXIDE

Exhausted carbon dioxide in grams per kilowatthour.

Categories of environmental impact values.

"NUCLEAR_WASTE"

EnvironmentalImpact

category
required
string <open-enum> (EnvironmentalImpactCategory)
Enum Description
NUCLEAR_WASTE

Produced nuclear waste in grams per kilowatthour.

CARBON_DIOXIDE

Exhausted carbon dioxide in grams per kilowatthour.

The environmental impact category of this value.

amount
required
number

Amount of this portion in g/kWh.

{
  • "category": "NUCLEAR_WASTE",
  • "amount": 0
}

EnergyMix

is_green_energy
required
boolean

True if 100% from regenerative sources. (CO2 and nuclear waste is zero)

Array of objects (EnergySource)

Key-value pairs (enum + percentage) of energy sources of this location's tariff.

Array of objects (EnvironmentalImpact)

Key-value pairs (enum + percentage) of nuclear waste and CO2 exhaust of this location's tariff.

supplier_name
string <= 64 characters

Name of the energy supplier, delivering the energy for this location or tariff.

energy_product_name
string <= 64 characters

Name of the energy supplier's product/tariff plan used at this location.

{
  • "is_green_energy": true,
  • "energy_sources": [
    ],
  • "environ_impact": [
    ],
  • "supplier_name": "string",
  • "energy_product_name": "string"
}

Location

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the CPO that 'owns' this Location.

party_id
required
string = 3 characters

ID of the CPO that 'owns' this Location (following the ISO-15118 standard).

id
required
string <= 36 characters

Uniquely identifies the location within the CPOs platform (and suboperator platforms). This field can never be changed, modified or renamed.

publish
required
boolean

Defines if a Location may be published on a website or app etc. When this is set to false, only tokens identified in the field publish_allowed_to are allowed to be shown this Location. When the same location has EVSEs that may be published and may not be published, two 'Locations' should be created.

Array of objects (PublishTokenType)

This field may only be used when the publish field is set to false. Only owners of Tokens that match all the set fields of one PublishToken in the list are allowed to be shown this location.

name
string <= 255 characters

Display name of the location.

address
required
string <= 45 characters

Street/block name and house number if available.

city
required
string <= 45 characters

City or town.

postal_code
string <= 10 characters

Postal code of the location, may only be omitted when the location has no postal code.

state
string <= 20 characters

State or province of the location, only to be used when relevant.

country
required
string = 3 characters

ISO 3166-1 alpha-3 code for the country of this location.

required
object (GeoLocation)

Coordinates of the location.

Array of objects (AdditionalGeoLocation)

Geographical location of related points relevant to the user.

parking_type
string <open-enum> (ParkingType)
Enum Description
ALONG_MOTORWAY

Location on a parking facility/rest area along a motorway, freeway, interstate, highway etc.

PARKING_GARAGE

Multistorey car park.

PARKING_LOT

A cleared area that is intended for parking vehicles, i.e. at super markets, bars, etc.

ON_DRIVEWAY

Location is on the driveway of a house/building.

ON_STREET

Parking in public space along a street.

UNDERGROUND_GARAGE

Multistorey car park, mainly underground.

The general type of parking at the charge point location.

Array of objects (EVSE)

List of EVSEs that belong to this Location.

Array of objects (Parking)

List of parking places at this location. New in OCPI 2.3.0.

Array of objects (DisplayText)

Human-readable directions on how to reach the location.

object (BusinessDetails)

Information of the operator. When not specified, the information retrieved from the Credentials module should be used instead.

object (BusinessDetails)

Information of the suboperator if available.

object (BusinessDetails)

Information of the owner if available.

facilities
Array of strings <open-enum> (Facility) [ items <open-enum > ]
Items Enum Description
HOTEL

A hotel.

RESTAURANT

A restaurant.

CAFE

A cafe.

MALL

A mall or shopping center.

SUPERMARKET

A supermarket.

SPORT

Sport facilities: gym, field etc.

RECREATION_AREA

A recreation area.

NATURE

Located in, or close to, a park, nature reserve etc.

MUSEUM

A museum.

BIKE_SHARING

A bike/e-bike/e-scooter sharing location.

BUS_STOP

A bus stop.

TAXI_STAND

A taxi stand.

TRAM_STOP

A tram stop/station.

METRO_STATION

A metro station.

TRAIN_STATION

A train station.

AIRPORT

An airport.

PARKING_LOT

A parking lot.

CARPOOL_PARKING

A carpool parking.

FUEL_STATION

A Fuel station.

WIFI

Wifi or other type of internet available.

Optional list of facilities this charging location directly belongs to.

time_zone
required
string <= 255 characters

One of IANA tzdata's TZ-values representing the time zone of the location. Examples "Europe/Oslo", "Europe/Zurich".

object (Hours)

The times when the EVSEs at the location can be accessed for charging.

charging_when_closed
boolean

Indicates if the EVSEs are still charging outside the opening hours of the location. Default is true.

Array of objects (Image)

Links to images related to the location such as photos or logos.

object (EnergyMix)

Details on the energy supplied at this location.

help_phone
string <= 25 characters

A telephone number that a Driver using the Location may call for assistance. Calling this number will typically connect the caller to the CPO's customer service department.

last_updated
required
string <date-time>

Timestamp when this Location or one of its EVSEs or Connectors were last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "id": "string",
  • "publish": true,
  • "publish_allowed_to": [
    ],
  • "name": "string",
  • "address": "string",
  • "city": "string",
  • "postal_code": "string",
  • "state": "string",
  • "country": "str",
  • "coordinates": {
    },
  • "related_locations": [
    ],
  • "parking_type": "ALONG_MOTORWAY",
  • "evses": [
    ],
  • "parking_places": [
    ],
  • "directions": [
    ],
  • "operator": {},
  • "suboperator": {},
  • "owner": {},
  • "facilities": [
    ],
  • "time_zone": "string",
  • "opening_times": {
    },
  • "charging_when_closed": true,
  • "images": [],
  • "energy_mix": {
    },
  • "help_phone": "string",
  • "last_updated": "2019-08-24T14:15:22Z"
}

CdrToken

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the MSP that 'owns' this Token.

party_id
required
string = 3 characters

ID of the eMSP that 'owns' this Token (following the ISO-15118 standard).

uid
required
string <= 36 characters

Unique ID by which this Token can be identified. This is the field used by the CPO's system (RFID reader on the Charge Point) to identify this token. Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the RFID reader, but that is not a requirement. If this is a type=APP_USER Token, it will be a unique, by the eMSP, generated ID.

type
required
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Type of the token

contract_id
required
string <= 36 characters

Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/).

{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string"
}

AuthMethod

string <enum> (AuthMethod)
Enum Description
AUTH_REQUEST

Authentication request has been sent to the eMSP.

COMMAND

Command like StartSession or ReserveNow used to start the Session, the Token provided in the Command was used as authorization.

WHITELIST

Whitelist used for authentication, no request to the eMSP has been performed.

Method used for authentication.

"AUTH_REQUEST"

CdrDimensionType

string <enum> (CdrDimensionType)
Enum Description
CURRENT

(Session Only) Average charging current during this ChargingPeriod: defined in A (Ampere). When negative, the current is flowing from the EV to the grid.

ENERGY

Total amount of energy (dis-)charged during this ChargingPeriod: defined in kWh. When negative, more energy was fed into the grid than charged into the EV. Default step_size is 1.

ENERGY_EXPORT

(Session Only) Total amount of energy fed back into the grid: defined in kWh.

ENERGY_IMPORT

(Session Only) Total amount of energy charged, defined in kWh.

MAX_CURRENT

Sum of the maximum current over all phases, reached during this ChargingPeriod: defined in A (Ampere).

MIN_CURRENT

Sum of the minimum current over all phases, reached during this ChargingPeriod, when negative, current has flowed from the EV to the grid. Defined in A (Ampere).

MAX_POWER

Maximum power reached during this ChargingPeriod: defined in kW (Kilowatt).

MIN_POWER

Minimum power reached during this ChargingPeriod: defined in kW (Kilowatt), when negative, the power has flowed from the EV to the grid.

PARKING_TIME

Time during this ChargingPeriod not charging: defined in hours, default step_size multiplier is 1 second.

POWER

(Session Only) Average power during this ChargingPeriod: defined in kW (Kilowatt). When negative, the power is flowing from the EV to the grid.

RESERVATION_TIME

Time during this ChargingPeriod the Charge Point has been reserved time, defined in hours default step_size multiplier is 1 second.

RESERVATION_EXPIRES

Time during this ChargingPeriod Charge Point has been reserved and not yet been in use for this customer: defined in hours, default step_size multiplier is 1 second.

RESERVATION_OVERTIME

Time after the reservation during a ChargingPeriod that the session continues after the reserved time slot, defined in hours, default step_size multiplier is 1 second.

STATE_OF_CHARGE

(Session Only) Current state of charge of the EV, in percentage, values allowed: 0 to 100.

TIME

Time charging during this ChargingPeriod: defined in hours, default step_size multiplier is 1 second.

Defines the type of a CDR dimension. Some of these values are not useful for CDRs, and SHALL therefore only be used in Sessions (marked as Session Only).

"CURRENT"

CdrDimension

type
required
string <enum> (CdrDimensionType)
Enum Description
CURRENT

(Session Only) Average charging current during this ChargingPeriod: defined in A (Ampere). When negative, the current is flowing from the EV to the grid.

ENERGY

Total amount of energy (dis-)charged during this ChargingPeriod: defined in kWh. When negative, more energy was fed into the grid than charged into the EV. Default step_size is 1.

ENERGY_EXPORT

(Session Only) Total amount of energy fed back into the grid: defined in kWh.

ENERGY_IMPORT

(Session Only) Total amount of energy charged, defined in kWh.

MAX_CURRENT

Sum of the maximum current over all phases, reached during this ChargingPeriod: defined in A (Ampere).

MIN_CURRENT

Sum of the minimum current over all phases, reached during this ChargingPeriod, when negative, current has flowed from the EV to the grid. Defined in A (Ampere).

MAX_POWER

Maximum power reached during this ChargingPeriod: defined in kW (Kilowatt).

MIN_POWER

Minimum power reached during this ChargingPeriod: defined in kW (Kilowatt), when negative, the power has flowed from the EV to the grid.

PARKING_TIME

Time during this ChargingPeriod not charging: defined in hours, default step_size multiplier is 1 second.

POWER

(Session Only) Average power during this ChargingPeriod: defined in kW (Kilowatt). When negative, the power is flowing from the EV to the grid.

RESERVATION_TIME

Time during this ChargingPeriod the Charge Point has been reserved time, defined in hours default step_size multiplier is 1 second.

RESERVATION_EXPIRES

Time during this ChargingPeriod Charge Point has been reserved and not yet been in use for this customer: defined in hours, default step_size multiplier is 1 second.

RESERVATION_OVERTIME

Time after the reservation during a ChargingPeriod that the session continues after the reserved time slot, defined in hours, default step_size multiplier is 1 second.

STATE_OF_CHARGE

(Session Only) Current state of charge of the EV, in percentage, values allowed: 0 to 100.

TIME

Time charging during this ChargingPeriod: defined in hours, default step_size multiplier is 1 second.

Type of CDR dimension.

volume
required
number

Volume of the dimension consumed, measured according to the dimension type.

{
  • "type": "CURRENT",
  • "volume": 0
}

ChargingPeriod

start_date_time
required
string <date-time>

Start timestamp of the charging period. A period ends when the next period starts. The last period ends when the session ends.

required
Array of objects (CdrDimension) non-empty

List of relevant values for this charging period.

tariff_id
string <= 36 characters

Unique identifier of the Tariff that is relevant for this Charging Period. If not provided, no Tariff is relevant during this period.

{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "dimensions": [
    ],
  • "tariff_id": "string"
}

TaxAmount

name
required
string

A description of the tax. In countries where a tax name is required like Canada this can be something like "QST". In countries where this is not required, this can be something more generic like "VAT" or "General Sales Tax".

account_number
string

Tax Account Number of the business entity remitting these taxes. Optional as this is not required in all countries.

percentage
number

Tax percentage. Optional as this is not required in all countries.

amount
required
number

The amount of money of this tax that is due.

{
  • "name": "string",
  • "account_number": "string",
  • "percentage": 0,
  • "amount": 0
}

Price

before_taxes
required
number

Price/Cost excluding taxes.

Array of objects (TaxAmount)

All taxes that are applicable to this price and relevant to the receiver of the Session or CDR.

{
  • "before_taxes": 0,
  • "taxes": [
    ]
}

SessionStatus

string <enum> (SessionStatus)
Enum Description
ACTIVE

The session has been accepted and is active. All pre-conditions were met: Communication between EV and EVSE (for example: cable plugged in correctly), EV or driver is authorized. EV is being charged, or can be charged. Energy is, or is not, being transfered.

COMPLETED

The session has been finished successfully. No more modifications will be made to the Session object using this state.

INVALID

The Session object using this state is declared invalid and will not be billed.

PENDING

The session is pending, it has not yet started. Not all pre-conditions are met. This is the initial state. The session might never become an active session.

RESERVATION

The session is started due to a reservation, charging has not yet started. The session might never become an active session.

Defines the state of a session.

"ACTIVE"

Session

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the CPO that 'owns' this Session.

party_id
required
string = 3 characters

ID of the CPO that 'owns' this Session (following the ISO-15118 standard).

id
required
string <= 36 characters

The unique id that identifies the charging session in the CPO platform.

start_date_time
required
string <date-time>

The timestamp when the session became ACTIVE in the Charge Point. When the session is still PENDING, this field SHALL be set to the time the Session was created at the Charge Point. When a Session goes from PENDING to ACTIVE, this field SHALL be updated to the moment the Session went to ACTIVE in the Charge Point.

end_date_time
string <date-time>

The timestamp when the session was completed/finished, charging might have finished before the session ends, for example: EV is full, but parking cost also has to be paid.

kwh
required
number

How many kWh were charged.

required
object (CdrToken)

Token used to start this charging session, including all the relevant information to identify the unique token.

auth_method
required
string <enum> (AuthMethod)
Enum Description
AUTH_REQUEST

Authentication request has been sent to the eMSP.

COMMAND

Command like StartSession or ReserveNow used to start the Session, the Token provided in the Command was used as authorization.

WHITELIST

Whitelist used for authentication, no request to the eMSP has been performed.

Method used for authentication. This might change during a session, for example when the session was started with a reservation: ReserveNow: COMMAND. When the driver arrives and starts charging using a Token that is whitelisted: WHITELIST.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP. When the eMSP provided an authorization_reference in either: real-time authorization, StartSession or ReserveNow this field SHALL contain the same value. When different authorization_reference values have been given by the eMSP that are relevant to this Session, the last given value SHALL be used here.

location_id
required
string <= 36 characters

Location.id of the Location object of this CPO, on which the charging session is/was happening.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE of this Location on which the charging session is/was happening. Allowed to be set to: #NA when this session is created for a reservation, but no EVSE yet assigned to the driver.

connector_id
required
string <= 36 characters

Connector.id of the Connector of this Location where the charging session is/was happening. Allowed to be set to: #NA when this session is created for a reservation, but no connector yet assigned to the driver.

meter_id
string <= 255 characters

Optional identification of the kWh meter.

currency
required
string = 3 characters

ISO 4217 code of the currency used for this session.

Array of objects (ChargingPeriod)

An optional list of Charging Periods that can be used to calculate and verify the total cost.

object (Price)

The total cost of the session in the specified currency. This is the price that the eMSP will have to pay to the CPO. A total_cost of 0.00 means free of charge. When omitted, i.e. no price information is given in the Session object, it does not imply the session is/was free of charge.

status
required
string <enum> (SessionStatus)
Enum Description
ACTIVE

The session has been accepted and is active. All pre-conditions were met: Communication between EV and EVSE (for example: cable plugged in correctly), EV or driver is authorized. EV is being charged, or can be charged. Energy is, or is not, being transfered.

COMPLETED

The session has been finished successfully. No more modifications will be made to the Session object using this state.

INVALID

The Session object using this state is declared invalid and will not be billed.

PENDING

The session is pending, it has not yet started. Not all pre-conditions are met. This is the initial state. The session might never become an active session.

RESERVATION

The session is started due to a reservation, charging has not yet started. The session might never become an active session.

The status of the session.

last_updated
required
string <date-time>

Timestamp when this Session was last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "id": "string",
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "end_date_time": "2019-08-24T14:15:22Z",
  • "kwh": 0,
  • "cdr_token": {
    },
  • "auth_method": "AUTH_REQUEST",
  • "authorization_reference": "string",
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string",
  • "meter_id": "string",
  • "currency": "str",
  • "charging_periods": [
    ],
  • "total_cost": {
    },
  • "status": "ACTIVE",
  • "last_updated": "2019-08-24T14:15:22Z"
}

ProfileType

string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Different smart charging profile types.

"CHEAP"

ChargingPreferences

profile_type
required
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Type of Smart Charging Profile selected by the driver. The ProfileType has to be supported at the Connector and for every supported ProfileType, a Tariff MUST be provided. This gives the EV driver the option between different pricing options.

departure_time
string <date-time>

Expected departure. The driver has given this Date/Time as expected departure moment. It is only an estimation and not necessarily the Date/Time of the actual departure.

energy_need
number

Requested amount of energy in kWh. The EV driver wants to have this amount of energy charged.

discharge_allowed
boolean

The driver allows their EV to be discharged when needed, as long as the other preferences are met: EV is charged with the preferred energy (energy_need) until the preferred departure moment (departure_time). Default if omitted: false.

{
  • "profile_type": "CHEAP",
  • "departure_time": "2019-08-24T14:15:22Z",
  • "energy_need": 0,
  • "discharge_allowed": true
}

ChargingPreferencesResponse

string <enum> (ChargingPreferencesResponse)
Enum Description
ACCEPTED

Charging Preferences accepted, EVSE will try to accomplish them, although this is no guarantee that they will be fulfilled.

DEPARTURE_REQUIRED

CPO requires departure_time to be able to perform Charging Preference based Smart Charging.

ENERGY_NEED_REQUIRED

CPO requires energy_need to be able to perform Charging Preference based Smart Charging.

NOT_POSSIBLE

Charging Preferences contain a demand that the EVSE knows it cannot fulfill.

PROFILE_TYPE_NOT_SUPPORTED

profile_type contains a value that is not supported by the EVSE.

An enum with possible responses to a PUT Charging Preferences request.

"ACCEPTED"

CdrLocation

id
required
string <= 36 characters

Uniquely identifies the location within the CPO's platform (and suboperator platforms). This field can never be changed, modified or renamed.

name
string <= 255 characters

Display name of the location.

address
required
string <= 45 characters

Street/block name and house number if available.

city
required
string <= 45 characters

City or town.

postal_code
string <= 10 characters

Postal code of the location, may only be omitted when the location has no postal code: in some countries charging locations at highways don't have postal codes.

state
string <= 20 characters

State only to be used when relevant.

country
required
string = 3 characters

ISO 3166-1 alpha-3 code for the country of this location.

required
object (GeoLocation)

Coordinates of the location.

evse_uid
required
string <= 36 characters

Uniquely identifies the EVSE within the CPO's platform (and suboperator platforms). For example a database unique ID or the actual EVSE ID. This field can never be changed, modified or renamed. This is the technical identification of the EVSE, not to be used as human readable identification, use the field: evse_id for that. Allowed to be set to: #NA when this CDR is created for a reservation that never resulted in a charging session.

evse_id
required
string <= 48 characters

Compliant with the following specification for EVSE ID: "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/). Allowed to be set to: #NA when this CDR is created for a reservation that never resulted in a charging session.

connector_id
required
string <= 36 characters

Identifier of the connector within the EVSE. Allowed to be set to: #NA when this CDR is created for a reservation that never resulted in a charging session.

connector_standard
required
string <open-enum> (ConnectorType)
Enum Description
CHADEMO

The connector type is CHAdeMO, DC.

CHAOJI

The ChaoJi connector. The new generation charging connector, harmonized between CHAdeMO and GB/T. DC.

DOMESTIC_A

Standard/Domestic household, type "A", NEMA 1-15, 2 pins.

DOMESTIC_B

Standard/Domestic household, type "B", NEMA 5-15, 3 pins.

DOMESTIC_C

Standard/Domestic household, type "C", CEE 7/17, 2 pins.

DOMESTIC_D

Standard/Domestic household, type "D", 3 pin.

DOMESTIC_E

Standard/Domestic household, type "E", CEE 7/5 3 pins.

DOMESTIC_F

Standard/Domestic household, type "F", CEE 7/4, Schuko, 3 pins.

DOMESTIC_G

Standard/Domestic household, type "G", BS 1363, Commonwealth, 3 pins.

DOMESTIC_H

Standard/Domestic household, type "H", SI-32, 3 pins.

DOMESTIC_I

Standard/Domestic household, type "I", AS 3112, 3 pins.

DOMESTIC_J

Standard/Domestic household, type "J", SEV 1011, 3 pins.

DOMESTIC_K

Standard/Domestic household, type "K", DS 60884-2-D1, 3 pins.

DOMESTIC_L

Standard/Domestic household, type "L", CEI 23-16-VII, 3 pins.

DOMESTIC_M

Standard/Domestic household, type "M", BS 546, 3 pins.

DOMESTIC_N

Standard/Domestic household, type "N", NBR 14136, 3 pins.

DOMESTIC_O

Standard/Domestic household, type "O", TIS 166-2549, 3 pins.

GBT_AC

Guobiao GB/T 20234.2 AC socket/connector.

GBT_DC

Guobiao GB/T 20234.3 DC connector.

IEC_60309_2_single_16

IEC 60309-2 Industrial Connector single phase 16 amperes (usually blue).

IEC_60309_2_three_16

IEC 60309-2 Industrial Connector three phases 16 amperes (usually red).

IEC_60309_2_three_32

IEC 60309-2 Industrial Connector three phases 32 amperes (usually red).

IEC_60309_2_three_64

IEC 60309-2 Industrial Connector three phases 64 amperes (usually red).

IEC_62196_T1

IEC 62196 Type 1 "SAE J1772".

IEC_62196_T1_COMBO

Combo Type 1 based, DC.

IEC_62196_T2

IEC 62196 Type 2 "Mennekes".

IEC_62196_T2_COMBO

Combo Type 2 based, DC.

IEC_62196_T3A

IEC 62196 Type 3A.

IEC_62196_T3C

IEC 62196 Type 3C "Scame".

MCS

The MegaWatt Charging System (MCS) connector as developed by CharIN.

NEMA_5_20

NEMA 5-20, 3 pins.

NEMA_6_30

NEMA 6-30, 3 pins.

NEMA_6_50

NEMA 6-50, 3 pins.

NEMA_10_30

NEMA 10-30, 3 pins.

NEMA_10_50

NEMA 10-50, 3 pins.

NEMA_14_30

NEMA 14-30, 3 pins, rating of 30 A.

NEMA_14_50

NEMA 14-50, 3 pins, rating of 50 A.

PANTOGRAPH_BOTTOM_UP

On-board Bottom-up-Pantograph typically for bus charging.

PANTOGRAPH_TOP_DOWN

Off-board Top-down-Pantograph typically for bus charging.

SAE_J3400

SAE J3400, also known as North American Charging Standard (NACS), developed by Tesla, Inc in 2021.

TESLA_R

Tesla Connector "Roadster"-type (round, 4 pin).

TESLA_S

Tesla Connector "Model-S"-type (oval, 5 pin). Mechanically compatible with SAE J3400 but uses CAN bus for communication instead of power line communication.

The standard of the installed connector. When this CDR is created for a reservation that never resulted in a charging session, this field can be set to any value and should be ignored by the Receiver.

connector_format
required
string <enum> (ConnectorFormat)
Enum Description
SOCKET

The connector is a socket; the EV user needs to bring a fitting plug.

CABLE

The connector is an attached cable; the EV users car needs to have a fitting inlet.

The format (socket/cable) of the installed connector. When this CDR is created for a reservation that never resulted in a charging session, this field can be set to any value and should be ignored by the Receiver.

connector_power_type
required
string <enum> (PowerType)
Enum Description
AC_1_PHASE

AC single phase.

AC_2_PHASE

AC two phases, only two of the three available phases connected.

AC_2_PHASE_SPLIT

AC two phases using split phase system.

AC_3_PHASE

AC three phases.

DC

Direct Current.

When this CDR is created for a reservation that never resulted in a charging session, this field can be set to any value and should be ignored by the Receiver.

{
  • "id": "string",
  • "name": "string",
  • "address": "string",
  • "city": "string",
  • "postal_code": "string",
  • "state": "string",
  • "country": "str",
  • "coordinates": {
    },
  • "evse_uid": "string",
  • "evse_id": "string",
  • "connector_id": "string",
  • "connector_standard": "CHADEMO",
  • "connector_format": "SOCKET",
  • "connector_power_type": "AC_1_PHASE"
}

TariffType

string <enum> (TariffType)
Enum Description
AD_HOC_PAYMENT

Used to describe that a Tariff is valid when ad-hoc payment is used at the Charge Point (for example: Debit or Credit card payment terminal).

PROFILE_CHEAP

Used to describe that a Tariff is valid when Charging Preference: CHEAP is set for the session.

PROFILE_FAST

Used to describe that a Tariff is valid when Charging Preference: FAST is set for the session.

PROFILE_GREEN

Used to describe that a Tariff is valid when Charging Preference: GREEN is set for the session.

REGULAR

Used to describe that a Tariff is valid when using an RFID, without any Charging Preference, or when Charging Preference: REGULAR is set for the session.

Type of tariff.

"AD_HOC_PAYMENT"

PriceLimit

before_taxes
required
number

Maximum or minimum cost excluding taxes.

after_taxes
number

Maximum or minimum cost including taxes.

{
  • "before_taxes": 0,
  • "after_taxes": 0
}

TaxIncluded

string <enum> (TaxIncluded)
Enum Description
YES

Taxes are included in the prices in this Tariff.

NO

Taxes are not included, and will be added on top of the prices in this Tariff.

N/A

No taxes are applicable to this Tariff.

Describes if tax may have to be added to the amounts in a Tariff.

"YES"

TariffDimensionType

string <enum> (TariffDimensionType)
Enum Description
ENERGY

Defined in kWh, step_size multiplier: 1 Wh

FLAT

Flat fee without unit for step_size

PARKING_TIME

Time not charging: defined in hours, step_size multiplier: 1 second

TIME

Time charging: defined in hours, step_size multiplier: 1 second. Can also be used in combination with a RESERVATION restriction to describe the price of the reservation time.

Defines the dimension of a tariff.

"ENERGY"

PriceComponent

type
required
string <enum> (TariffDimensionType)
Enum Description
ENERGY

Defined in kWh, step_size multiplier: 1 Wh

FLAT

Flat fee without unit for step_size

PARKING_TIME

Time not charging: defined in hours, step_size multiplier: 1 second

TIME

Time charging: defined in hours, step_size multiplier: 1 second. Can also be used in combination with a RESERVATION restriction to describe the price of the reservation time.

The dimension that is being priced.

price
required
number

Price per unit for this dimension. This is including or excluding taxes according to the tax_included field of the Tariff that this PriceComponent is contained in.

vat
number

Applicable VAT percentage for this tariff dimension. If omitted, no VAT is applicable.

step_size
required
integer

Minimum amount to be billed. That is, the dimension will be billed in this step_size blocks. Consumed amounts are rounded up to the smallest multiple of step_size that is greater than the consumed amount. For example: if type is TIME and step_size has a value of 300, then time will be billed in blocks of 5 minutes. If 6 minutes were consumed, 10 minutes (2 blocks of step_size) will be billed.

The step_size field is no longer present in OCPI 3.0. In OCPI 3.0, Parties are advised to measure quantities as precise as required by calibration law and use the full precision of such measurements in cost computation. Users of OCPI 2.2.1 looking to be ready for a transition to OCPI 3.0 or to maximize interoperability with OCPI 3.0 are advised to effectively avoid using step_size by setting step_size to 1 always.

{
  • "type": "ENERGY",
  • "price": 0,
  • "vat": 0,
  • "step_size": 0
}

DayOfWeek

string <enum> (DayOfWeek)
Enum: "MONDAY" "TUESDAY" "WEDNESDAY" "THURSDAY" "FRIDAY" "SATURDAY" "SUNDAY"

Day of the week.

"MONDAY"

ReservationRestrictionType

string <enum> (ReservationRestrictionType)
Enum Description
RESERVATION

Used in Tariff Elements to describe costs for a reservation.

RESERVATION_EXPIRES

Used in Tariff Elements to describe costs for a reservation that expires (i.e. driver does not start a charging session before expiry_date of the reservation).

Defines if a TariffElement is applicable for a reservation.

"RESERVATION"

BookingRestrictionType

string <enum> (BookingRestrictionType)
Enum Description
BOOKING

Used in Tariff Elements to describe costs for a booking.

BOOKING_EXPIRES

Used in Tariff Elements to describe costs for a booking that does not start in the specified booking period.

BOOKING_CANCELLATION_FEES

Used in Tariff Elements to describe costs for cancelling a booking.

BOOKING_OVERTIME

Used in Tariff Elements to describe costs for charging after the booking has been completed.

Defines if a TariffElement is applicable for booking costs.

"BOOKING"

TariffRestrictions

start_time
string^([0-1][0-9]|2[0-3]):[0-5][0-9]$

Start time of day in local time, the time zone is defined in the time_zone field of the Location, for example 13:30, valid from this time of the day. Must be in 24h format with leading zeros. Hour/Minute separator ":".

end_time
string^([0-1][0-9]|2[0-3]):[0-5][0-9]$

End time of day in local time, the time zone is defined in the time_zone field of the Location, for example 19:45, valid until this time of the day. Same syntax as start_time. If end_time < start_time then the period wraps around to the next day. To stop at end of the day use 00:00.

start_date
string^([12][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][...

Start date in local time, the time zone is defined in the time_zone field of the Location, for example 2015-12-24, valid from this day (inclusive). Format YYYY-MM-DD.

end_date
string^([12][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][...

End date in local time, the time zone is defined in the time_zone field of the Location, for example 2015-12-27, valid until this day (exclusive). Format YYYY-MM-DD.

min_kwh
number

Minimum consumed energy in kWh, for example 20, valid from this amount of energy (inclusive) being used.

max_kwh
number

Maximum consumed energy in kWh, for example 50, valid until this amount of energy (exclusive) being used.

min_current
number

Sum of the minimum current (in Amperes) over all phases, for example 5. When the EV is charging with more than, or equal to, the defined amount of current, this TariffElement is/becomes active. If the charging current is or becomes lower, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the minimum current over the entire Charging Session. This restriction can make a TariffElement become active when the charging current is above the defined value, but the TariffElement MUST no longer be active when the charging current drops below the defined value.

max_current
number

Sum of the maximum current (in Amperes) over all phases, for example 20. When the EV is charging with less than the defined amount of current, this TariffElement becomes/is active. If the charging current is or becomes higher, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the maximum current over the entire Charging Session. This restriction can make a TariffElement become active when the charging current is below this value, but the TariffElement MUST no longer be active when the charging current raises above the defined value.

min_power
number

Minimum power in kW, for example 5. When the EV is charging with more than, or equal to, the defined amount of power, this TariffElement is/becomes active. If the charging power is or becomes lower, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the minimum power over the entire Charging Session. This restriction can make a TariffElement become active when the charging power is above this value, but the TariffElement MUST no longer be active when the charging power drops below the defined value.

max_power
number

Maximum power in kW, for example 20. When the EV is charging with less than the defined amount of power, this TariffElement becomes/is active. If the charging power is or becomes higher, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the maximum power over the entire Charging Session. This restriction can make a TariffElement become active when the charging power is below this value, but the TariffElement MUST no longer be active when the charging power raises above the defined value.

min_duration
integer

Minimum duration in seconds the Charging Session MUST last (inclusive). When the duration of a Charging Session is longer than the defined value, this TariffElement is or becomes active. Before that moment, this TariffElement is not yet active.

max_duration
integer

Maximum duration in seconds the Charging Session MUST last (exclusive). When the duration of a Charging Session is shorter than the defined value, this TariffElement is or becomes active. After that moment, this TariffElement is no longer active.

day_of_week
Array of strings <enum> (DayOfWeek) [ items <enum > ]
Items Enum: "MONDAY" "TUESDAY" "WEDNESDAY" "THURSDAY" "FRIDAY" "SATURDAY" "SUNDAY"

Which day(s) of the week this TariffElement is active.

reservation
string <enum> (ReservationRestrictionType)
Enum Description
RESERVATION

Used in Tariff Elements to describe costs for a reservation.

RESERVATION_EXPIRES

Used in Tariff Elements to describe costs for a reservation that expires (i.e. driver does not start a charging session before expiry_date of the reservation).

When this field is present, the TariffElement describes reservation costs. A reservation starts when the reservation is made, and ends when the driver starts charging on the reserved EVSE/Location, or when the reservation expires. A reservation can only have FLAT and TIME TariffDimensions, where TIME is for the duration of the reservation.

booking
string <enum> (BookingRestrictionType)
Enum Description
BOOKING

Used in Tariff Elements to describe costs for a booking.

BOOKING_EXPIRES

Used in Tariff Elements to describe costs for a booking that does not start in the specified booking period.

BOOKING_CANCELLATION_FEES

Used in Tariff Elements to describe costs for cancelling a booking.

BOOKING_OVERTIME

Used in Tariff Elements to describe costs for charging after the booking has been completed.

When this field is present, the TariffElement describes booking costs. A booking can only have: FLAT and TIME TariffDimensions.

{
  • "start_time": "string",
  • "end_time": "string",
  • "start_date": "string",
  • "end_date": "string",
  • "min_kwh": 0,
  • "max_kwh": 0,
  • "min_current": 0,
  • "max_current": 0,
  • "min_power": 0,
  • "max_power": 0,
  • "min_duration": 0,
  • "max_duration": 0,
  • "day_of_week": [
    ],
  • "reservation": "RESERVATION",
  • "booking": "BOOKING"
}

TariffElement

required
Array of objects (PriceComponent) non-empty

List of Price Components that each describe how a certain dimension is priced.

object (TariffRestrictions)

Restrictions that describe under which circumstances the Price Components of this Tariff Element apply.

{
  • "price_components": [
    ],
  • "restrictions": {
    }
}

Tariff

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the CPO that 'owns' this Tariff.

party_id
required
string = 3 characters

ID of the CPO that 'owns' this Tariff (following the ISO-15118 standard).

id
required
string <= 36 characters

Uniquely identifies the tariff within the CPO's platform (and suboperator platforms).

currency
required
string = 3 characters

ISO-4217 code of the currency of this tariff.

type
string <enum> (TariffType)
Enum Description
AD_HOC_PAYMENT

Used to describe that a Tariff is valid when ad-hoc payment is used at the Charge Point (for example: Debit or Credit card payment terminal).

PROFILE_CHEAP

Used to describe that a Tariff is valid when Charging Preference: CHEAP is set for the session.

PROFILE_FAST

Used to describe that a Tariff is valid when Charging Preference: FAST is set for the session.

PROFILE_GREEN

Used to describe that a Tariff is valid when Charging Preference: GREEN is set for the session.

REGULAR

Used to describe that a Tariff is valid when using an RFID, without any Charging Preference, or when Charging Preference: REGULAR is set for the session.

Defines the type of the tariff. This allows for distinction in case of given Charging Preferences. When omitted, this tariff is valid for all sessions.

Array of objects (DisplayText)

List of multi-language alternative tariff info texts.

tariff_alt_url
string <uri>

URL to a web page that contains an explanation of the tariff information in human readable form.

object (PriceLimit)

When this field is set, a Charging Session with this tariff will at least cost this amount.

object (PriceLimit)

When this field is set, a Charging Session with this tariff will at most cost this amount.

preauthorize_amount
number

The amount that a Payment Terminal Provider should preauthorize when handling card payment for a Session with this Tariff.

tax_included
required
string <enum> (TaxIncluded)
Enum Description
YES

Taxes are included in the prices in this Tariff.

NO

Taxes are not included, and will be added on top of the prices in this Tariff.

N/A

No taxes are applicable to this Tariff.

Whether taxes are included in the amounts in this Tariff.

required
Array of objects (TariffElement) non-empty

List of Tariff Elements.

start_date_time
string <date-time>

The time when this tariff becomes active, in UTC. time_zone field of the Location can be used to convert to local time. Typically used for a new tariff that is already given with the location, before it becomes active.

end_date_time
string <date-time>

The time after which this tariff is no longer valid, in UTC. time_zone field of the Location can be used to convert to local time. Typically used when this tariff is going to be replaced with a different tariff in the near future.

object (EnergyMix)

Details on the energy supplied with this tariff.

last_updated
required
string <date-time>

Timestamp when this Tariff was last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "id": "string",
  • "currency": "str",
  • "type": "AD_HOC_PAYMENT",
  • "tariff_alt_text": [
    ],
  • "tariff_alt_url": "http://example.com",
  • "min_price": {
    },
  • "max_price": {
    },
  • "preauthorize_amount": 0,
  • "tax_included": "YES",
  • "elements": [
    ],
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "end_date_time": "2019-08-24T14:15:22Z",
  • "energy_mix": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

SignedValue

nature
required
string <= 32 characters

Nature of the value, in other words, the event this value belongs to. Possible values at moment of writing:

  • Start (value at the start of the Session)
  • End (signed value at the end of the Session)
  • Intermediate (signed values take during the Session, after Start, before End) Others might be added later.
plain_data
required
string <= 512 characters

The un-encoded string of data. The format of the content depends on the EncodingMethod field.

signed_data
required
string <= 5000 characters

Blob of signed data, base64 encoded. The format of the content depends on the EncodingMethod field.

{
  • "nature": "string",
  • "plain_data": "string",
  • "signed_data": "string"
}

SignedData

encoding_method
required
string <= 36 characters

The name of the encoding used in the SignedData field. This is the name given to the encoding by a company or group of companies. For the German Eichrecht, different solutions are used, all have (somewhat) different encodings like OCMF, Alfen Eichrecht, EDL40 E-Mobility Extension or EDL40 Mennekes .

encoding_method_version
integer

Version of the EncodingMethod (when applicable).

public_key
string <= 512 characters

Public key used to sign the data, base64 encoded.

required
Array of objects (SignedValue) non-empty

One or more signed values.

url
string <= 512 characters

URL that can be shown to an EV driver. This URL gives the EV driver the possibility to check the signed data from a charging session.

{
  • "encoding_method": "string",
  • "encoding_method_version": 0,
  • "public_key": "string",
  • "signed_values": [
    ],
  • "url": "string"
}

CDR

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the CPO that 'owns' this CDR.

party_id
required
string = 3 characters

ID of the CPO that 'owns' this CDR (following the ISO-15118 standard).

id
required
string <= 39 characters

Uniquely identifies the CDR, the ID SHALL be unique per country_code/party_id combination. This field is longer than the usual 36 characters to allow for credit CDRs to have something appended to the original ID. Normal (non-credit) CDRs SHALL only have an ID with a maximum length of 36.

start_date_time
required
string <date-time>

Start timestamp of the charging session, or in-case of a reservation (before the start of a session) the start of the reservation.

end_date_time
required
string <date-time>

The timestamp when the session was completed/finished, charging might have finished before the session ends, for example: EV is full, but parking cost also has to be paid.

session_id
string <= 36 characters

Unique ID of the Session for which this CDR is sent. Is only allowed to be omitted when the CPO has not implemented the Sessions module or this CDR is the result of a reservation that never became a charging session, thus no OCPI Session.

booking_id
string <= 36 characters

Unique ID of the Booking for which this cdr can also be sent. Is only allowed to be omitted when the Session was reserved.

required
object (CdrToken)

Token used to start this charging session, including all the relevant information to identify the unique token.

auth_method
required
string <enum> (AuthMethod)
Enum Description
AUTH_REQUEST

Authentication request has been sent to the eMSP.

COMMAND

Command like StartSession or ReserveNow used to start the Session, the Token provided in the Command was used as authorization.

WHITELIST

Whitelist used for authentication, no request to the eMSP has been performed.

Method used for authentication. Multiple AuthMethods are possible during a charging sessions, for example when the session was started with a reservation: ReserveNow: COMMAND. When the driver arrives and starts charging using a Token that is whitelisted: WHITELIST. The last method SHALL be used in the CDR.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP. When the eMSP provided an authorization_reference in either real-time authorization, StartSession or ReserveNow, this field SHALL contain the same value. When different authorization_reference values have been given by the eMSP that are relevant to this Session, the last given value SHALL be used here.

required
object (CdrLocation)

Location where the charging session took place, including only the relevant EVSE and Connector.

meter_id
string <= 255 characters

Identification of the Meter inside the Charge Point.

currency
required
string = 3 characters

Currency of the CDR in ISO 4217 Code.

Array of objects (Tariff)

List of relevant Tariffs, see: Tariff. When relevant, a Free of Charge tariff should also be in this list, and point to a defined Free of Charge Tariff.

required
Array of objects (ChargingPeriod) non-empty

List of Charging Periods that make up this charging session.

object (SignedData)

Signed data that belongs to this charging Session.

required
object (Price)

Total sum of all the costs of this transaction in the specified currency.

object (Price)

Total sum of all the fixed costs in the specified currency, except fixed price components of parking and reservation. The cost not depending on amount of time/energy used etc. Can contain costs like a start tariff.

total_energy
required
number

Total energy charged, in kWh.

object (Price)

Total sum of all the cost of all the energy used, in the specified currency.

total_time
required
number

Total duration of the charging session (including the duration of charging and not charging), in hours.

object (Price)

Total sum of all the cost related to duration of charging during this transaction, in the specified currency.

total_parking_time
number

Total duration of the charging session where the EV was not charging (no energy was transferred between EVSE and EV), in hours.

object (Price)

Total sum of all the cost related to parking of this transaction, including fixed price components, in the specified currency.

object (Price)

Total sum of all the cost related to a reservation of a Charge Point, including fixed price components, in the specified currency.

remark
string <= 255 characters

Optional remark, can be used to provide additional human readable information to the CDR, for example: reason why a transaction was stopped.

invoice_reference_id
string <= 39 characters

This field can be used to reference an invoice, that will later be send for this CDR. Making it easier to link a CDR to a given invoice. Maybe even group CDRs that will be on the same invoice.

credit
boolean

When set to true, this is a Credit CDR, and the field credit_reference_id needs to be set as well.

credit_reference_id
string <= 39 characters

Is required to be set for a Credit CDR. This SHALL contain the id of the CDR for which this is a Credit CDR.

home_charging_compensation
boolean

When set to true, this CDR is for a charging session using the home charger of the EV Driver for which the energy cost needs to be financial compensated to the EV Driver.

last_updated
required
string <date-time>

Timestamp when this CDR was last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "id": "string",
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "end_date_time": "2019-08-24T14:15:22Z",
  • "session_id": "string",
  • "booking_id": "string",
  • "cdr_token": {
    },
  • "auth_method": "AUTH_REQUEST",
  • "authorization_reference": "string",
  • "cdr_location": {
    },
  • "meter_id": "string",
  • "currency": "str",
  • "tariffs": [
    ],
  • "charging_periods": [
    ],
  • "signed_data": {
    },
  • "total_cost": {
    },
  • "total_fixed_cost": {
    },
  • "total_energy": 0,
  • "total_energy_cost": {
    },
  • "total_time": 0,
  • "total_time_cost": {
    },
  • "total_parking_time": 0,
  • "total_parking_cost": {
    },
  • "total_reservation_cost": {
    },
  • "remark": "string",
  • "invoice_reference_id": "string",
  • "credit": true,
  • "credit_reference_id": "string",
  • "home_charging_compensation": true,
  • "last_updated": "2019-08-24T14:15:22Z"
}

WhitelistType

string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Defines when authorization of a Token by the CPO is allowed.

"ALWAYS"

EnergyContract

supplier_name
required
string <= 64 characters

Name of the energy supplier for this token.

contract_id
string <= 64 characters

Contract ID at the energy supplier, that belongs to the owner of this token.

{
  • "supplier_name": "string",
  • "contract_id": "string"
}

Token

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the MSP that 'owns' this Token.

party_id
required
string = 3 characters

ID of the eMSP that 'owns' this Token (following the ISO-15118 standard).

uid
required
string <= 36 characters

Unique ID by which this Token, combined with the Token type, can be identified. This is the field used by CPO system (RFID reader on the Charge Point) to identify this token. Currently, in most cases: type=RFID, this is the RFID hidden ID as read by the RFID reader, but that is not a requirement. If this is a APP_USER or AD_HOC_USER Token, it will be a uniquely, by the eMSP, generated ID. This field is named uid instead of id to prevent confusion with: contract_id.

type
required
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

Type of the token

contract_id
required
string <= 36 characters

Uniquely identifies the EV Driver contract token within the eMSP's platform (and suboperator platforms). Recommended to follow the specification for eMA ID from "E-mobility ID-codes: the purpose of IDs, ID usage and ID format" (https://evroaming.org/contract-evse-ids/).

visual_number
string <= 64 characters

Visual readable number/identification as printed on the Token (RFID card), might be equal to the contract_id.

issuer
required
string <= 64 characters

Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP.

group_id
string <= 36 characters

This ID groups a couple of tokens. This can be used to make two or more tokens work as one, so that a session can be started with one token and stopped with another, handy when a card and key-fob are given to the EV-driver. Beware that OCPP 1.5/1.6 only support group_ids (it is called parentId in OCPP 1.5/1.6) with a maximum length of 20.

valid
required
boolean

Is this Token valid

whitelist
required
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Indicates what type of white-listing is allowed.

language
string = 2 characters

Language Code ISO 639-1. This optional field indicates the Token owner's preferred interface language. If the language is not provided or not supported then the CPO is free to choose its own language.

default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

The default Charging Preference. When this is provided, and a charging session is started on an Charge Point that support Preference base Smart Charging and support this ProfileType, the Charge Point can start using this ProfileType, without this having to be set via: Set Charging Preferences.

object (EnergyContract)

When the Charge Point supports using your own energy supplier/contract at a Charge Point, information about the energy supplier/contract is needed so the CPO knows which energy supplier to use. NOTE: In a lot of countries it is currently not allowed/possible to use a drivers own energy supplier/contract at a Charge Point.

last_updated
required
string <date-time>

Timestamp when this Token was last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

TokenPatch

country_code
string = 2 characters
party_id
string = 3 characters
uid
string <= 36 characters
type
string <open-enum> (TokenType)
Enum Description
AD_HOC_USER

One time use Token ID generated by a server (or App.) The eMSP uses this to bind a Session to a customer, probably an app user.

APP_USER

Token ID generated by a server (or App.) to identify a user of an App. The same user uses the same Token for every Session.

EMAID

An EMAID. EMAIDs are used as Tokens when the Charging Station and the vehicle are using ISO 15118 for communication.

OTHER

Other type of token

RFID

RFID Token

The type of token.

contract_id
string <= 36 characters
visual_number
string <= 64 characters
issuer
string <= 64 characters
group_id
string <= 36 characters
valid
boolean
whitelist
string <enum> (WhitelistType)
Enum Description
ALWAYS

Token always has to be whitelisted, realtime authorization is not possible/allowed. CPO shall always allow any use of this Token.

ALLOWED

It is allowed to whitelist the token, realtime authorization is also allowed. The CPO may choose which version of authorization to use.

ALLOWED_OFFLINE

In normal situations realtime authorization shall be used. But when the CPO cannot get a response from the eMSP (communication between CPO and eMSP is offline), the CPO shall allow this Token to be used.

NEVER

Whitelisting is forbidden, only realtime authorization is allowed. CPO shall always send a realtime authorization for any use of this Token to the eMSP.

Defines when authorization of a Token by the CPO is allowed.

language
string = 2 characters
default_profile_type
string <enum> (ProfileType)
Enum Description
CHEAP

Driver wants to use the cheapest charging profile possible.

FAST

Driver wants his EV charged as quickly as possible and is willing to pay a premium for this, if needed.

GREEN

Driver wants his EV charged with as much regenerative (green) energy as possible.

REGULAR

Driver does not have special preferences.

Different smart charging profile types.

object (EnergyContract)

Information about an energy contract that belongs to a Token so a driver could use his/her own energy contract when charging at a Charge Point.

last_updated
required
string <date-time>
{
  • "country_code": "st",
  • "party_id": "str",
  • "uid": "string",
  • "type": "AD_HOC_USER",
  • "contract_id": "string",
  • "visual_number": "string",
  • "issuer": "string",
  • "group_id": "string",
  • "valid": true,
  • "whitelist": "ALWAYS",
  • "language": "st",
  • "default_profile_type": "CHEAP",
  • "energy_contract": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

CancelReservation

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between CancelReservation requests.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Charge Point already has a reservation that matches this reservationId the Charge Point will replace the reservation.

{}

CommandResponseType

string <enum> (CommandResponseType)
Enum Description
NOT_SUPPORTED

The requested command is not supported by this CPO, Charge Point, EVSE etc.

REJECTED

Command request rejected by the CPO. (Session might not be from a customer of the eMSP that sent this request)

ACCEPTED

Command request accepted by the CPO.

UNKNOWN_SESSION

The Session in the requested command is not known by this CPO.

Response to the command request from the eMSP to the CPO.

"NOT_SUPPORTED"

CommandResponse

result
required
string <enum> (CommandResponseType)
Enum Description
NOT_SUPPORTED

The requested command is not supported by this CPO, Charge Point, EVSE etc.

REJECTED

Command request rejected by the CPO. (Session might not be from a customer of the eMSP that sent this request)

ACCEPTED

Command request accepted by the CPO.

UNKNOWN_SESSION

The Session in the requested command is not known by this CPO.

Response from the CPO on the command request.

timeout
required
integer

Timeout for this command in seconds. When the Result is not received within this timeout, the eMSP can assume that the message might never be sent.

Array of objects (DisplayText)

Human-readable description of the result (if one can be provided), multiple languages can be provided.

{
  • "result": "NOT_SUPPORTED",
  • "timeout": 0,
  • "message": [
    ]
}

ReserveNow

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between ReserveNow requests.

required
object (Token)

Token object for how to reserve this Charge Point (and specific EVSE).

expiry_date
required
string <date-time>

The Date/Time when this reservation ends, in UTC.

reservation_id
required
string <= 36 characters

Reservation id, unique for this reservation. If the Receiver (typically CPO) Point already has a reservation that matches this reservationId for that Location it will replace the reservation.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) for which to reserve an EVSE.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location if a specific EVSE has to be reserved.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "expiry_date": "2019-08-24T14:15:22Z",
  • "reservation_id": "string",
  • "location_id": "string",
  • "evse_uid": "string",
  • "authorization_reference": "string"
}

StartSession

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StartSession requests.

required
object (Token)

Token object the Charge Point has to use to start a new session. The Token provided in this request is authorized by the eMSP.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) on which a session is to be started.

evse_uid
string <= 36 characters

Optional EVSE.uid of the EVSE of this Location on which a session is to be started. Required when connector_id is set.

connector_id
string <= 36 characters

Optional Connector.id of the Connector of the EVSE on which a session is to be started. This field is required when the capability START_SESSION_CONNECTOR_REQUIRED is set on the EVSE.

authorization_reference
string <= 36 characters

Reference to the authorization given by the eMSP, when given, this reference will be provided in the relevant Session and/or CDR.

{
  • "response_url": "http://example.com",
  • "token": {
    },
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string",
  • "authorization_reference": "string"
}

StopSession

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between StopSession requests.

session_id
required
string <= 36 characters

Session.id of the Session that is requested to be stopped.

{}

UnlockConnector

response_url
required
string <uri>

URL that the CommandResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between UnlockConnector requests.

location_id
required
string <= 36 characters

Location.id of the Location (belonging to the CPO this request is sent to) of which it is requested to unlock the connector.

evse_uid
required
string <= 36 characters

EVSE.uid of the EVSE of this Location of which it is requested to unlock the connector.

connector_id
required
string <= 36 characters

Connector.id of the Connector of this Location of which it is requested to unlock.

{
  • "response_url": "http://example.com",
  • "location_id": "string",
  • "evse_uid": "string",
  • "connector_id": "string"
}

ChargingProfileResponseType

string <enum> (ChargingProfileResponseType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the CPO, request will be forwarded to the EVSE.

NOT_SUPPORTED

The ChargingProfiles not supported by this CPO, Charge Point, EVSE etc.

REJECTED

ChargingProfile request rejected by the CPO. (Session might not be from a customer of the eMSP that sent this request)

TOO_OFTEN

ChargingProfile request rejected by the CPO, requests are sent more often than allowed.

UNKNOWN_SESSION

The Session in the requested command is not known by this CPO.

Response to the ChargingProfile request from the eMSP to the CPO.

"ACCEPTED"

ChargingProfileResponse

result
required
string <enum> (ChargingProfileResponseType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the CPO, request will be forwarded to the EVSE.

NOT_SUPPORTED

The ChargingProfiles not supported by this CPO, Charge Point, EVSE etc.

REJECTED

ChargingProfile request rejected by the CPO. (Session might not be from a customer of the eMSP that sent this request)

TOO_OFTEN

ChargingProfile request rejected by the CPO, requests are sent more often than allowed.

UNKNOWN_SESSION

The Session in the requested command is not known by this CPO.

Response from the CPO on the ChargingProfile request.

timeout
required
integer

Timeout for this ChargingProfile request in seconds. When the Result is not received within this timeout, the eMSP can assume that the message might never be sent.

{
  • "result": "ACCEPTED",
  • "timeout": 0
}

ChargingRateUnit

string <enum> (ChargingRateUnit)
Enum Description
W

Watts (power). This is the total allowed charging power. It is usually more convenient to use this for DC charging.

A

Amperes (current). The amount of Ampere per phase, not the sum of all phases. It is usually more convenient to use this for AC charging.

Unit in which a charging profile is defined.

"W"

ChargingProfilePeriod

start_period
required
integer

Start of the period, in seconds from the start of profile. The value of StartPeriod also defines the stop time of the previous period.

limit
required
number

Charging rate limit during the profile period, in the applicable chargingRateUnit, for example in Amperes (A) or Watts (W). Accepts at most one digit fraction (e.g. 8.1).

{
  • "start_period": 0,
  • "limit": 0
}

ChargingProfile

start_date_time
string <date-time>

Starting point of an absolute profile. If absent the profile will be relative to start of charging.

duration
integer

Duration of the charging profile in seconds. If the duration is left empty, the last period will continue indefinitely or until end of the transaction in case start_date_time is absent.

charging_rate_unit
required
string <enum> (ChargingRateUnit)
Enum Description
W

Watts (power). This is the total allowed charging power. It is usually more convenient to use this for DC charging.

A

Amperes (current). The amount of Ampere per phase, not the sum of all phases. It is usually more convenient to use this for AC charging.

The unit of measure.

min_charging_rate
number

Minimum charging rate supported by the EV. The unit of measure is defined by the chargingRateUnit. This parameter is intended to be used by a local smart charging algorithm to optimize the power allocation for in the case a charging process is inefficient at lower charging rates. Accepts at most one digit fraction (e.g. 8.1).

Array of objects (ChargingProfilePeriod)

List of ChargingProfilePeriod elements defining maximum power or current usage over time.

{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "duration": 0,
  • "charging_rate_unit": "W",
  • "min_charging_rate": 0,
  • "charging_profile_period": [
    ]
}

SetChargingProfile

required
object (ChargingProfile)

Contains limits for the available power or current over time.

response_url
required
string <uri>

URL that the ChargingProfileResult POST should be sent to. This URL might contain a unique ID to be able to distinguish between GET ActiveChargingProfile requests.

{
  • "charging_profile": {
    },
  • "response_url": "http://example.com"
}