Charging Points API (DOT-NL)

Warning

These APIs are still under development and specifications may change.

DOT-NL (Data Platform for Publicly Accessible Charging Points in the Netherlands) is the portal that receives real-time data about alternative energy infrastructure for vehicles from suppliers and makes it available.

Connection

To connect to DOT-NL, you can contact the NDW Servicedesk. Please indicate that you are connecting to DOT-NL, NAP-EV, or Dafne. Subsequently, arrangements will be made on how to set up the connection, and connection tests will be conducted.

Timeliness

The provided data must be current. This means that changes must be delivered within 1 minute.

Delivery with OCPI-2.2.1

OCPI (Open Charge Point Interface) is a protocol that enables communication between charging point operators and service providers and is maintained by the EVRoaming Foundation.

For delivery to DOT-NL, via OCPI-2.2.1, openapi specifications have been established for the pull and push functionality (4.1.3 in OCPI-2.2.1), which indicate what information is expected through which endpoints.

In addition to OCPI-2.2.1, due to the AFIR, the following optional elements have been made mandatory in the openapi specifications:

Object	Element
Location	opening_times
Location	energy_mix
EVSE	parking_restrictions
Connector	max_electric_power
Connector	tariff_ids

Pull

To know the complete set of objects and the latest status of individual objects, these are periodically (daily) retrieved using the pull functionality. A server must be available that provides the current state as a response to a GET according to the pull-API openapi spec.

Pull - Locations

To provide the Locations, an endpoint must be available that listens for requests for both the complete set and specific locations. The retrieval of individual EVSE and Connector objects is not currently used.

Pull - Tariffs

To provide the Tariffs, an endpoint must be available that listens for requests for the complete set of tariffs.

Pull - Authentication

Warning

The credentials module of OCPI is not used.

To retrieve the current status from the supplier, the authentication credentials must be made available. It is possible to grant access in two ways, namely through a token/API-key or through OAuth2.

When using an agreed-upon token/API-key, the access token/API-key will be included in the Authorization: Token header in requests.

When using OAuth2, a client-id and client-secret combination must be made available along with the endpoint where this combination can be used. Subsequently, in accordance with OAuth2 conventions, the JWT will be passed via an Authorization: Bearer header in the requests.

Push

To report changes to objects within a minute after they occur, there is the push functionality. For this, the client must provide changes according to the push-API openapi spec. With PUT, complete objects are updated, while with PATCH, only provided elements are updated. Only for tariffs is it possible to delete objects with a DELETE.

Method	Description	Location	EVSE	Connector	Tariff
PUT	Update objects	x	x	x	x
PATCH	Update elements of existing objects	x	x	x
DELETE	Delete objects				x

It is not allowed to change identifiers of objects. For example, a PUT on a location with a parameter location_id with value x, while the id element of the object is y.

Push - Locations

To update a single location, it is possible to perform a PUT or PATCH on the Locations, EVSE, and Connector objects. Only the last_updated is a mandatory element. If a sub-object is mentioned in an update, this sub-object must be fully present (according to the requirements of a PUT for that type of object).

Push - Tariffs

To update a single tariff, it is possible to perform a PUT on a Tariff object. To delete a tariff, it is possible to perform a DELETE, which returns an HTTP-204 status code upon success (this differs from the OCPI specification).

Push - Authentication

Warning

The credentials module of OCPI is not used.

Authentication for delivering updates (push) is done via OAuth. When calling the API, an 'OAuth token' must be sent along. Such an OAuth token can be obtained through the NDW Identity & Access Management server.

You can request an NDW service account for the DOT-NL API at the NDW service desk. When contacting them, clearly state that it is for a "service account for supplying DOT-NL".

If you have a service account, an OAuth token can be obtained in the following way (via curl):

curl \
  -d "client_id=<uw client_id>" \
  -d "client_secret=<uw client secret>" \
  -d "grant_type=client_credentials" \
  https://iam.ndw.nu/auth/realms/ndw/protocol/openid-connect/token

This results in the following response:

{
  "access_token": "",
  "expires_in": 1800,
  "refresh_expires_in": 3600,
  "refresh_token": "",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "81ae1763-9c99-4c54-99b8-5e0629f8a2d6",
  "scope": "profile email"
}

The response contains an access_token. The content of this access_token must be included when calling the API. This can be done using the following HTTP header: Authorization: Bearer <betreffende access token>

Here is the translation to English:

Push - Error Handling

In response to pushing data, there are 2 possible response codes, namely related to communication (HTTP) and related to content (OCPI). The table below provides insight into the expected codes.

	HTTP Code	OCPI Status Code
Incorrect resource	404	-
No access	401	-
Invalid JSON message	400	-
JSON not conforming to specification	200	2xxx
JSON conforming to specification	200 / 201	1xxx

Consume using OCPI-2.2.1

It is possible to connect to the API to retrieve real-time data about the charging points.

API specifications

Supplier pull-API

Pull-API according to openapi-spec

Supplier push-API

Push-API according to openapi-spec

Consumer pull-API

Pull-API according to openapi-spec

Servicedesk

For more information, you can contact the NDW Servicedesk.

Go back to the previous page