Eco-Movement Data API User Guide

Introduction

Eco-Movement Data API is an outbound API based on the market standard OCPI protocol, which makes it easy for partners and clients to connect with Eco-Movement.

๐Ÿ“˜

Note

This user guide explains only the main features of OCPI protocol. For more in-depth documentation, refer to the original OCPI 2.1.1 documentation.

Eco-Movement offers a large and growing number of attributes that are not available in the OCPI protocol. These attributes are explained in this documentation.

Realtime Updates

Realtime Updates using PATCH Method

The fastest and preferred method to receive real-time data from Eco-Movement is to use the PATCH method. Eco-Movement sends the updates to your server without delay using the PATCH method. For this method to work, you are required to build an endpoint that can receive PATCH updates. A so-called handshake can be performed with the credentials endpoint (/credentials), so that Eco-Movement knows where to send the PATCH updates.

The syntax for the PATCH method is:

PATCH '<https://api.customername.com/api/ocpi/emsp/2.1.1/locations/NL/ECO/{location_id}/{evse_uid}'>

The following is an example request using the PATCH method:

PATCH '<https://api.customername.com/api/ocpi/emsp/2.1.1/locations/NL/ECO/47155362-4d93-11e8-a522-42010a840002/9785'>

The following is an example response:

{
"status":"AVAILABLE",
"last_updated": "2023-07-24T08:25:28Z"
}

๐Ÿ“˜

Note

The last_updated field is not always available with OCPI 2.1.1.

Realtime Updates using GET Method

Eco-Movement emphasizes that the PATCH method (PUSH) is the default and GET requests (PULL) are for minor volumes only. To get real-time information using GET requests, you can use the parameters date_from and date_to. These parameters use the combined date and time format from the ISO 8601 standard. All timestamps are in UTC.

The result returned by Eco-Movement consists only the changes that have occurred during the timeline set using the date_from and date_to parameters. However, it is not completely real-time, because there is an interval of a few minutes between the GET requests. If you desire to have more precise real-time information, it is better to use the PUSH service (PATCH method) of Eco-Movement.

ParameterDescription
date_fromUse this parameter to set the starting date and time. For example, request only the updates for the last 5 minutes.
date_toUse this parameter to set the ending date and time. For example, request only the updates for the last 5 minutes.

The following is an example request using the GET method:

<https://api.eco-movement.com/api/ocpi/cpo/2.1.1/locations/?date_from=2020-12-29T17:15:09&date_to=2020-12-29T17:20:09>

๐Ÿ“˜

Note

When you receive information using GET requests, which often require many paginated requests, if one or more requests fail, retry the failed requests so you don't miss that data.

๐Ÿšง

Caution

Eco-Movement strongly recommends limiting simultaneous GET requests to a maximum of 5.

Available Endpoints

The following table lists the endpoints that are available for communicating using the JSON format:

EndpointDescription
locationsThe locations endpoint retrieves a list of all locations or a specific location (using the location's id).
evseThe evse endpoint returns a location using the EVSE_id parameter.
prices and prices (New)Both prices endpoints return a list of MSP prices and CPO ad hoc prices. The prices are considered at the connector level.
tariffsThe tariffs endpoint displays the raw tariffs shared with Eco-Movement by the CPOs using the OCPI protocol.
credentialsThe credentials endpoint performs a so-called handshake between Eco-Movement and your organization.

Preferred Method of Implementation

There are several ways to obtain the data via the OCPI protocol. The preferred method is described below as a recipe. This ensures the fastest real-time data and the least server load for all parties.