Skip to content

EV Charging Stations API

EVChargingStationsApi

A python interface into the HERE EV Charging Stations API

__init__(self, app_id=None, app_code=None, timeout=None) special

Returns a EVChargingStationsApi instance.

Parameters:

Name Type Description Default
app_id str

App Id taken from HERE Developer Portal.

None
app_code str

API Code taken from HERE Developer Portal.

None
timeout int

Timeout limit for requests.

None
Source code in herepy/ev_charging_stations_api.py
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(self, app_id: str = None, app_code: str = None, timeout: int = None):
    """Returns a EVChargingStationsApi instance.
    Args:
      app_id (str):
        App Id taken from HERE Developer Portal.
      app_code (str):
        API Code taken from HERE Developer Portal.
      timeout (int):
        Timeout limit for requests.
    """

    self._app_id = app_id
    self._app_code = app_code
    if timeout:
        self._timeout = timeout
    else:
        self._timeout = 20
    self._base_url = "https://ev-v2.cit.cc.api.here.com/ev/"

get_station_details(self, station_id)

Based on the results of a search for charging stations, this method retrieves the full/updated information about a single charging station only.

Parameters:

Name Type Description Default
station_id str

station_id is an attribute of the evStation element with a unique value.

required

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def get_station_details(
    self, station_id: str
) -> Optional[EVChargingStationsResponse]:
    """Based on the results of a search for charging stations, this method
    retrieves the full/updated information about a single charging station only.
    Args:
      station_id (str):
        station_id is an attribute of the evStation element with a unique value.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

    data = {"app_id": self._app_id, "app_code": self._app_code}
    url = self._base_url + "stations/" + station_id + ".json"
    response = self.__get(url, data, EVChargingStationsResponse)
    return response

get_stations_bounding_box(self, top_left, bottom_right, connectortypes=None)

Makes a search request for charging stations with in given bounding box. The bounding box can have a maximum height / width of 400km.

Parameters:

Name Type Description Default
top_left List[float]

List contains latitude and longitude in order.

required
bottom_right List[float]

List contains latitude and longitude in order.

required
connectortypes List[herepy.here_enum.EVStationConnectorTypes]

Optional, to identify the connector types.

None

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def get_stations_bounding_box(
    self,
    top_left: List[float],
    bottom_right: List[float],
    connectortypes: List[EVStationConnectorTypes] = None,
) -> Optional[EVChargingStationsResponse]:
    """Makes a search request for charging stations with in given
       bounding box. The bounding box can have a maximum height / width of 400km.
    Args:
      top_left (List):
        List contains latitude and longitude in order.
      bottom_right (List):
        List contains latitude and longitude in order.
      connectortypes (List[EVStationConnectorTypes]):
        Optional, to identify the connector types.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

    if connectortypes:
        connector_types_str = self.__connector_types_str(connectortypes)
        data = {
            "app_id": self._app_id,
            "app_code": self._app_code,
            "bbox": str.format(
                "{0},{1};{2},{3}",
                top_left[0],
                top_left[1],
                bottom_right[0],
                bottom_right[1],
            ),
            "connectortype": connector_types_str,
        }
    else:
        data = {
            "app_id": self._app_id,
            "app_code": self._app_code,
            "bbox": str.format(
                "{0},{1};{2},{3}",
                top_left[0],
                top_left[1],
                bottom_right[0],
                bottom_right[1],
            ),
        }
    response = self.__get(
        self._base_url + "stations.json", data, EVChargingStationsResponse
    )
    return response

Makes a search request for charging stations. A circular search area defined by the latitude and longitude of its center (compliant with WGS 84) and an integer representing the radius of the area in meters, all separated by commas.

Parameters:

Name Type Description Default
latitude float

latitude.

required
longitude float

longitude.

required
radius int

Radius of circular area in meter. Radius can be a maximum of 200 km (200000).

required
connectortypes List[herepy.here_enum.EVStationConnectorTypes]

Optional, to identify the connector types.

None

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def get_stations_circular_search(
    self,
    latitude: float,
    longitude: float,
    radius: int,
    connectortypes: List[EVStationConnectorTypes] = None,
) -> Optional[EVChargingStationsResponse]:
    """Makes a search request for charging stations.
       A circular search area defined by the latitude and longitude of its center
       (compliant with WGS 84) and an integer representing the radius of the area
       in meters, all separated by commas.
    Args:
      latitude (float):
        latitude.
      longitude (float):
        longitude.
      radius (int):
        Radius of circular area in meter. Radius can be a maximum of 200 km (200000).
      connectortypes (List[EVStationConnectorTypes]):
        Optional, to identify the connector types.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

    if connectortypes:
        connector_types_str = self.__connector_types_str(connectortypes)
        data = {
            "app_id": self._app_id,
            "app_code": self._app_code,
            "prox": str.format("{0},{1},{2}", latitude, longitude, radius),
            "connectortype": connector_types_str,
        }
    else:
        data = {
            "app_id": self._app_id,
            "app_code": self._app_code,
            "prox": str.format("{0},{1},{2}", latitude, longitude, radius),
        }
    response = self.__get(
        self._base_url + "stations.json", data, EVChargingStationsResponse
    )
    return response

get_stations_corridor(self, points, connectortypes=None)

Makes a search request for charging stations with in given corridor. Maximum corridor area is 5000 km2.

Parameters:

Name Type Description Default
points List[float]

List contains latitude and longitude pairs in order.

required
connectortypes List[herepy.here_enum.EVStationConnectorTypes]

Optional, to identify the connector types.

None

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
def get_stations_corridor(
    self, points: List[float], connectortypes: List[EVStationConnectorTypes] = None
) -> Optional[EVChargingStationsResponse]:
    """Makes a search request for charging stations with in given corridor.
       Maximum corridor area is 5000 km2.
    Args:
      points (List):
        List contains latitude and longitude pairs in order.
      connectortypes (List[EVStationConnectorTypes]):
        Optional, to identify the connector types.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

    if connectortypes:
        connector_types_str = self.__connector_types_str(connectortypes)
        data = {
            "app_id": self._app_id,
            "app_code": self._app_code,
            "corridor": self.__corridor_str(points),
            "connectortype": connector_types_str,
        }
    else:
        data = {
            "app_id": self._app_id,
            "app_code": self._app_code,
            "corridor": self.__corridor_str(points),
        }
    response = self.__get(
        self._base_url + "stations.json", data, EVChargingStationsResponse
    )
    return response

UnauthorizedError

Unauthorized Error Type.

This error is returned if the specified token was invalid or no contract
could be found for this token.

error_from_ev_charging_service_error(json_data)

Return the correct subclass for ev charging errors

Source code in herepy/ev_charging_stations_api.py
223
224
225
226
227
228
229
230
231
232
233
def error_from_ev_charging_service_error(json_data: dict):
    """Return the correct subclass for ev charging errors"""

    if "Type" in json_data:
        error_type = json_data["Type"]
        message = json_data["Message"]

        if error_type == "Unauthorized":
            return UnauthorizedError(message)
    # pylint: disable=W0212
    return HEREError("Error occured on " + sys._getframe(1).f_code.co_name)