API docs by Redocly

OCPI 2.3.0 - MSP 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 a Location

If the CPO wants to check the status of a Location object in the eMSP system, it might GET the object from the eMSP system for validation purposes. The CPO is the owner of the objects, so it would be illogical if the eMSP system had a different status or was missing an object. If a discrepancy is found, the CPO might push an update to the eMSP via a PUT or PATCH call.

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

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

Create or replace a Location

The CPO pushes available Location objects to the eMSP. PUT can be used to send new Location objects to the eMSP but also to replace existing Locations.

The country_code and party_id in the URL SHALL be the same value as the country_code and party_id in the Location object being pushed.

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

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.

Request Body schema: application/json
required

New Location object, or Location object to replace.

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Partially update a Location

Notify the eMSP of partial updates to a Location. Only the fields/objects that have to be updated have to be present, other fields/objects that are not specified are considered unchanged. This method is not suitable to remove information shared earlier.

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

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.

Request Body schema: application/json
required

The partial Location object containing only the fields to update. Must contain last_updated.

publish
boolean
Array of objects (PublishTokenType)
name
string <= 255 characters
address
string <= 45 characters
city
string <= 45 characters
postal_code
string <= 10 characters
state
string <= 20 characters
country
string = 3 characters
object (GeoLocation)

This class defines the geo location of the Charge Point. The geodetic system to be used is WGS 84. Five decimal places is seen as a minimum for GPS coordinates as this gives approximately 1 meter precision. More is always better. Seven decimal places gives approximately 1cm precision.

Array of objects (AdditionalGeoLocation)
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.

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

Array of objects (EVSE)
Array of objects (Parking)
Array of objects (DisplayText)
object (BusinessDetails)

Business details of an operator, suboperator, or owner.

object (BusinessDetails)

Business details of an operator, suboperator, or owner.

object (BusinessDetails)

Business details of an operator, suboperator, or owner.

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.

time_zone
string <= 255 characters
object (Hours)

Opening and access hours of the location.

charging_when_closed
boolean
Array of objects (Image)
object (EnergyMix)

This type is used to specify the energy mix and environmental impact of the supplied energy at a location or in a tariff.

help_phone
string <= 25 characters
last_updated
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Get an EVSE

Retrieve an EVSE as it is stored in the receiver's system. The EVSE object includes all Connectors belonging to it.

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

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

Create or replace an EVSE

The CPO pushes a new or updated EVSE object to the eMSP.

When the PUT only contains an EVSE Object, the Receiver SHALL also set the new last_updated value on the parent Location 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).

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.

Request Body schema: application/json
required

New EVSE object, or EVSE object to replace.

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Partially update an EVSE

Notify the eMSP of partial updates to an EVSE (such as the status). Only the fields that have to be updated need to be present.

Any request to the PATCH method SHALL contain the last_updated field.

When the PATCH is on an EVSE Object, the Receiver SHALL also set the new last_updated value on the parent Location 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).

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.

Request Body schema: application/json
required

The partial EVSE object containing only the fields to update. Must contain last_updated.

evse_id
string <= 48 characters
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.

Array of objects (StatusSchedule)
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.

Array of objects (Connector)
floor_level
string <= 4 characters
object (GeoLocation)

This class defines the geo location of the Charge Point. The geodetic system to be used is WGS 84. Five decimal places is seen as a minimum for GPS coordinates as this gives approximately 1 meter precision. More is always better. Seven decimal places gives approximately 1cm precision.

physical_reference
string <= 16 characters
Array of objects (DisplayText)
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.

Array of objects (EVSEParking)
accepted_service_providers
Array of strings[ items <= 50 characters ]
Array of objects (Image)
last_updated
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Get a Connector

Retrieve a Connector as it is stored in the receiver's system.

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

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

Create or replace a Connector

The CPO pushes a new or updated Connector object to the eMSP.

When the PUT only contains a Connector Object, the Receiver SHALL also set the new last_updated value on the parent EVSE and Location Objects.

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

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.

Request Body schema: application/json
required

New Connector object, or Connector object to replace.

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Partially update a Connector

Notify the eMSP of partial updates to a Connector (such as the tariff). Only the fields that have to be updated need to be present.

Any request to the PATCH method SHALL contain the last_updated field.

When the PATCH is on a Connector Object, the Receiver SHALL also set the new last_updated value on the parent EVSE and Location Objects.

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

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.

Request Body schema: application/json
required

The partial Connector object containing only the fields to update. Must contain last_updated.

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

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

power_type
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
integer
max_amperage
integer
max_electric_power
integer
tariff_ids
Array of strings[ items <= 36 characters ]
terms_and_conditions
string <uri>
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.

last_updated
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Sessions

Get a Session

The CPO system might request the current version of a Session object from the eMSP's system to, for example, validate the state, or because the CPO has received an error during a PATCH operation.

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

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.

Responses

Response samples

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

Create or replace a Session

Inform the eMSP's system about a new/updated Session object in the CPO's system.

When a PUT request is received for an existing Session object (the object is PUT to the same URL), the newly received Session object SHALL replace the existing object.

Any charging_periods from the existing object SHALL be replaced by the charging_periods from the newly received Session object. If the new Session object does not contain charging_periods (field is omitted or contains an empty list), the charging_periods of the existing object SHALL be removed (replaced by the new empty list).

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO performing this PUT on the eMSP’s system. This SHALL be the same value as the country_code in the Session object being pushed.

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO performing this PUT on the eMSP’s system. This SHALL be the same value as the party_id in the Session object being pushed.

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

New or updated Session object.

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Partially update a Session

Same as the PUT method, but only the fields/objects that need to be updated have to be present. Fields/objects which are not specified are considered unchanged.

Any request to the PATCH method SHALL contain the last_updated field.

The PATCH method works on the entire Session object only. It is not allowed to use extra URL segments to try to PATCH fields of inner objects of the Session object directly.

When a PATCH request contains the charging_periods field (inside a Session object), this SHALL be processed as a request to add all the ChargingPeriod objects to the existing Session object. If the request charging_periods list is omitted (or contains an empty list), no changes SHALL be made to the existing list of charging_periods.

If existing ChargingPeriod objects in a Session need to be replaced or removed, the Sender SHALL use the PUT method to replace the entire Session object (including all the charging_periods).

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

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

The partial Session object containing only the fields to update. Must contain last_updated.

start_date_time
string <date-time>
end_date_time
string <date-time>
kwh
number
object (CdrToken)

Token information used to start a charging session, containing all relevant information to identify the unique token.

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

authorization_reference
string <= 36 characters
location_id
string <= 36 characters
evse_uid
string <= 36 characters
connector_id
string <= 36 characters
meter_id
string <= 255 characters
currency
string = 3 characters
Array of objects (ChargingPeriod)

When present in a PATCH, these ChargingPeriod objects are added to the existing list.

object (Price)

Price information with tax details.

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

last_updated
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

CDRs

Create a new CDR

Creates a new CDR. The POST method should contain the full and final CDR object. CDRs cannot be changed or replaced once sent. Instead, a Credit CDR can be sent.

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

The new CDR object.

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Retrieve an existing CDR

Fetch a CDR from the receiver's system. The actual URL structure is open to the eMSP to define. The URL is provided to the CPO by the eMSP in the Location header of the POST response. Therefore, OCPI does not strictly define variables for this endpoint. The path shown here is a typical implementation pattern.

Authorizations:
ocpiAuthorization
path Parameters
cdr_id
required
string

ID of the CDR to retrieve. The actual URL is provided by the eMSP in the POST response Location header.

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

Retrieve a Tariff

If the CPO wants to check the status of a Tariff in the eMSP's system, it might GET the object from the eMSP's system for validation purposes. After all, the CPO is the owner of the object, so it would be illogical if the eMSP's system had a different status or was missing the object entirely.

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

tariff_id
required
string <= 36 characters

Tariff.id of the Tariff 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.

Responses

Response samples

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

Create or update a Tariff

Push new or updated Tariff object to the eMSP.

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

tariff_id
required
string <= 36 characters

Tariff.id of the Tariff 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

New or updated Tariff object.

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

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

Delete a Tariff

Delete a Tariff object which is not used any more and will not be used in the future. Before deleting a Tariff object, it is RECOMMENDED to ensure that the Tariff object is not referenced by any Connector object within the tariff_ids.

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

tariff_id
required
string <= 36 characters

Tariff.id of the Tariff 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.

Responses

Response samples

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

Tokens

Get list of Tokens

Fetch information about Tokens known in the eMSP systems. If additional parameters date_from and/or date_to are provided, only Tokens 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": [
    ]
}

Real-time authorization request

Do a 'real-time' authorization request to the eMSP system, validating if a Token might be used (at the optionally given Location).

When the eMSP does not know the Token, the eMSP SHALL respond with an HTTP status code: 404 (Not Found).

When the eMSP receives a 'real-time' authorization request from a CPO that contains too little information (no LocationReferences provided) to determine if the Token might be used, the eMSP SHALL respond with the OCPI status: 2002.

Authorizations:
ocpiAuthorization
path Parameters
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
optional

Optional LocationReferences object. The eMSP SHALL then validate if the Token is allowed to be used at this Location, and if applicable: which of the Location's EVSEs. The object with valid Location and EVSEs will be returned in the response.

location_id
required
string <= 36 characters

Unique identifier for the location.

evse_uids
Array of strings[ items <= 36 characters ]

Unique identifiers for EVSEs within the CPO's platform for the EVSE within the given location.

Responses

Request samples

Content type
application/json
{
  • "location_id": "string",
  • "evse_uids": [
    ]
}

Response samples

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

Commands

Receive asynchronous command result

It is up to the implementation of the eMSP to determine what parameters are put in the URL. The eMSP sends a URL in the POST method body to the CPO. The CPO is required to use this URL for the asynchronous response by the Charge Point. It is advised to make this URL unique for every request to differentiate simultaneous commands, for example by adding a unique id as a URL segment.

No structure defined. This is open to the Sender to define, the URL is provided to the Receiver by the Sender in the POST to the Receiver interface. Therefor OCPI does not define variables.

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

Result of the command request, from the Charge Point.

result
required
string <enum> (CommandResultType)
Enum Description
ACCEPTED

Command request accepted by the Charge Point.

CANCELED_RESERVATION

The Reservation has been canceled by the CPO.

EVSE_OCCUPIED

EVSE is currently occupied, another session is ongoing. Cannot start a new session.

EVSE_INOPERATIVE

EVSE is currently inoperative or faulted.

FAILED

Execution of the command failed at the Charge Point.

NOT_SUPPORTED

The requested command is not supported by this Charge Point, EVSE etc.

REJECTED

Command request rejected by the Charge Point.

TIMEOUT

Command request timeout, no response received from the Charge Point in a reasonable time.

UNKNOWN_RESERVATION

The Reservation in the requested command is not known by this Charge Point.

Result of the command request as sent by the Charge Point to the CPO.

Array of objects (DisplayText)

Human-readable description of the reason (if one can be provided), multiple languages can be provided.

Responses

Request samples

Content type
application/json
{
  • "result": "ACCEPTED",
  • "message": [
    ]
}

Response samples

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

ChargingProfiles

Receive asynchronous charging profile result

Receive the asynchronous response from the Charge Point.

As the Sender interface is called by the Receiver (typically CPO) on the URL given response_url in the Sender request to the Receiver interface. It is up to the implementation of the Sender (typically SCSP) to determine what parameters are put in the URL. The Sender sends a URL in the POST method body to the Receiver. The Receiver is required to use this URL for the asynchronous response by the Charge Point. It is advised to make this URL unique for every request to differentiate simultaneous commands, for example by adding a unique id as a URL segment.

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

Choice: one of three. ActiveChargingProfileResult: Result of the GET ActiveChargingProfile request, from the Charge Point. ChargingProfileResult: Result of the PUT ChargingProfile request, from the Charge Point. ClearProfileResult: Result of the DELETE ChargingProfile request, from the Charge Point.

One of
result
required
string <enum> (ChargingProfileResultType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the request for the ActiveChargingProfile

object (ActiveChargingProfile)

The requested ActiveChargingProfile, if the result field is set to: ACCEPTED

Responses

Request samples

Content type
application/json
Example
{
  • "result": "ACCEPTED",
  • "profile": {
    }
}

Response samples

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

Receive updated ActiveChargingProfile

Updates the Sender (typically SCSP) when the Receiver (typically CPO) knows the ActiveChargingProfile has changed.

The Receiver SHALL call this interface every time it knows changes have been made that influence the ActiveChargingProfile for an ongoing session AND the Sender has at least once successfully called the charging profile Receiver PUT interface for this session (SetChargingProfile). If the Receiver doesn’t know the ActiveChargingProfile has changed (EVSE does not notify the Receiver (typically CPO) of the change) it is not required to call this interface.

The Receiver SHALL NOT call this interface for any session where the Sender has never, successfully called the charging profile Receiver PUT interface for this session (SetChargingProfile).

The Receiver SHALL send a useful relevant duration of ActiveChargingProfile to send to the Sender. As a guide: between 5 and 60 minutes. If the Sender wants a longer ActiveChargingProfile the Sender can always do a GET with a longer duration.

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

The new ActiveChargingProfile. If there is no longer any charging profile active, the ActiveChargingProfile SHALL reflect this by showing the maximum charging capacity of the EVSE.

start_date_time
required
string <date-time>

Date and time at which the Charge Point has calculated this ActiveChargingProfile. All time measurements within the profile are relative to this timestamp.

required
object (ChargingProfile)

Charging profile structure defines a list of charging periods.

Responses

Request samples

Content type
application/json
{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "charging_profile": {
    }
}

Response samples

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

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

LocationPatch

publish
boolean
Array of objects (PublishTokenType)
name
string <= 255 characters
address
string <= 45 characters
city
string <= 45 characters
postal_code
string <= 10 characters
state
string <= 20 characters
country
string = 3 characters
object (GeoLocation)

This class defines the geo location of the Charge Point. The geodetic system to be used is WGS 84. Five decimal places is seen as a minimum for GPS coordinates as this gives approximately 1 meter precision. More is always better. Seven decimal places gives approximately 1cm precision.

Array of objects (AdditionalGeoLocation)
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.

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

Array of objects (EVSE)
Array of objects (Parking)
Array of objects (DisplayText)
object (BusinessDetails)

Business details of an operator, suboperator, or owner.

object (BusinessDetails)

Business details of an operator, suboperator, or owner.

object (BusinessDetails)

Business details of an operator, suboperator, or owner.

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.

time_zone
string <= 255 characters
object (Hours)

Opening and access hours of the location.

charging_when_closed
boolean
Array of objects (Image)
object (EnergyMix)

This type is used to specify the energy mix and environmental impact of the supplied energy at a location or in a tariff.

help_phone
string <= 25 characters
last_updated
required
string <date-time>
{
  • "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"
}

EVSEPatch

evse_id
string <= 48 characters
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.

Array of objects (StatusSchedule)
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.

Array of objects (Connector)
floor_level
string <= 4 characters
object (GeoLocation)

This class defines the geo location of the Charge Point. The geodetic system to be used is WGS 84. Five decimal places is seen as a minimum for GPS coordinates as this gives approximately 1 meter precision. More is always better. Seven decimal places gives approximately 1cm precision.

physical_reference
string <= 16 characters
Array of objects (DisplayText)
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.

Array of objects (EVSEParking)
accepted_service_providers
Array of strings[ items <= 50 characters ]
Array of objects (Image)
last_updated
required
string <date-time>
{
  • "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"
}

ConnectorPatch

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

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

power_type
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
integer
max_amperage
integer
max_electric_power
integer
tariff_ids
Array of strings[ items <= 36 characters ]
terms_and_conditions
string <uri>
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.

last_updated
required
string <date-time>
{
  • "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"
}

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

SessionPatch

start_date_time
string <date-time>
end_date_time
string <date-time>
kwh
number
object (CdrToken)

Token information used to start a charging session, containing all relevant information to identify the unique token.

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

authorization_reference
string <= 36 characters
location_id
string <= 36 characters
evse_uid
string <= 36 characters
connector_id
string <= 36 characters
meter_id
string <= 255 characters
currency
string = 3 characters
Array of objects (ChargingPeriod)

When present in a PATCH, these ChargingPeriod objects are added to the existing list.

object (Price)

Price information with tax details.

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

last_updated
required
string <date-time>
{
  • "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"
}

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"

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"

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

LocationReferences

location_id
required
string <= 36 characters

Unique identifier for the location.

evse_uids
Array of strings[ items <= 36 characters ]

Unique identifiers for EVSEs within the CPO's platform for the EVSE within the given location.

{
  • "location_id": "string",
  • "evse_uids": [
    ]
}

AllowedType

string <enum> (AllowedType)
Enum Description
ALLOWED

This Token is allowed to charge (at this location).

BLOCKED

This Token is blocked.

EXPIRED

This Token has expired.

NO_CREDIT

This Token belongs to an account that has not enough credits to charge (at the given location).

NOT_ALLOWED

Token is valid, but is not allowed to charge at the given location.

Defines the allowed status of a Token.

"ALLOWED"

AuthorizationInfo

allowed
required
string <enum> (AllowedType)
Enum Description
ALLOWED

This Token is allowed to charge (at this location).

BLOCKED

This Token is blocked.

EXPIRED

This Token has expired.

NO_CREDIT

This Token belongs to an account that has not enough credits to charge (at the given location).

NOT_ALLOWED

Token is valid, but is not allowed to charge at the given location.

Status of the Token, and whether charging is allowed at the optionally given location.

required
object (Token)

The complete Token object for which this authorization was requested.

object (LocationReferences)

Optional reference to the location if it was included in the request, and if the EV driver is allowed to charge at that location. Only the EVSEs the EV driver is allowed to charge at are returned.

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.

object (DisplayText)

Optional display text, additional information to the EV driver.

{
  • "allowed": "ALLOWED",
  • "token": {
    },
  • "location": {
    },
  • "authorization_reference": "string",
  • "info": {
    }
}

CommandResultType

string <enum> (CommandResultType)
Enum Description
ACCEPTED

Command request accepted by the Charge Point.

CANCELED_RESERVATION

The Reservation has been canceled by the CPO.

EVSE_OCCUPIED

EVSE is currently occupied, another session is ongoing. Cannot start a new session.

EVSE_INOPERATIVE

EVSE is currently inoperative or faulted.

FAILED

Execution of the command failed at the Charge Point.

NOT_SUPPORTED

The requested command is not supported by this Charge Point, EVSE etc.

REJECTED

Command request rejected by the Charge Point.

TIMEOUT

Command request timeout, no response received from the Charge Point in a reasonable time.

UNKNOWN_RESERVATION

The Reservation in the requested command is not known by this Charge Point.

Result of the command that was sent to the Charge Point.

"ACCEPTED"

CommandResult

result
required
string <enum> (CommandResultType)
Enum Description
ACCEPTED

Command request accepted by the Charge Point.

CANCELED_RESERVATION

The Reservation has been canceled by the CPO.

EVSE_OCCUPIED

EVSE is currently occupied, another session is ongoing. Cannot start a new session.

EVSE_INOPERATIVE

EVSE is currently inoperative or faulted.

FAILED

Execution of the command failed at the Charge Point.

NOT_SUPPORTED

The requested command is not supported by this Charge Point, EVSE etc.

REJECTED

Command request rejected by the Charge Point.

TIMEOUT

Command request timeout, no response received from the Charge Point in a reasonable time.

UNKNOWN_RESERVATION

The Reservation in the requested command is not known by this Charge Point.

Result of the command request as sent by the Charge Point to the CPO.

Array of objects (DisplayText)

Human-readable description of the reason (if one can be provided), multiple languages can be provided.

{
  • "result": "ACCEPTED",
  • "message": [
    ]
}

ChargingProfileResultType

string <enum> (ChargingProfileResultType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

Result of a ChargingProfile request that the EVSE sends via the CPO to the eMSP.

"ACCEPTED"

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": [
    ]
}

ActiveChargingProfile

start_date_time
required
string <date-time>

Date and time at which the Charge Point has calculated this ActiveChargingProfile. All time measurements within the profile are relative to this timestamp.

required
object (ChargingProfile)

Charging profile structure defines a list of charging periods.

{
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "charging_profile": {
    }
}

ActiveChargingProfileResult

result
required
string <enum> (ChargingProfileResultType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the request for the ActiveChargingProfile

object (ActiveChargingProfile)

The requested ActiveChargingProfile, if the result field is set to: ACCEPTED

{
  • "result": "ACCEPTED",
  • "profile": {
    }
}

ChargingProfileResult

result
required
string <enum> (ChargingProfileResultType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the new/updated charging profile.

{
  • "result": "ACCEPTED"
}

ClearProfileResult

result
required
string <enum> (ChargingProfileResultType)
Enum Description
ACCEPTED

ChargingProfile request accepted by the EVSE.

REJECTED

ChargingProfile request rejected by the EVSE.

UNKNOWN

No Charging Profile(s) were found by the EVSE matching the request.

The EVSE will indicate if it was able to process the removal of the charging profile (ClearChargingProfile).

{
  • "result": "ACCEPTED"
}