API Reference

Getting Started

Introduction

Eco-Movement Data API is an outbound API based on the market standard OCPI protocol, which makes it easy to connect with Eco-Movement. This API is organized around the RESTful architecture for web services and returns JSON-encoded response.

Authorization

Each HTTP request must add an ‘Authorization’ header. The following is a sample header:

Authorization: Token IpbJOXxkxOAuKR92z0nEcmVF3Qw09VG7I7d/WCg0koM=

The ‘Token’ literal indicates that the token based authentication mechanism was used. The parameter is a string of printable non-whitespace ASCII characters. The token uniquely identifies a user.

Supported Methods

The supported methods in the request are:

MethodDescription
GETFetch objects or information.
POSTCreate new objects or information.
PUTUpdate existing objects or information.
PATCHPartially update existing objects or information.

Pagination

The Eco-Movement Data API endpoints can return more than 100,000 locations. Hence, pagination is supported.

limit & offset (All Endpoints)

Use the following two parameters to control the size of the response.

ParameterDescription
limitLimits the number of objects that are returned. The minimum value is 1 and the maximum value is 1000 or 10000 (only for new pricing endpoints). This parameter is optional and the default value is 1000 or 10000 (only for new pricing endpoints).
offsetIndicates the number of items to skip. This parameter is optional and the default value is 0 (that is, the first page of the results is only returned).

For example, the maximum amount of locations that can be returned in the result is 1000. In the result's header, a link to the following 1000 locations is given. The following is an example of a link in the result's header:

<https://api.eco-movement.com/ocpi/cpo/2.1.1/locations/?offset=1000&limit=2000>; rel=”next”

last_record (Only for New Pricing Endpoints)

Use the following parameter to retrieve the next set of records.

ParameterDescription
last_recordIndicates a value that can be used to retrieve the next set of records.

The following steps explain how to best use this parameter:

  1. For the first request use /prices or /prices/connector_prices without the parameter, and the first 10000 records are returned with the X-Last-Record header.
  2. Use the value in the X-Last-Record header with the last_record parameter to retrieve the next set of records.
  3. Continue using the last_record parameter. When X-Last-Record is empty, then that is the last set of records.

The following is an example:

https://api.eco-movement.com/prices?last_record=MTA1Mjk0Czk5

📘

Note

  • You can use last_record with limit parameter. But if offset is sent, then it is ignored and the value in last_record is considered for pagination.
  • When last_record parameter is used, pagination does not miss any results even if rows are deleted from the previous set of records.

Status Codes

Eco-Movement Data API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 1xxx range indicate success. Codes in the 2xxx range indicate client errors (for example, a required parameter was omitted or a resource was missing). Codes in the 3xxx range indicate a server error or an entry that cannot be processed.

Every error includes a human-readable message. For example:

{
  "status_code": 2001,
  "status_message": "evse_id EVSE_ID is not valid",
  "timestamp": "2022-07-12T09:34:35"
}