Locations API v2

Suggest Edits

Locations v2

The Locations v2 API allows to:

  • GET all Locations
  • GET a Single Location
  • POST create a Location
  • PUT upsert a Location
  • PATCH to update single fields of a Location

Retrieving Locations (GET)

To retrieve all Locations, use the /locations endpoint with the 'date_from' field to narrow the search to objects updated since a specific date.
Note: Changes to the EVSE status will count towards a last modified event for the Locations, only Location object modificatons.

The/locations/{locationid} endpoint should be used to retrieve information in real time about a Location. This endpoint should be called when loading a single object.

It is NOT allowed to call the /locations/{locationid} endpoint for all LocationIDs to get real time information.

To retrieve all Charge Stations of a Location, use the Get Chargestations endpoint and query by LocationId.

Search for address

The Locations endpoint has functionality to filter the search by address (country, city, street, postcode) as well as within a radius of up to 1000m.
The intended use case is for a field installer to load all locations nearby.
It is NOT allowed to use this endpoint for end-Customer facing functionality to help them find a charging station.

Creating a Location

In order to create a Location, the following fields are required:

  • Location name
  • address (Street & housenumber)
  • city
  • postal code
  • country (3 letter iso code)
  • CPO Id

The CPO_id can be found in the EV Portal as the External ID. It is case sensitive.
The latitude and longitude will be automatically generated based on the address.

Updating a Location

There are two operations to update a Location:

  • PUT which will upsert the fields. Optional fields that are not supplied will be cleared for the Location
  • PACH will only update those fields provided.

Patch

Patching an object, e.g. Custom Groups or Facilities will replace the object.
E.g. to add 'HOTEL' to an already existing facility 'MALL' will require to upsert the object

"facilities": [
    "HOTEL",
    "MALL"
]

Etags for updating a Location

To ensure that a Location object is not updated at the same time and creating concurrency problems, we have introduced etag

"etag": "ca3a9cab-f785-4624-b0fa-90085e509f70",

When updating (PUT) a Location, then the etag MUST be provided. This can be retrieved from any of the GET calls

For PATCH updates, an etag is not required

Added fields

  • Custom Groups
  • Authorization
  • Notes
  • Remarks
  • Location Payment Wallet
  • Energy Mix Profile ID
  • Updated and modified by fields
  • CPO id

Custom Groups

Custom Groups can be added by a PUT or PATCH operation, using the Custom Group 'name'
"custom_groups": [
{
"name": "gfx-xyz-norway"
}
],

🚧

Custom group ID

It is currently not possible to retrieve the custom group id via API or find it in the EvPortal. This will be an improvement point.
In general it is 'gfx-' in front and then the name of the Custom Group, with spaced replaced by '-'.
'Alfen chargers' --> 'gfx-alfen-chargers'

Auth_rules

This corresponds with the 'Authorization' tab in the EvPortal.

There are two types of Authorizations:

  • Customers --> "type": "CustomerExternalId",
  • individual tokens--> "type": "ClosedGroups",

"auth_rules": [
{
"type": "CustomerExternalId",
"value": "customer1"
},
{
"type": "ClosedGroups",
"value": "token1"
}
],

Energy Mix Profile ID

GreenFlux created Energy Mix Profiles to easier add an energy mix to a Location. The ID is now part of the payload for easier referencing.

"energy_mix_profile_id": "86ae001d-c6df-43f6-9364-ef5e426dba0c",

Location Payment wallet

Functionality used by a single provider and otherwise not relevant

Maintenance Info & Remarks

Available in the EvPortal and added to the API.

Created and Modified fields

The following fields were added. They are auto-generated by the backend.

created_by
modified_by
created
modified

field returns

type:

  • ON_STREET
  • PARKING_GARAGE
  • UNDERGROUND_GARAGE
  • PARKING_LOT
  • OTHER
  • UNKNOWN

country:

valid 3 letter country code:
https://www.iban.com/country-codes

access_type:

  • PUBLIC
  • RESTRICTED
  • PRIVATE

facilities:

  • HOTEL
  • RESTAURANT
  • CAFE
  • MALL
  • SUPERMARKET
  • SPORT
  • RECREATION_AREA
  • NATURE
  • MUSEUM
  • BUS_STOP
  • TAXI_STAND
  • TRAIN_STATION
  • AIRPORT
  • CARPOOL_PARKING
  • FUEL_STATION
  • WIFI

Updated 8 months ago