OCPI 2.2.1-d2 Module: locations

Locations Module

The Location objects live in the CPO back-end system. They describe the charging locations of an operator. This module covers the flow, interfaces, object descriptions, and data types for managing charging locations via OCPI.

5 Sections

Data owner: CPO

Functional Module

1. Overview

Introduction

The Location objects live in the CPO back-end system. They describe the charging locations of an operator.

Module Information

Module Identifier

locations

Data Owner

CPO

Type

Functional Module

Module Dependency

Receiver endpoint is dependent on the Tariffs module.

2. Flow and Lifecycle

Lifecycle

The Locations module has the Location as base object. Each Location can have multiple EVSEs (1:n) and each EVSE can have multiple Connectors (1:n). With the methods in the Receiver interface, Location data and status information can be shared with for example an eMSP and NSP. Updates can be made to a whole Location, but also only to an EVSE or a single Connector.

The CPO creates Location objects and pushes them to connected eMSPs via PUT. eMSPs that do not support Push can use GET to retrieve Location data.

The CPO replaces objects by performing a PUT request on the Receiver interface.

Changes can be pushed via PATCH, sending only the actual changes. eMSPs that do not support Push can use GET to stay up to date.

To delete an EVSE, the CPO sets its status to REMOVED and calls PUT or PATCH. A Location without any valid EVSEs is considered expired. There is no way to delete Location, EVSE, or Connector objects, as charging sessions may still reference them.

The CPO can use GET on the Receiver interface to validate that objects in the eMSP system match the CPO's own records.

Private charging locations SHALL NOT be published via OCPI. Only locations intended for public or roaming use should be shared with receiving parties.

No Public Charging or Roaming

When a Location is not available for either Public Charging or Roaming, it is RECOMMENDED to NOT send that Location via OCPI to receiving parties.

Group of Charge Points

OCPP 2.0 uses a 3-tier model: Charge Point > EVSE > Connector. OCPI uses a similar model: Location > EVSE > Connector.

There are two options for mapping a group of Charge Points to OCPI: create one Location for the entire group (preferred), or create one Location per Charge Point. OCPI prefers grouping all Charge Points at the same physical location into a single Location object, as this provides a better user experience for EV drivers looking for available charging stations.

Note: By definition, an EVSE can only charge one EV at a time.

OCPP 1.x Charge Points with Multiple Connectors per EVSE

OCPP 1.x had no notion of EVSEs. A Charge Point in OCPP 1.x could have multiple Connectors, but there was no concept of grouping Connectors into EVSEs. As a workaround, when mapping OCPP 1.x Charge Points to OCPI, one "virtual" EVSE should be defined per Connector.

When a Connector on a hardware EVSE becomes unavailable, all virtual EVSEs for all Connectors of that hardware EVSE should be set to UNAVAILABLE. This ensures that EV drivers see an accurate representation of the physical charging infrastructure.

3. Interfaces and Endpoints

API

There are both, a Sender and a Receiver interface for Locations. It is advised to use the Push direction from Sender to Receiver during normal operation in order to keep the latency of updates low. The Sender interface is meant to be used when the connection between two parties is established for the first time, to retrieve the current list of Location objects with the current status, and when the Receiver is not 100% sure the Location cache is entirely up-to-date (i.e. to perform a full sync). The Receiver can also use the Sender GET Object interface to retrieve a specific Location, EVSE or Connector.

3.1 Sender Interface

Typically implemented by market roles like: CPO.

Method	Description
`GET`	Fetch a list of Locations, last updated between the {date_from} and {date_to} (paginated), or get a specific Location, EVSE or Connector.
`POST`	n/a
`PUT`	n/a
`PATCH`	n/a
`DELETE`	n/a

GET List: Request Parameters

GET

Endpoint structure:

{locations_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limit}]

Example GET List URLs

https://www.server.com/ocpi/cpo/2.2.1/locations/?date_from=2019-01-28T12:00:00&date_to=2019-01-29T12:00:00
https://www.server.com/ocpi/cpo/2.2.1/locations/?offset=50
https://www.server.com/ocpi/cpo/2.2.1/locations/?date_from=2019-01-29T12:00:00&limit=100
https://www.server.com/ocpi/cpo/2.2.1/locations/?offset=50&limit=100

If additional parameters: {date_from} and/or {date_to} are provided, only Locations with last_updated between the given {date_from} (including) and {date_to} (excluding) will be returned. In order for this to work correctly, the following needs to be taken into account: If an EVSE is updated, also the last_updated field of the Location containing that EVSE needs to be set to the moment of the update of the EVSE. The same is valid for a Connector that is updated: the parent EVSE AND the Location objects need to have their last_updated fields updated.

Parameter	Datatype	Required	Description
`date_from`	DateTime	no	Only return Locations that have `last_updated` after or equal to this Date/Time (inclusive).
`date_to`	DateTime	no	Only return Locations that have `last_updated` up to this Date/Time, but not including (exclusive).
`offset`	int	no	The offset of the first object returned. Default is 0.
`limit`	int	no	Maximum number of objects in the GET response. The server may decide to return fewer objects.

GET List: Response Data

The endpoint returns a list of Location objects matching the given parameters in the GET request, with the pagination-related HTTP headers in the response. Each request shall also contain the pagination-related HTTP headers.

Datatype	Card.	Description
Location	*	List of all Locations with valid EVSEs.

GET Object: Request Parameters

GET

Endpoint structure:

{locations_endpoint_url}/{location_id}[/{evse_uid}][/{connector_id}]

Example GET Object URLs

https://www.server.com/ocpi/cpo/2.2.1/locations/LOC1
https://www.server.com/ocpi/cpo/2.2.1/locations/LOC1/3256
https://www.server.com/ocpi/cpo/2.2.1/locations/LOC1/3256/1

Parameter	Datatype	Required	Description
`location_id`	CiString(36)	yes	Location.id of the Location object to retrieve.
`evse_uid`	CiString(36)	no	Evse.uid, required when requesting an EVSE or Connector object.
`connector_id`	CiString(36)	no	Connector.id, required when requesting a Connector object.

GET Object: Response Data

The response contains the requested object. Depending on the URL segments provided, the response contains one of the following:

Datatype	Card.	Description
Location	1	If only location_id was provided.
EVSE	1	If location_id and evse_uid were provided.
Connector	1	If location_id, evse_uid and connector_id were provided.

3.2 Receiver Interface

Typically implemented by market roles like: eMSP and NSP.

Locations are Client Owned Objects, so the end-points need to contain the required extra fields: {party_id} and {country_code}.

Endpoint structure:

{locations_endpoint_url}/{country_code}/{party_id}/{location_id}[/{evse_uid}][/{connector_id}]

Example Receiver Interface URLs

https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012
https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012/3256
https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012/3256/1

Method	Description
`GET`	Retrieve a Location as it is stored in the eMSP system.
`POST`	n/a (use PUT)
`PUT`	Push new/updated Location, EVSE or Connector to the eMSP.
`PATCH`	Notify the eMSP of partial updates to a Location, EVSE or Connector (e.g. status update).
`DELETE`	n/a (use PATCH to set status to `REMOVED`)

Receiver GET Method

GET

If the CPO wants to check the status of a Location, EVSE or Connector object in the eMSP system, it can issue a GET request to retrieve the object as stored in the eMSP system. This can be useful for debugging or verifying that objects have been synchronized correctly.

Parameter	Datatype	Required	Description
`country_code`	CiString(2)	yes	Country code of the CPO requesting this GET from the eMSP system.
`party_id`	CiString(3)	yes	Party ID (Provider ID) of the CPO requesting this GET from the eMSP system.
`location_id`	CiString(36)	yes	Location.id of the Location object to retrieve.
`evse_uid`	CiString(36)	no	Evse.uid, required when requesting an EVSE or Connector object.
`connector_id`	CiString(36)	no	Connector.id, required when requesting a Connector object.

Receiver GET: Response Data

The response contains the requested object. Depending on the URL segments provided, the response contains one of the following:

Datatype	Card.	Description
Location	1	If only location_id was provided.
EVSE	1	If location_id and evse_uid were provided.
Connector	1	If location_id, evse_uid and connector_id were provided.

Receiver PUT Method

PUT

The CPO pushes available Location, EVSE or Connector objects to the eMSP. PUT is used to send new Location objects to the eMSP, or to replace existing Locations.

When a PUT request contains only a Connector object, the Receiver should also set the last_updated field on the parent EVSE and the parent Location. Similarly, when a PUT contains an EVSE object, the Receiver should set the last_updated field on the parent Location.

Parameter	Datatype	Required	Description
`country_code`	CiString(2)	yes	Country code of the CPO that 'owns' this Location. Must match the value in the Location object.
`party_id`	CiString(3)	yes	Party ID (Provider ID) of the CPO that 'owns' this Location. Must match the value in the Location object.
`location_id`	CiString(36)	yes	Location.id of the new or updated Location object.
`evse_uid`	CiString(36)	no	Evse.uid, required when pushing an EVSE or Connector object.
`connector_id`	CiString(36)	no	Connector.id, required when pushing a Connector object.

Receiver PUT: Request Body

The request body contains the new or updated object. Depending on the URL segments provided, the body contains one of the following:

Datatype	Card.	Description
Location	1	New or updated Location object (if only location_id provided).
EVSE	1	New or updated EVSE object (if location_id and evse_uid provided).
Connector	1	New or updated Connector object (if location_id, evse_uid and connector_id provided).

Add an EVSE

PUT To URL: https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012/3256

{
  "uid": "3256",
  "evse_id": "BE*BEC*E041503003",
  "status": "AVAILABLE",
  "capabilities": ["RESERVABLE"],
  "connectors": [
    {
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "tariff_ids": ["14"]
    }
  ],
  "floor": -1,
  "physical_reference": 3,
  "last_updated": "2019-06-24T12:39:09Z"
}

Receiver PATCH Method

PATCH

Same as the PUT method, but only the fields/objects that have to be updated need to be present in the request body. Any field that is not included in the request body will remain unchanged. This method is not suitable to remove information that was shared earlier.

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

When a PATCH request updates a Connector object, the Receiver should also update the last_updated field on the parent EVSE and the parent Location. Similarly, when a PATCH updates an EVSE object, the Receiver should update the last_updated field on the parent Location.

Simple status update

PATCH To URL: https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012/3255

{
  "status": "CHARGING",
  "last_updated": "2019-06-24T12:39:09Z"
}

Change location name

PATCH To URL: https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012

{
  "name": "Interparking Gent Zuid",
  "last_updated": "2019-06-24T12:39:09Z"
}

Set tariff update

PATCH To URL: https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012/3255/2

{
  "tariff_ids": ["15"],
  "last_updated": "2019-06-24T12:39:09Z"
}

Delete an EVSE

PATCH To URL: https://www.server.com/ocpi/emsp/2.2.1/locations/NL/TNM/1012/3256

{
  "status": "REMOVED",
  "last_updated": "2019-06-24T12:39:09Z"
}

Note

To schedule the removal of an EVSE in the future, the status_schedule field of the EVSE can be used. This allows the CPO to inform the eMSP that a given EVSE will change its status at a specified point in time, including transitioning to REMOVED.

4. Object Description

Objects

The Locations module uses a hierarchical object model to describe charging infrastructure. The relationship between the main objects is as follows:

Location (1) ---- (0..n) EVSE (1) ---- (1..n) Connector

4.1 Location Object

class

The Location object describes a charging location and its properties. A Location has one or more EVSEs (Electric Vehicle Supply Equipment). The Location object also includes information about the operator, facilities, parking options, and opening hours.

The publish field determines the visibility of a Location. When set to true, the Location may be shown in apps and published to receivers. When set to false, only token owners listed in the publish_allowed_to list are allowed to see the Location. The PublishTokenType matching is used to determine which tokens grant visibility: if any of the specified fields match (e.g. visual_number, issuer, uid, or type), the token owner is granted access to view the Location details.

Property	Type	Cardinality	Description
`country_code`	`CiString(2)`	`1`	ISO-3166 alpha-2 country code of the CPO that 'owns' this Location.
`party_id`	`CiString(3)`	`1`	ID of the CPO that 'owns' this Location (following the ISO-15118 standard).
`id`	`CiString(36)`	`1`	Uniquely identifies the Location within the CPO's platform (and suboperator platforms). This field can not be changed, modified or renamed.
`publish`	`boolean`	`1`	Defines if a Location may be published on an informational website or app. When this is set to `false`, only tokens identified in the `publish_allowed_to` field are permitted to be shown this Location.
`publish_allowed_to`	`PublishTokenType`	`*`	Only used when `publish` is `false`. Defines the set of token(s) that have visibility on this Location through matching criteria.
`name`	`string(255)`	`?`	Display name of the Location.
`address`	`string(45)`	`1`	Street/block name and house number if available.
`city`	`string(45)`	`1`	City or town.
`postal_code`	`string(10)`	`?`	Postal code of the Location, may be omitted when the Location has no postal code (e.g. for highway locations).
`state`	`string(20)`	`?`	State or province of the Location.
`country`	`string(3)`	`1`	ISO 3166-1 alpha-3 code for the country of this Location.
`coordinates`	`GeoLocation`	`1`	Coordinates of the Location.
`related_locations`	`AdditionalGeoLocation`	`*`	Geographical location of related points relevant to the user.
`parking_type`	`ParkingType`	`?`	The general type of parking at the charge point Location.
`evses`	`EVSE`	`*`	List of EVSEs that belong to this Location.
`directions`	`DisplayText`	`*`	Human-readable directions on how to reach the Location.
`operator`	`BusinessDetails`	`?`	Information of the operator.
`suboperator`	`BusinessDetails`	`?`	Information of the suboperator if applicable.
`owner`	`BusinessDetails`	`?`	Information of the owner if available.
`facilities`	`Facility`	`*`	Optional list of facilities this charging Location directly belongs to.
`time_zone`	`string(255)`	`1`	One of IANA tzdata's TZ-values representing the time zone of the Location. Examples: "Europe/Oslo", "Europe/Zurich".
`opening_times`	`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: `true`.
`images`	`Image`	`*`	Links to images related to the Location such as photos or logos.
`energy_mix`	`EnergyMix`	`?`	Details on the energy supplied at this Location.
`last_updated`	`DateTime`	`1`	Timestamp when this Location or one of its EVSEs or Connectors were last updated (or created).

Note: Private Charge Points that do not need to be published on apps and do not require remote control via OCPI SHOULD NOT be PUT via the OCPI Locations module.

4.1.1 Location Examples

Public charging location

A publicly available on-street charging location with publish set to true and parking_type set to ON_STREET.

Public charging location

{
  "country_code": "BE",
  "party_id": "BEC",
  "id": "LOC1",
  "publish": true,
  "name": "Gent Zuid",
  "address": "F.Rooseveltlaan 3A",
  "city": "Gent",
  "postal_code": "9000",
  "country": "BEL",
  "coordinates": {
    "latitude": "51.047599",
    "longitude": "3.729944"
  },
  "parking_type": "ON_STREET",
  "evses": [{
    "uid": "3256",
    "evse_id": "BE*BEC*E041503001",
    "status": "AVAILABLE",
    "capabilities": ["RESERVABLE"],
    "connectors": [{
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "CABLE",
      "power_type": "AC_3_PHASE",
      "max_voltage": 220,
      "max_amperage": 16,
      "tariff_ids": ["11"],
      "last_updated": "2015-03-16T10:10:02Z"
    }, {
      "id": "2",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "power_type": "AC_3_PHASE",
      "max_voltage": 220,
      "max_amperage": 16,
      "tariff_ids": ["13"],
      "last_updated": "2015-03-18T08:12:01Z"
    }],
    "physical_reference": "1",
    "floor_level": "-1",
    "last_updated": "2015-06-28T08:12:01Z"
  }, {
    "uid": "3257",
    "evse_id": "BE*BEC*E041503002",
    "status": "RESERVED",
    "capabilities": ["RESERVABLE"],
    "connectors": [{
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "power_type": "AC_3_PHASE",
      "max_voltage": 220,
      "max_amperage": 16,
      "tariff_ids": ["12"],
      "last_updated": "2015-06-29T20:39:09Z"
    }],
    "physical_reference": "2",
    "floor_level": "-2",
    "last_updated": "2015-06-29T20:39:09Z"
  }],
  "operator": {
    "name": "BeCharged"
  },
  "time_zone": "Europe/Brussels",
  "last_updated": "2015-06-29T20:39:09Z"
}

Destination charging location

A destination charging location such as a restaurant, office, or shopping center with publish set to true, parking_type set to PARKING_LOT, and EVSE.parking_restrictions set to CUSTOMERS.

Destination charging location

{
  "country_code": "NL",
  "party_id": "ALF",
  "id": "3e7b39c2-10d0-4138-a8b3-8509a25f9920",
  "publish": true,
  "name": "ihomer",
  "address": "Tamboerijn 7",
  "city": "Etten-Leur",
  "postal_code": "4876 BS",
  "country": "NLD",
  "coordinates": {
    "latitude": "51.562787",
    "longitude": "4.638975"
  },
  "parking_type": "PARKING_LOT",
  "evses": [{
    "uid": "fd855359-bc81-47bb-bb89-849ae3dac89e",
    "evse_id": "NL*ALF*E000000001",
    "status": "AVAILABLE",
    "connectors": [{
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "power_type": "AC_3_PHASE",
      "max_voltage": 220,
      "max_amperage": 16,
      "last_updated": "2019-07-01T12:12:11Z"
    }],
    "parking_restrictions": ["CUSTOMERS"],
    "last_updated": "2019-07-01T12:12:11Z"
  }],
  "time_zone": "Europe/Amsterdam",
  "last_updated": "2019-07-01T12:12:11Z"
}

Destination charging - not published, paid guest usage

A destination charging location with publish set to false and publish_allowed_to not used. No parking_type is specified. The eMSP helpdesk can use this information to assist EV drivers, but selection via an app is not possible.

Destination charging - not published

{
  "country_code": "NL",
  "party_id": "ALF",
  "id": "3e7b39c2-10d0-4138-a8b3-8509a25f9920",
  "publish": false,
  "name": "ihomer",
  "address": "Tamboerijn 7",
  "city": "Etten-Leur",
  "postal_code": "4876 BS",
  "country": "NLD",
  "coordinates": {
    "latitude": "51.562787",
    "longitude": "4.638975"
  },
  "evses": [{
    "uid": "fd855359-bc81-47bb-bb89-849ae3dac89e",
    "evse_id": "NL*ALF*E000000001",
    "status": "AVAILABLE",
    "connectors": [{
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "power_type": "AC_3_PHASE",
      "max_voltage": 220,
      "max_amperage": 16,
      "last_updated": "2019-07-01T12:12:11Z"
    }],
    "parking_restrictions": ["CUSTOMERS"],
    "last_updated": "2019-07-01T12:12:11Z"
  }],
  "time_zone": "Europe/Amsterdam",
  "last_updated": "2019-07-01T12:12:11Z"
}

Limited visibility location

A location with publish set to false and a publish_allowed_to list specifying which tokens may see this Location. Typical use cases include apartment garages, offices, and vehicle depots.

Limited visibility location

{
  "country_code": "NL",
  "party_id": "ALL",
  "id": "f76c2e0c-a6ef-4f67-bf23-6a187e5ca0e0",
  "publish": false,
  "publish_allowed_to": [{
    "visual_number": "12345-67",
    "issuer": "NewMotion"
  }, {
    "visual_number": "0055375624",
    "issuer": "ANWB"
  }, {
    "uid": "12345678905880",
    "type": "RFID"
  }],
  "name": "Water State",
  "address": "Taco van der Veenplein 12",
  "city": "Leeuwarden",
  "postal_code": "8923 EM",
  "country": "NLD",
  "coordinates": {
    "latitude": "53.213763",
    "longitude": "5.804638"
  },
  "parking_type": "UNDERGROUND_GARAGE",
  "evses": [{
    "uid": "8c1b3487-61ac-40a7-a367-21eee99dbd90",
    "evse_id": "NL*ALL*EG00000013",
    "status": "AVAILABLE",
    "connectors": [{
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "power_type": "AC_3_PHASE",
      "max_voltage": 230,
      "max_amperage": 16,
      "last_updated": "2019-09-27T00:19:45Z"
    }],
    "last_updated": "2019-09-27T00:19:45Z"
  }],
  "time_zone": "Europe/Amsterdam",
  "last_updated": "2019-09-27T00:19:45Z"
}

Private charge point with eMSP app control

A private charge point with publish set to false and publish_allowed_to containing only the owner's token. The parking_type is ON_DRIVEWAY.

Private charge point with eMSP app control

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "a5295927-09b9-4a71-b4b9-a5fffdfa0b77",
  "publish": false,
  "publish_allowed_to": [{
    "visual_number": "0123456-99",
    "issuer": "MoveMove"
  }],
  "address": "Krautwigstrasse 283A",
  "city": "Koln",
  "postal_code": "50931",
  "country": "DEU",
  "coordinates": {
    "latitude": "50.931826",
    "longitude": "6.964043"
  },
  "parking_type": "ON_DRIVEWAY",
  "evses": [{
    "uid": "4534ad5f-45be-428b-bfd0-fa489dda932d",
    "evse_id": "DE*ALL*EG00000001",
    "status": "AVAILABLE",
    "connectors": [{
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "power_type": "AC_1_PHASE",
      "max_voltage": 230,
      "max_amperage": 8,
      "last_updated": "2019-04-05T17:17:56Z"
    }],
    "last_updated": "2019-04-05T17:17:56Z"
  }],
  "time_zone": "Europe/Berlin",
  "last_updated": "2019-04-05T17:17:56Z"
}

Parking garage with opening hours

A public parking garage with publish set to true, parking_type set to PARKING_GARAGE, opening_times with weekday 1-7 from 07:00 to 18:00, and charging_when_closed set to true.

Parking garage with opening hours

{
  "country_code": "SE",
  "party_id": "EVC",
  "id": "cbb0df21-d17d-40ba-a4aa-dc588c8f98cb",
  "publish": true,
  "name": "P-Huset Leonard",
  "address": "Claesgatan 6",
  "city": "Malmo",
  "postal_code": "214 26",
  "country": "SWE",
  "coordinates": {
    "latitude": "55.590325",
    "longitude": "13.008307"
  },
  "parking_type": "PARKING_GARAGE",
  "evses": [{
    "uid": "eccb8dd9-4189-433e-b100-cc0945dd17dc",
    "evse_id": "SE*EVC*E000000123",
    "status": "AVAILABLE",
    "connectors": [{
      "id": "1",
      "standard": "IEC_62196_T2",
      "format": "SOCKET",
      "power_type": "AC_3_PHASE",
      "max_voltage": 230,
      "max_amperage": 32,
      "last_updated": "2017-03-07T02:21:22Z"
    }],
    "last_updated": "2017-03-07T02:21:22Z"
  }],
  "time_zone": "Europe/Stockholm",
  "opening_times": {
    "twentyfourseven": false,
    "regular_hours": [{
      "weekday": 1,
      "period_begin": "07:00",
      "period_end": "18:00"
    }, {
      "weekday": 2,
      "period_begin": "07:00",
      "period_end": "18:00"
    }, {
      "weekday": 3,
      "period_begin": "07:00",
      "period_end": "18:00"
    }, {
      "weekday": 4,
      "period_begin": "07:00",
      "period_end": "18:00"
    }, {
      "weekday": 5,
      "period_begin": "07:00",
      "period_end": "18:00"
    }, {
      "weekday": 6,
      "period_begin": "07:00",
      "period_end": "18:00"
    }, {
      "weekday": 7,
      "period_begin": "07:00",
      "period_end": "18:00"
    }]
  },
  "charging_when_closed": true,
  "last_updated": "2017-03-07T02:21:22Z"
}

4.2 EVSE Object

class

The EVSE object describes the part that controls the power supply to a single EV in a single session. It always belongs to a Location object. The object contains directions and facilities information from the Location to the EVSE (such as floor level and physical reference).

An EVSE object has a list of Connectors which can not be used simultaneously: only one connector per EVSE can be used at the time.

Property	Type	Cardinality	Description
`uid`	`CiString(36)`	`1`	Uniquely identifies the EVSE within the CPO's platform (and suboperator platforms). This field can not be changed, modified or renamed. This is a technical identification, not to be used as human-readable identification, and not an authorization identification. It is named `uid` instead of `id` to prevent confusion with `evse_id`.
`evse_id`	`CiString(48)`	`?`	Compliant with the eMI3 standard for EVSE IDs. Optional because: if an EVSE ID is to be re-used in the future, the EVSE ID can be removed after the EVSE is set to status `REMOVED`.
`status`	`Status`	`1`	Indicates the current status of the EVSE.
`status_schedule`	`StatusSchedule`	`*`	Indicates a planned status update of the EVSE.
`capabilities`	`Capability`	`*`	List of functionalities that the EVSE is capable of.
`connectors`	`Connector`	`+`	List of available Connectors on the EVSE.
`floor_level`	`string(4)`	`?`	Level on which the Charge Point is located (in garage buildings), in the locally displayed numbering scheme.
`coordinates`	`GeoLocation`	`?`	Coordinates of the EVSE.
`physical_reference`	`string(16)`	`?`	A number/string printed on the outside of the EVSE for visual identification.
`directions`	`DisplayText`	`*`	Multi-language human-readable directions when more detailed information on how to reach the EVSE from the Location is needed.
`parking_restrictions`	`ParkingRestriction`	`*`	The restrictions that apply to the parking spot.
`images`	`Image`	`*`	Links to images related to the EVSE such as photos or logos.
`last_updated`	`DateTime`	`1`	Timestamp when this EVSE or one of its Connectors were last updated (or created).

Note: OCPP 1.x does not have good support for Charge Points that have multiple connectors per EVSE. To make StartSession over OCPI work, the CPO SHOULD present the different connectors of an EVSE as separate EVSE objects, each with a single Connector.

4.3 Connector Object

class

A Connector is the socket or cable available for the EV to use. A single EVSE may provide multiple Connectors, but only one of them can be in use at the same time. A Connector always belongs to an EVSE object.

Property	Type	Cardinality	Description
`id`	`CiString(36)`	`1`	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`	`ConnectorType`	`1`	The standard of the installed Connector.
`format`	`ConnectorFormat`	`1`	The format (socket/cable) of the installed Connector.
`power_type`	`PowerType`	`1`	The type of power at the Connector.
`max_voltage`	`int`	`1`	Maximum voltage of the Connector (line to neutral for AC_3_PHASE), in volt (V).
`max_amperage`	`int`	`1`	Maximum amperage of the Connector, in ampere (A).
`max_electric_power`	`int`	`?`	Maximum electric power that can be delivered by this Connector, in watt (W). When the maximum electric power is lower than the calculated value from `voltage` * `amperage`, this value should be set. For example: a DC Connector with 920V/400A that is limited to 150kW.
`tariff_ids`	`CiString(36)`	`*`	Identifiers of the valid charging tariffs. Multiple tariffs are possible, but only one of each `Tariff.type` can be active at the same time. When the Connector allows free charging, a reference to a defined free tariff should be given.
`terms_and_conditions`	`URL`	`?`	URL to the operator's terms and conditions.
`last_updated`	`DateTime`	`1`	Timestamp when this Connector was last updated (or created).

5. Data Types

Reference

This section describes all data types used in the Locations module. Each type is either a class (structured object) or an enum (fixed set of values).

5.1 AdditionalGeoLocation

class

Additional geo location relevant for the Charge Point. Geodetic system: WGS 84.

Property	Type	Cardinality	Description
`latitude`	`string(10)`	`1`	Latitude of the point in decimal degree. Example: 50.770774. Geodetic system: WGS 84.
`longitude`	`string(11)`	`1`	Longitude of the point in decimal degree. Example: -126.104965. Geodetic system: WGS 84.
`name`	`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.

5.2 BusinessDetails

class

Property	Type	Cardinality	Description
`name`	`string(100)`	`1`	Name of the operator.
`website`	`URL`	`?`	Link to the operator's website.
`logo`	`Image`	`?`	Image link to the operator's logo.

5.3 Capability

enum

The capabilities of an EVSE.

Value	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 of this EVSE can be unlocked remotely.

Note: The combination of the values CHIP_CARD_SUPPORT, CONTACTLESS_CARD_SUPPORT, CREDIT_CARD_PAYABLE, DEBIT_CARD_PAYABLE, and PED_TERMINAL can be used to indicate that ad-hoc payments are possible at an EVSE.

Note: The value START_SESSION_CONNECTOR_REQUIRED is typically used for OCPP 1.x Charge Points that have multiple connectors per EVSE. Such a Charge Point requires the MSP to first specify which connector to use before starting a session.

5.4 ConnectorFormat

enum

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

Value	Description
`SOCKET`	The connector is a socket; the EV driver needs to bring a fitting plug.
`CABLE`	The connector is an attached cable; the EV driver does not need to bring a cable.

5.5 ConnectorType

enum

The socket or plug standard of the charging point.

Value	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 pins.
`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 phase 16 amperes (usually red).
`IEC_60309_2_three_32`	IEC 60309-2 Industrial connector three phase 32 amperes (usually red).
`IEC_60309_2_three_64`	IEC 60309-2 Industrial connector three phase 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".
`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.
`NEMA_14_50`	NEMA 14-50, 3 pins.
`PANTOGRAPH_BOTTOM_UP`	On-board bottom-up pantograph typically for bus charging.
`PANTOGRAPH_TOP_DOWN`	Off-board top-down pantograph typically for bus charging.
`TESLA_R`	Tesla connector "Roadster"-type (round, 4 pins).
`TESLA_S`	Tesla connector "Model-S"-type (oval, 5 pins).

5.6 EnergyMix

class

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

Property	Type	Cardinality	Description
`is_green_energy`	`boolean`	`1`	True if 100% from regenerative sources. (CO2 and nuclear waste is zero)
`energy_sources`	`EnergySource`	`*`	Key-value pairs (enum + percentage) of energy sources of this location's tariff.
`environ_impact`	`EnvironmentalImpact`	`*`	Key-value pairs (enum + amount) of nuclear waste and CO2 exhaust of this location's tariff.
`supplier_name`	`string(64)`	`?`	Name of the energy supplier, delivering the energy for this location or tariff.
`energy_product_name`	`string(64)`	`?`	Name of the energy supplier's product/tariff plan used at this location.

Note: The fields supplier_name and energy_product_name are only relevant for MSPs that want to display the energy supplier and/or product name to the EV driver.

Examples

Simple green energy

{
  "is_green_energy": true
}

Tariff provider energy mix

{
  "is_green_energy": true,
  "supplier_name": "Greenpeace Energy eG",
  "energy_product_name": "eco-power"
}

Complete energy mix with sources and environmental impact

{
  "is_green_energy": false,
  "energy_sources": [
    {
      "source": "GENERAL_GREEN",
      "percentage": 35.5
    },
    {
      "source": "GAS",
      "percentage": 22.6
    },
    {
      "source": "COAL",
      "percentage": 28.8
    },
    {
      "source": "GENERAL_FOSSIL",
      "percentage": 1.3
    },
    {
      "source": "NUCLEAR",
      "percentage": 11.8
    }
  ],
  "environ_impact": [
    {
      "category": "NUCLEAR_WASTE",
      "amount": 0.0006
    },
    {
      "category": "CARBON_DIOXIDE",
      "amount": 372
    }
  ]
}

5.7 EnergySource

class

Property	Type	Cardinality	Description
`source`	`EnergySourceCategory`	`1`	The type of energy source.
`percentage`	`number`	`1`	Percentage of this source (0-100) in the energy mix.

5.8 EnergySourceCategory

enum

Categories of energy sources.

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

5.9 EnvironmentalImpact

class

Property	Type	Cardinality	Description
`category`	`EnvironmentalImpactCategory`	`1`	The category of this environmental impact value.
`amount`	`number`	`1`	Amount of this portion in g/kWh.

5.10 EnvironmentalImpactCategory

enum

Categories of environmental impact values.

Value	Description
`NUCLEAR_WASTE`	Produced nuclear waste in g/kWh.
`CARBON_DIOXIDE`	Produced CO2 in g/kWh.

5.11 ExceptionalPeriod

class

Specifies one exceptional period for opening or access hours.

Property	Type	Cardinality	Description
`period_begin`	`DateTime`	`1`	Begin of the exceptional period, in UTC, no milliseconds allowed.
`period_end`	`DateTime`	`1`	End of the exceptional period, in UTC, no milliseconds allowed.

5.12 Facility

enum

Facilities available at a charging location.

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

5.13 GeoLocation

class

This class defines the geo location of the Charge Point. The geodetic system to be used is WGS 84.

Property	Type	Cardinality	Description
`latitude`	`string(10)`	`1`	Latitude of the point in decimal degree. Example: 50.770774. Geodetic system: WGS 84.
`longitude`	`string(11)`	`1`	Longitude of the point in decimal degree. Example: -126.104965. Geodetic system: WGS 84.

Note: The precision of the geo coordinate is important. 5 decimal places gives a precision of approximately 1 meter, which is sufficient for most use cases. 7 decimal places gives a precision of approximately 1 centimeter.

5.14 Hours

class

Opening and access hours of the location.

Property	Type	Cardinality	Description
`twentyfourseven`	`boolean`	`1`	True to represent 24/7, false if the hours are defined by regular_hours and/or exceptional periods.
`regular_hours`	`RegularHours`	`*`	Regular hours, weekday-based. Only to be used if twentyfourseven is false. May not be set. Should be set if twentyfourseven is false.
`exceptional_openings`	`ExceptionalPeriod`	`*`	Exceptions for specified calendar dates, the location is open during the exceptional period.
`exceptional_closings`	`ExceptionalPeriod`	`*`	Exceptions for specified calendar dates, the location is closed during the exceptional period.

Examples

24/7 with exceptional closing

{
  "twentyfourseven": true,
  "exceptional_closings": [
    {
      "period_begin": "2014-06-21T09:00:00Z",
      "period_end": "2014-06-21T12:00:00Z"
    }
  ]
}

Regular hours with exceptional closing

{
  "twentyfourseven": false,
  "regular_hours": [
    {
      "weekday": 1,
      "period_begin": "01:00",
      "period_end": "06:00"
    },
    {
      "weekday": 2,
      "period_begin": "01:00",
      "period_end": "06:00"
    }
  ],
  "exceptional_closings": [
    {
      "period_begin": "2014-06-24T00:00:00Z",
      "period_end": "2014-06-25T00:00:00Z"
    }
  ]
}

Regular hours with exceptional opening

{
  "twentyfourseven": false,
  "regular_hours": [
    {
      "weekday": 1,
      "period_begin": "00:00",
      "period_end": "04:00"
    },
    {
      "weekday": 2,
      "period_begin": "00:00",
      "period_end": "04:00"
    }
  ],
  "exceptional_openings": [
    {
      "period_begin": "2014-06-21T09:00:00Z",
      "period_end": "2014-06-21T12:00:00Z"
    }
  ]
}

5.15 Image

class

This class references an image related to an EVSE in terms of a file name or URL. The recommended photo dimensions are a minimum width of 800 pixels and a minimum height of 600 pixels. Logo dimensions should be a minimum width of 200 pixels and a minimum height of 200 pixels.

Property	Type	Cardinality	Description
`url`	`URL`	`1`	URL from where the image data can be fetched through a web browser.
`thumbnail`	`URL`	`?`	URL from where a thumbnail of the image can be fetched through a web browser.
`category`	`ImageCategory`	`1`	Describes what the image is used for.
`type`	`CiString(4)`	`1`	Image type like: gif, jpeg, png, svg.
`width`	`int(5)`	`?`	Width of the full-scale image.
`height`	`int(5)`	`?`	Height of the full-scale image.

5.16 ImageCategory

enum

The category of an image to obtain the correct usage in a user presentation.

Value	Description
`CHARGER`	Photo of the physical device that contains one or more EVSEs.
`ENTRANCE`	Photo of the entrance to the location, e.g. the gate or door of a parking garage.
`LOCATION`	Photo of the location overview, e.g. a photo taken from a nearby hill.
`NETWORK`	Logo of an associated roaming network to be displayed with the EVSE, for example in lists.
`OPERATOR`	Logo of the Charge Point Operator, for example a municipal, to be displayed with the EVSE.
`OTHER`	Other type of image not covered by the previous categories.
`OWNER`	Logo of the battery owner, for example a car manufacturer, to be displayed with the EVSE.

5.17 ParkingRestriction

enum

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

Value	Description
`EV_ONLY`	Reserved parking spot for electric vehicles.
`PLUGGED`	Parking is only allowed while plugged in (charging).
`DISABLED`	Reserved parking spot for disabled people with valid ID.
`CUSTOMERS`	Parking spot for customers/visitors only, for example in case of a hotel or shop.
`MOTORCYCLES`	Parking spot only suitable for (electric) motorcycles or scooters.

5.18 ParkingType

enum

Reflects the general type of the charge point's location.

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

5.19 PowerType

enum

The type of power supply at the connector.

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

5.20 PublishTokenType

class

Defines the set of values that identify a token to which a Location might be published. At least one of uid, visual_number, or group_id SHALL be set. When uid is set, type SHALL also be set. When visual_number is set, issuer SHALL also be set.

Property	Type	Cardinality	Description
`uid`	`CiString(36)`	`?`	Unique ID by which this Token can be identified.
`type`	`TokenType`	`?`	Type of the token.
`visual_number`	`string(64)`	`?`	Visual readable number/identification as printed on the Token (RFID card).
`issuer`	`string(64)`	`?`	Issuing company, most of the times the name of the company printed on the token (RFID card), not necessarily the eMSP.
`group_id`	`CiString(36)`	`?`	This ID groups Tokens. This can be used to make two or more tokens work as one.

5.21 RegularHours

class

Regular recurring operation or access hours.

Property	Type	Cardinality	Description
`weekday`	`int(1)`	`1`	Number of day in the week, from Monday (1) till Sunday (7).
`period_begin`	`string(5)`	`1`	Begin of the regular period, in local time, given in hours and minutes. Must be in 24h format with leading zeros. Example: "18:15". Hour/Minute separator: ":" Regex: [0-2][0-9]:[0-5][0-9].
`period_end`	`string(5)`	`1`	End of the regular period, in local time, syntax as for period_begin. Must be later than period_begin.

Example

Weekday hours with exceptional periods

{
  "twentyfourseven": false,
  "regular_hours": [
    {
      "weekday": 1,
      "period_begin": "08:00",
      "period_end": "20:00"
    },
    {
      "weekday": 2,
      "period_begin": "08:00",
      "period_end": "20:00"
    },
    {
      "weekday": 3,
      "period_begin": "08:00",
      "period_end": "20:00"
    },
    {
      "weekday": 4,
      "period_begin": "08:00",
      "period_end": "20:00"
    },
    {
      "weekday": 5,
      "period_begin": "08:00",
      "period_end": "20:00"
    }
  ],
  "exceptional_openings": [
    {
      "period_begin": "2014-06-21T09:00:00Z",
      "period_end": "2014-06-21T12:00:00Z"
    }
  ],
  "exceptional_closings": [
    {
      "period_begin": "2014-06-24T00:00:00Z",
      "period_end": "2014-06-25T00:00:00Z"
    }
  ]
}

Schedule Visualization

The following table shows how the above example is resolved for the period Monday June 16 to Sunday June 29.

Day	Date	Open	Close
Monday	June 16	08:00	20:00
Tuesday	June 17	08:00	20:00
Wednesday	June 18	08:00	20:00
Thursday	June 19	08:00	20:00
Friday	June 20	08:00	20:00
Saturday	June 21	09:00	12:00 (exceptional opening)
Sunday	June 22	Closed
Monday	June 23	08:00	20:00
Tuesday	June 24	Closed	(exceptional closing)
Wednesday	June 25	08:00	20:00
Thursday	June 26	08:00	20:00
Friday	June 27	08:00	20:00
Saturday	June 28	Closed
Sunday	June 29	Closed

5.22 Status

enum

The status of an EVSE.

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

5.23 StatusSchedule

class

Used to schedule status periods in the future for trip planning.

Property	Type	Cardinality	Description
`period_begin`	`DateTime`	`1`	Begin of the scheduled period.
`period_end`	`DateTime`	`?`	End of the scheduled period, if known.
`status`	`Status`	`1`	Status value during the scheduled period.

Note: The scheduled status is purely informational. When the status actually changes, the CPO must push an update to the EVSE's status field itself.