👍

Controlled Availability

The Charge-Location Management API is now available to all Customers. We have received positive feedback from initial testing and are confident in its stability. As such, GreenFlux will no longer be making breaking changes with shorter notice periods. We encourage Customers to use the API and build business critical processes on top of it.

Intro

GreenFlux is releasing a new set of APIs called 'Location & Charge Station Management APIs'.

These APIs have the following new properties:

• ability to write, e.g. create Location & Charge Station (as opposed to only read)
• additional fields (e.g. CS configuration fields) to populate your data warehouses

Until a definitive API documentation is released, this section outlines the current state of the API

Use Cases

Who should use these APIs?

• Every CPO currently using the Locations API (v1.0) should migrate to the Locations v 2.0 endpoint as it has additional fields and additional functionality
• CPOs who want to integrate their own CRM/Asset management system more closely. We are aware of some CPOs who have built front-ends for their end Customers. The new APIs would also allow them to e.g. change tariff codes, change opening hours or availability of a Charge Station
• Build third-party installer Apps. An installer could use a custom built app to link a just-placed Charge Station with a Location and perform basic tests, instead of having to contact central support
• Populate data-warehouses for further analytics. Our APIs will perform better for larger data polling and are complete

Design Principles - OCPI based

The current 'Platform APIs' are strongly based on OCPI, since originally they were just forked from the roaming side and made available to CPOs to retrieve their own data.

We believe that amongst our CPO Customers there is generally a good understanding of OCPI APIs and therefore these APIs are designed to stay as close as possible to the OCPI documentation.

Examples:

• use of the data property for a data object or list of objects
• The response format uses the data object, status code, status message and timestamp
• reuse naming convention from OCPI as much as possible
• same syntax (e.g. camel_case)
• Same request format: use of offset, date_from, date_to and limit
• authorization method

Key Changes

Locations

We have largely made the Locations object backwards compatible with OCPI 2.1.1.

As we already did in the previous iteration, we have added additional, custom GreenFlux fields to the object, such as:

• auth_list
• Custom group
• Notes and remarks
• Energy Profile Mix

New is also the ability to create, update and patch a Location object.

Charge Station

The Charge Station object does not exist in OCPI, so we have used the current structure that is in the Portal as a basis.

In principle, any field that is visible and editable in the EvPortal for a Charge Station can be updated via the API (except for Configuration, which will be addressed in future APIs)

Key elements

• the EVSEs reside in the Charge Station object. Changes to an EVSE will update the parent Location object
• Charge stations can be created and updated in a similar way as in the Portal
• Key configuration items will be made available as read-only
  (Configuration changes are not yet able via API)

Error Codes

For these APIs, we follow OCPI guidelines. They state that:
If a request is syntactically valid JSON and addresses an existing resource, a HTTP error MUST NOT be returned. Those requests are supposed to have reached the OCPI layer.

OCPI error code ranges.

This means that e.g. a POST request to create a Location that is missing a required field will return a HTTP 200 code, but will have a OCPI 2000 status.

Another example of a PUT upsert where the etag is out of date: