Echarging Stations Howto

This howto uses the E-charging stations dataset to showcase a few basic API calls, whose output will be needed in most complex calls.

Dataset Information

This datasets exposes data about the existing e-charging stations in South Tyrol and their status, including historical data and usage.

License CC0 license (public domain)
Output JSON, mime-type application/json
E-mail contact info@opendatahub.bz.it
API version v1
Swagger URL http://ipchannels.integreen-life.bz.it/EchargingFrontEnd

Invoking the API

The available methods in this API are very generic, so some post-processing of the JSON that you receive as output will probably be necessary.

The API calls shown here can be used with other datasets of the mobility domain.

You can find all the API’s defined methods and documentation at the URL http://ipchannels.integreen-life.bz.it/EchargingFrontEnd.

The two most basic REST calls are carried out by the methods get-stations and get-station-details.

get-stations

The get-stations method requires no parameters and retrieves all the IDs of the charging stations that are part of this dataset.

There are two possibilities to retrieve the data with the API call:

  1. By HTTP request:

    http://ipchannels.integreen-life.bz.it/emobility/rest/get-stations
    
  2. Using a command line with a tool like curl or wget:

    curl -X GET --header 'Accept: application/json' 'http://ipchannels.integreen-life.bz.it/emobility/rest/get-stations'
    

The result structure is a json list of strings, and an actual outcome is (shortened for the sake of clarity):

[
  "IT*220*EBZ000034",
  "82",
  "DW_000006",
  "DW_000009",
  "IT*220*ETN020016",
  "83",
  "84",
  "DW_000013",
  "DW_000019",
  "85",
]

Each of the IDs can then be used in other methods to obtain more detailed information about the station.

get-station-details

The get-station-details method requires no parameters and retrieves all the known information for each charging station in the dataset. Like the previous method, two method can be used for the call:

  1. By HTTP request:

    http://ipchannels.integreen-life.bz.it/emobility/rest/get-station-details
    
  2. Using a command line with a tool like curl or wget:

    curl -X GET --header 'Accept: application/json' 'http://ipchannels.integreen-life.bz.it/emobility/rest/get-station-details'
    

The result structure is a json list of strings, and an actual outcome is (shortened for the sake of clarity):

{
  "_t": "it.bz.idm.bdp.dto.emobility.EchargingStationDto",
  "id": "ASM_00000103",
  "name": "BRIXEN_02",
  "latitude": 46.706333,
  "longitude": 11.651225,
  "municipality": "Brixen - Bressanone",
  "capacity": 2,
  "provider": "Alperia Smart Mobility",
  "city": "BRESSANONE - BRIXEN",
  "state": "ACTIVE",
  "paymentInfo": "https://www.alperiaenergy.eu/smart-mobility/punti-di-ricarica.html",
  "accessType": "PUBLIC",
  "address": "CLUB MAX - Fischzuchtweg - Via del Laghetto"
},
{
  "_t": "it.bz.idm.bdp.dto.emobility.EchargingStationDto",
  "id": "DW-000027",
  "name": "San Vigilio Hotel Sport",
  "latitude": 46.698061,
  "longitude": 11.934766,
  "municipality": "Marèo - Enneberg - Marebbe",
  "capacity": 1,
  "provider": "DriWe",
  "city": "San Vigilio (Marebbe)",
  "state": "ACTIVE",
  "paymentInfo": "http://www.driwe.eu",
  "accessInfo": "24h",
  "accessType": "PRIVATE_WITHPUBLICACCESS",
  "categories": [
       "EAT&CHARGE",
       "SLEEP&CHARGE"
  ],
  "address": "Strada al Plan Dessora",
  "reservable": true
},

As you see from the example, many of the e-charging station’s metadata is shared by all of them including the (unique) ID, name, location (town or city, address, geographic coordinates), access to it. There are however additional metadata that are optional (like the station’s category and if it is reservable.

Troubleshooting

If the API call fails, one of the following response code is returned - they correspond to HTTP status codes :

401 Unauthorised
The request is valid, but authentication is required and you provided none. This should never happen, you should receive an empty output set if you require data that are not publicly available.
403 Forbidden
The request is valid but could not be completed on the server side.
404 Not found
There is an syntax error in the call you made or the page is not available at this moment.
500 Internal Server Error
Oh, well. Apparently we have a problem now…