Locations

A location is a physical place, such as a parking lot or a shopping mall, where one or more charging stations are installed. Grouping stations into a location lets you configure them all at once.

Reading

Locations can be read via the locations GET endpoint. It returns all locations visible to you in be.ENERGISED.

The list endpoint is using cursor pagination.

curl --location --request GET 'https://<slug>.beenergised.cloud/api/cpoapi/v1/locations/' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json'

CRUD operations

Locations are created with POST /locations and updated with PUT /locations — note that the location uuid goes into the body (id) on update, not into the path. DELETE /locations/{uuid} removes a location; the stations that were assigned to it are not deleted.

Stations are assigned with PUT /locations/{uuid}/stations and unassigned with DELETE /locations/{uuid}/stations. Both take a cpIds array. Assigning is additive — stations already on this location are ignored — but a station that currently belongs to a different location is refused with 409; unassign it there first.

A location furthermore has these sub-resources:

Sub-resource	Endpoint
Address	/locations/{uuid}/address
Parking type	/locations/{uuid}/parking_information
Parking places	/locations/{uuid}/parking_places
Directions	/locations/{uuid}/directions
Additional fields	/locations/{uuid}/additional_fields
Geolocation	/locations/{uuid}/geolocations
Time settings	/locations/{uuid}/operating_times
Operator / sub-operator	/locations/{uuid}/operator, /locations/{uuid}/sub-operator
Energy mix	/locations/{uuid}/energy-mix

Note

The path segments are not spelled consistently: most sub-resources use snake_case (parking_places, operating_times, additional_fields) while sub-operator and energy-mix use a hyphen. Copy the paths above verbatim.

Directions

Directions are short wayfinding texts telling a driver how to find the charging points once they have arrived at the location — for example “south entrance, level -1, behind the lift”. A location can hold one direction per language.

Unlike a station direction, the language travels in the request body rather than the path, and each direction has its own uuid, which is what DELETE addresses.

Operation	Endpoint
List all directions	GET /locations/{uuid}/directions
Add or update one language	POST /locations/{uuid}/directions
Update one language	PUT /locations/{uuid}/directions
Remove one direction	DELETE /locations/{uuid}/directions?uuid={directionUuid}

POST for a language that already exists replaces its text rather than adding a second entry, so the call is safe to repeat. DELETE for a direction that is already gone is a no-op and also returns 200.

curl --location --request POST \
'https://<slug>.beenergised.cloud/api/cpoapi/v1/locations/<uuid>/directions' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json' \
--data '{
  "language": "de",
  "text": "Eingang Süd, Ebene -1, hinten links neben dem Aufzug"
}'

Parameters

• language (body, string): Two-letter ISO 639-1 code, e.g. de, en, fr. Required, case-insensitive, stored lowercase. Anything that is not two letters is rejected with 400.

  It must further be one of the languages the platform supports, and anything else is rejected with 400. This is the same set the portal’s direction editor offers, so that a direction written here can also be read and corrected in the UI. The supported set does not cover every ISO 639-1 code; if a language you need is missing, ask your contact at has·to·be to have it added.

  DELETE takes no language and is therefore unaffected: directions written before this rule existed may carry a code that is no longer accepted, and they have to stay removable.

• text (body, string): The direction text. Required, trimmed, must not be blank, and at most 512 characters.

Response shape

Most location responses are wrapped in an {id, type, attributes} envelope. The type value identifies the resource:

Endpoint	type
/locations	locations — plural, unlike every sub-resource below
/locations/{uuid}/address	location_address
/locations/{uuid}/parking_information	location_parking_information
/locations/{uuid}/parking_places	location_parking_place
/locations/{uuid}/directions	location_directions
/locations/{uuid}/additional_fields	location_additional_fields
/locations/{uuid}/geolocations	location_geo_location
/locations/{uuid}/operating_times	location_operating_times
/locations/{uuid}/operator	location_operator
/locations/{uuid}/sub-operator	location_sub_operator

The location’s attributes include the address object itself; the sub-resources below are separate resources with their own envelope.

Three responses do not follow the envelope, so do not expect attributes there:

• energy mix returns the fields flat (isGreenEnergy, supplierName, energyProductName, energySources, environImpact) with no id or type.

• operator / sub-operator key the location as locationUuid instead of id.

• the write calls that have nothing to return — DELETE on a location or sub-resource, and PUT/DELETE on /stations — answer 200 with an empty object {}.

Required fields

The API requires the same fields the be.ENERGISED user interface asks for, so a location created through the API is as complete as one created in the UI. A violation is answered with 400.

One difference remains: timezone is only checked for being non-empty here, while the UI offers a fixed list of identifiers.

Creating or updating a location via the locations POST / PUT endpoints requires:

• name

• partyId — exactly 3 alphanumeric characters, e.g. EBE

• partyCountryCode — exactly 2 letters, e.g. AT

• helpPhone — digits, optionally starting with +

• timezone — e.g. Europe/Vienna

• address — see below

• id — additionally on PUT

A location may not exist without an address, so the address travels inline with the location itself:

{
  "name": "Parking deck west",
  "partyId": "EBE",
  "partyCountryCode": "AT",
  "helpPhone": "+4319066670",
  "timezone": "Europe/Vienna",
  "address": {
    "addressLine1": "Lakeside B01",
    "city": "Klagenfurt",
    "countryAlpha3": "AUT"
  }
}

The address is returned by every read as well, so the resource round-trips: what GET /locations/{uuid} hands back can be sent straight to PUT.

It is null for locations stored before an address was mandatory. Those are the one exception to the round-trip: they have to be given an address before they can be updated, since PUT will not accept a missing one.

GET/PUT /locations/{uuid}/address remain available for reading or changing the address on its own.

PUT /locations is a full replace: fields you leave out are cleared, so always send the complete location.

Field rules:

• address — addressLine1, city and a valid countryAlpha3 are required, both inline and on PUT /locations/{uuid}/address; addressLine2, zip, state and county are optional.

• geolocation — latitude (-90 to 90) and longitude (-180 to 180) are both required. Use DELETE to remove coordinates.

• energy mix — the energySources percentages must add up to exactly 100% and each source may only appear once. Sending no sources at all is allowed. Reading is never restricted: a stored mix is always returned as-is, including older data that does not add up to 100%.