Intro to Charge-Location Management API
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.
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
|Get Charge Stations and Locations in batch||Get a list of charge stations and locations that have recently been updated. Used for populating an external data warehouse.|
|Get Charge Stations and Locations in real time||Get multiple/single charge stations and locations in real time for use in an external Portal.|
|Create/Update/Patch single charge stations and locations||Changes should be available in real time.|
|Batch Create/Update/Patch single charge stations and locations||Changes should be available in real time.|
|Manage Charge Station hardware templates.||Can get all hardware templates for a CPO and create/update templates. These templates can be used to manage charge stations.|
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.
- 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
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:
- Custom group
- Notes and remarks
- Energy Profile Mix
New is also the ability to create, update and patch a Location object.
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)
- 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)
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.
|2xxx||Client errors – The data sent by the client can not be processed by the server|
|3xxx||Server errors – The server encountered an internal error|
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:
Updated 2 months ago