Short description

The Location API allows Partner to retrieve the Location objects in an OCPI related format.
GreenFlux also has Push/Webhook mechanisms to push location status updates to CPOs.
Link to Locations

Use cases:

Create data lake with up-to-date Location and EVSE information
Get real-time information on charge station availability for e.g. systems, websites, etc

Setup

The Locations module has Locations as base object, Locations have EVSEs, EVSEs have Connectors.

Note: In the Location object, the property of a 'charge station' does not exist. Only EVSEs are part of a Location.

Flows

Greenflux provides Push and Pull

Pull

GreenFlux provides these endpoints to GET Location information with:

All Locations of CPO
Location ID
EVSE ID
Connector ID

See further below of an example Location response.

Push / Webhooks

GreenFlux can establish a push connection to CPO Customers that mirrors updates of Locations from the Roaming networks.

PUT Location

GreenFlux pushes available Location/EVSE or Connector objects to the eMSP. PUT is used to send new Location objects to the eMSP, or to replace existing Locations.

Same code example as for a GET call.

PATCH Location

A PATCH request sends an update of only the fields/objects where a change has occurred. Other fields/objects that are not specified are considered unchanged.

Typically this is just the Status, moving between AVAILABLE and CHARGING (or to a faulted state)

PATCH To URL: https://www.server.com/locations/NL/GFX/0d4ef8c6-e0c8-54c1d-b4f4-eb245f3f7afa/BE-BEC-E041503001-1

{
"status": "CHARGING"
}

Endpoints

For the PUSH mechanism, GreenFlux requires an endpoint from the customer.

PUT Location
We will append the message with {country-code}/{party-id}/{Location-id}
e.g. NL/GFX/0d4ef8c6-e0c8-54c1d-b4f4-eb245f3f7afa

PATCH EVSE
For Patch, we update the specific EVSE-ID: {country-code}/{party-id}/{Location-id}/{EVSE-ID}
e.g. NL/GFX/0d4ef8c6-e0c8-54c1d-b4f4-eb245f3f7afa/BE-BEC-E041503001-1

Authorisation

Every HTTP request MUST add an 'Authorization' header. The header looks as follows:

Authorization: Token IpbJOXxkxOAuKR92z0nEcmVF3Qw09VG7I7d/WCg0koM=

Published Location

For Platform connections/CPO data APIs, all Locations will be accessible via API, regardless of published status.
In OCPI/Roaming, only published locations will be shared.

Published status is indicated by the 'publish' field in the Location API.

A Locations needs to have at least on EVSE in order for it to show in the API.

Restricted Access

Generally speaking in the EV world, there are public, semi-public and private charge locations.

Public locations are those published via roaming.
Private locations are not published via roaming.
Semi-public can be indicated through the Parking Restriction field in OCPI. When the Customers restriction is set, this should indicate to EMSP apps that this location has restrictions. However, it can't be guaranteed how Locations will be shown in Apps or navigation systems.

CUSTOMERS - Parking spot for customers/guests only, for example in case of a hotel or shop.

Restricted Access in the EV Portal will add the Parking Restriction: CUSTOMERS to the Location object.

📘
Published location
Until 28. September it was required for Platform connections to have the Location published. This is no longer a requirement.

Examples

Example Location response - extended

Below is an extended Location with response .

{
   "id":"0d4ef8c6-e0c8-54c1d-b4f4-eb245f3f7afa",
   "type":"ON_STREET",
   "publish": true,
   "name":"Gent Zuid",
   "address":"F.Rooseveltlaan 3A",
   "city":"Gent",
   "postal_code":"9000",
   "country":"BEL",
   "coordinates":{
      "latitude":"51.047599",
      "longitude":"3.729944"
   },
   "evses":[
      {
         "uid":"BE-BEC-E041503001",
         "evse_id":"BE*BEC*E041503001",
         "status":"AVAILABLE",
         "status_schedule":[
            
         ],
         "capabilities":[
            "CHARGING_PROFILE_CAPABLE",
            "CREDIT_CARD_PAYABLE",
            "REMOTE_START_STOP_CAPABLE",
            "RESERVABLE",
            "RFID_READER",
            "UNLOCK_CAPABLE"
         ],
         "connectors":[
            {
               "id":"1",
               "standard":"IEC_62196_T2",
               "format":"CABLE",
               "power_type":"AC_3_PHASE",
               "voltage":220,
               "amperage":16,
               "tariff_id":"11",
               "last_updated":"2015-03-16T10:10:02Z"
            },
            {
               "id":"2",
               "standard":"IEC_62196_T2",
               "format":"SOCKET",
               "power_type":"AC_3_PHASE",
               "voltage":220,
               "amperage":16,
               "tariff_id":"11",
               "last_updated":"2015-03-18T08:12:01Z"
            }
         ],
         "physical_reference":"1",
         "floor_level":"-1",
         "coordinates": null,
         "directions": [],
         "parking_restrictions": [],
         "images": null,
         "last_updated": "2021-06-07T18:25:01Z"
      },
      {
         "uid":"BE-BEC-E04150300",
         "evse_id":"BE*BEC*E041503002",
         "status":"CHARGING",
         "capabilities":[
            "CHARGING_PROFILE_CAPABLE",
            "CREDIT_CARD_PAYABLE",
            "REMOTE_START_STOP_CAPABLE",
            "RESERVABLE",
            "RFID_READER",
            "UNLOCK_CAPABLE"
         ],
         "connectors":[
            {
               "id":"1",
               "standard":"IEC_62196_T2",
               "format":"SOCKET",
               "power_type":"DC",
               "voltage":500,
               "amperage":100,
               "tariff_id":"12",
               "last_updated":"2015-06-29T20:39:09Z"
            }
         ],
         "physical_reference":"2",
         "floor_level":"-2",
         "coordinates": null,
         "directions": [],
         "parking_restrictions": [],
         "images": null,
         "last_updated":"2015-06-29T20:39:09Z"
      }
   ],
       "directions": [
            {
              "language": "en",
              "text": "In front of the Supermarket"
            }
          ],
     "operator": {
      "name":"EVChargepointOperator",
      "website":"https://www.EVChargepointOperator.nl",
      "logo":{
         "url":"https://www.EVChargepointOperator.nl/logo.png",
         "thumbnail":"https://www.EVChargepointOperator.nl/icon.ico",
         "category":"OPERATOR",
         "type":"png",
         "width":0,
         "height":0
      }
   },
   "suboperator": {
      "name":"EVChargepointOperator"
   },
   "owner": {
      "name":"EVChargepointOperator"
   },
   "facilities": [
        "AIRPORT",
        "BUS_STOP",
        "CAFE",
        "CARPOOL_PARKING",
        "FUEL_STATION",
        "HOTEL",
        "MALL",
        "MUSEUM",
        "NATURE",
        "RECREATION_AREA",
        "RESTAURANT",
        "SPORT",
        "SUPERMARKET",
        "TAXI_STAND",
        "TRAIN_STATION",
        "WIFI"
      ],
   "time_zone":null,
   "opening_times": {
      "regular_hours": [
         {
            "weekday":1,
            "period_begin":"00:00",
            "period_end":"23:59"
         },
         {
            "weekday":2,
            "period_begin":"00:00",
            "period_end":"23:59"
         },
         {
            "weekday":3,
            "period_begin":"00:00",
            "period_end":"23:59"
         },
         {
            "weekday":4,
            "period_begin":"00:00",
            "period_end":"23:59"
         },
         {
            "weekday":5,
            "period_begin":"00:00",
            "period_end":"23:59"
         },
         {
            "weekday":6,
            "period_begin":"08:00",
            "period_end":"22:00"
         },
         {
            "weekday":7,
            "period_begin":"08:00",
            "period_end":"12:00"
         },
         {
            "weekday":7,
            "period_begin":"15:00",
            "period_end":"22:00"
         }
      ],
      "twentyfourseven":false,
      "charging_when_closed":null,
      "images":null,
      "energy_mix": {
         "is_green_energy":false,
         "energy_sources": [
            {
               "source":"GENERAL_GREEN",
               "percentage":35.9
            },
            {
               "source":"GAS",
               "percentage":6.3
            },
            {
               "source":"COAL",
               "percentage":33.2
            },
            {
               "source":"GENERAL_FOSSIL",
               "percentage":2.9
            },
            {
               "source":"NUCLEAR",
               "percentage":21.7
            }
         ],
         "environ_impact":[
            {
               "source":"NUCLEAR_WASTE",
               "amount":0.0006
            },
            {
               "source":"CARBON_DIOXIDE",
               "amount":372
            }
         ],
         "supplier_name":"E.ON Energy Deutschland",
         "energy_product_name":"E.ON DirektStrom eco"
      },
      "last_updated":"2021-06-29T20:39:09Z"
   }
}

Example Location response - simple

Below is an example of a 'simple' Location object filled with the minimum requirements.

{
   "id":"08110553",
   "type":"UNKNOWN",
   "publish": true,
   "address":"Grossweg Straße 10",
   "city":"Höxter",
   "postal_code":"37671",
   "country":"DEU",
   "coordinates":{
      "latitude":"51.810697",
      "longitude":"9.426715"
   },
   "related_locations":[],
   "directions":[],
   "evses":[
      {
         "uid":"08110553_1",
         "evse_id":"DE*DEF*E08400147*0",
         "status":"AVAILABLE",
         "status_schedule":[]
         "capabilities":[
            "RFID_READER"
         ],
         "connectors":[
            {
               "amperage":16,
               "format":"SOCKET",
               "id":"0",
               "last_updated":"2021-07-09T14:11:58.561Z",
               "power_type":"AC_3_PHASE",
               "standard":"IEC_62196_T2",
               "voltage":230
            }
         ],
         "directions":[],
         "parking_restrictions":[],
         "images":[],
         "last_updated":"2021-07-09T14:11:58.561Z"
      }
   ],
   "facilities":[]
   "operator":{
      "name":"CPO Corp",
      "images":[],
      "last_updated":"2021-07-09T14:11:58.561Z"
   }
}

Short description

Setup

Flows

Pull

Push / Webhooks

PUT Location

PATCH Location

Endpoints

Authorisation

Published Location

Restricted Access

📘Published location

Examples

Example Location response - extended

Example Location response - simple

📘
Published location