Skip to content

EV Charging Stations API

EVChargingStationsApi

A python interface into the HERE EV Charging Stations API

Source code in herepy/ev_charging_stations_api.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 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
105
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
157
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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
class EVChargingStationsApi:
    """A python interface into the HERE EV Charging Stations API"""

    def __init__(self, api_key: str = None, timeout: int = None):
        """Returns a EVChargingStationsApi instance.
        Args:
          api_key (str):
            API key taken from HERE Developer Portal.
          timeout (int):
            Timeout limit for requests.
        """

        self._api_key = api_key
        if timeout:
            self._timeout = timeout
        else:
            self._timeout = 20
        self._base_url = "https://ev-v2.cit.cc.api.here.com/ev/"

    def __get(self, base_url, data, response_cls):
        url = Utils.build_url(base_url, extra_params=data)
        response = requests.get(url, timeout=self._timeout)
        json_data = json.loads(response.content.decode("utf8"))
        if json_data.get("evStations") is not None:
            return response_cls.new_from_jsondict(json_data)
        else:
            raise error_from_ev_charging_service_error(json_data)

    def __connector_types_str(self, connector_types: List[EVStationConnectorTypes]):
        connector_types_str = ""
        for connector_type in connector_types:
            connector_types_str += str.format("{0},", connector_type._value_)
        connector_types_str = connector_types_str[:-1]
        return connector_types_str

    def __corridor_str(self, points: List[float]):
        if len(points) % 2 != 0:
            points = points[:-1]
        corridor_str = ""
        for i in range(0, len(points), 2):
            corridor_str += str.format("{0},{1};", points[i], points[i + 1])
        corridor_str = corridor_str[:-1]
        return corridor_str

    def get_stations_circular_search(
        self,
        latitude: float,
        longitude: float,
        radius: int,
        connectortypes: List[EVStationConnectorTypes] = None,
        maxresults: int = 50,
        offset: int = 0,
    ) -> 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.
          maxresults (int):
            The maximum number of results a response can contain.
            This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
          offset (int):
            A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
            This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
        Returns:
          EVChargingStationsResponse
        Raises:
          HEREError
        """

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

    def get_stations_bounding_box(
        self,
        top_left: List[float],
        bottom_right: List[float],
        connectortypes: List[EVStationConnectorTypes] = None,
        maxresults: int = 50,
        offset: int = 0,
    ) -> 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.
          maxresults (int):
            The maximum number of results a response can contain.
            This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
          offset (int):
            A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
            This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
        Returns:
          EVChargingStationsResponse
        Raises:
          HEREError
        """

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

    def get_stations_corridor(
        self,
        points: List[float],
        connectortypes: List[EVStationConnectorTypes] = None,
        maxresults: int = 50,
        offset: int = 0,
    ) -> 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.
          maxresults (int):
            The maximum number of results a response can contain.
            This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
          offset (int):
            A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
            This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
        Returns:
          EVChargingStationsResponse
        Raises:
          HEREError
        """

        if connectortypes:
            connector_types_str = self.__connector_types_str(connectortypes)
            data = {
                "apiKey": self._api_key,
                "corridor": self.__corridor_str(points),
                "connectortype": connector_types_str,
                "maxresults": maxresults,
                "offset": offset,
            }
        else:
            data = {
                "apiKey": self._api_key,
                "corridor": self.__corridor_str(points),
                "maxresults": maxresults,
                "offset": offset,
            }
        response = self.__get(
            self._base_url + "stations.json", data, EVChargingStationsResponse
        )
        return response

    def get_station_details(
        self, station_id: str, maxresults: int = 50, offset: int = 0
    ) -> 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.
          maxresults (int):
            The maximum number of results a response can contain.
            This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
          offset (int):
            A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
            This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
        Returns:
          EVChargingStationsResponse
        Raises:
          HEREError
        """

        data = {"apiKey": self._api_key, "maxresults": maxresults, "offset": offset}
        url = self._base_url + "stations/" + station_id + ".json"
        response = self.__get(url, data, EVChargingStationsResponse)
        return response

__init__(api_key=None, timeout=None)

Returns a EVChargingStationsApi instance. Args: api_key (str): API key taken from HERE Developer Portal. timeout (int): Timeout limit for requests.

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

    self._api_key = api_key
    if timeout:
        self._timeout = timeout
    else:
        self._timeout = 20
    self._base_url = "https://ev-v2.cit.cc.api.here.com/ev/"

get_station_details(station_id, maxresults=50, offset=0)

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. maxresults (int): The maximum number of results a response can contain. This parameter can be used with the offset parameter in the query and HasMore in the response for pagination. offset (int): A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results. This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination. Returns: EVChargingStationsResponse Raises: HEREError

Source code in herepy/ev_charging_stations_api.py 
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
def get_station_details(
    self, station_id: str, maxresults: int = 50, offset: int = 0
) -> 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.
      maxresults (int):
        The maximum number of results a response can contain.
        This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
      offset (int):
        A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
        This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

    data = {"apiKey": self._api_key, "maxresults": maxresults, "offset": offset}
    url = self._base_url + "stations/" + station_id + ".json"
    response = self.__get(url, data, EVChargingStationsResponse)
    return response

get_stations_bounding_box(top_left, bottom_right, connectortypes=None, maxresults=50, offset=0)

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. maxresults (int): The maximum number of results a response can contain. This parameter can be used with the offset parameter in the query and HasMore in the response for pagination. offset (int): A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results. This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination. Returns: EVChargingStationsResponse Raises: HEREError

Source code in herepy/ev_charging_stations_api.py 
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def get_stations_bounding_box(
    self,
    top_left: List[float],
    bottom_right: List[float],
    connectortypes: List[EVStationConnectorTypes] = None,
    maxresults: int = 50,
    offset: int = 0,
) -> 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.
      maxresults (int):
        The maximum number of results a response can contain.
        This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
      offset (int):
        A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
        This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

    if connectortypes:
        connector_types_str = self.__connector_types_str(connectortypes)
        data = {
            "apiKey": self._api_key,
            "bbox": str.format(
                "{0},{1};{2},{3}",
                top_left[0],
                top_left[1],
                bottom_right[0],
                bottom_right[1],
            ),
            "connectortype": connector_types_str,
            "maxresults": maxresults,
            "offset": offset,
        }
    else:
        data = {
            "apiKey": self._api_key,
            "bbox": str.format(
                "{0},{1};{2},{3}",
                top_left[0],
                top_left[1],
                bottom_right[0],
                bottom_right[1],
            ),
            "maxresults": maxresults,
            "offset": offset,
        }
    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. 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. maxresults (int): The maximum number of results a response can contain. This parameter can be used with the offset parameter in the query and HasMore in the response for pagination. offset (int): A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results. This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination. Returns: EVChargingStationsResponse Raises: HEREError

Source code in herepy/ev_charging_stations_api.py 
 59
 60
 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
105
106
107
108
109
110
111
112
def get_stations_circular_search(
    self,
    latitude: float,
    longitude: float,
    radius: int,
    connectortypes: List[EVStationConnectorTypes] = None,
    maxresults: int = 50,
    offset: int = 0,
) -> 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.
      maxresults (int):
        The maximum number of results a response can contain.
        This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
      offset (int):
        A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
        This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

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

get_stations_corridor(points, connectortypes=None, maxresults=50, offset=0)

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. maxresults (int): The maximum number of results a response can contain. This parameter can be used with the offset parameter in the query and HasMore in the response for pagination. offset (int): A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results. This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination. Returns: EVChargingStationsResponse Raises: HEREError

Source code in herepy/ev_charging_stations_api.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
def get_stations_corridor(
    self,
    points: List[float],
    connectortypes: List[EVStationConnectorTypes] = None,
    maxresults: int = 50,
    offset: int = 0,
) -> 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.
      maxresults (int):
        The maximum number of results a response can contain.
        This parameter can be used with the offset parameter in the query and HasMore in the response for pagination.
      offset (int):
        A value specifying the index of the first result. The offset together with the "maxresults" value can be used to support a paging mechanism on search results.
        This parameter can be used with the maxresults parameter in the query and HasMore in the response for pagination.
    Returns:
      EVChargingStationsResponse
    Raises:
      HEREError
    """

    if connectortypes:
        connector_types_str = self.__connector_types_str(connectortypes)
        data = {
            "apiKey": self._api_key,
            "corridor": self.__corridor_str(points),
            "connectortype": connector_types_str,
            "maxresults": maxresults,
            "offset": offset,
        }
    else:
        data = {
            "apiKey": self._api_key,
            "corridor": self.__corridor_str(points),
            "maxresults": maxresults,
            "offset": offset,
        }
    response = self.__get(
        self._base_url + "stations.json", data, EVChargingStationsResponse
    )
    return response

UnauthorizedError

Bases: HEREError

Unauthorized Error Type.

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

Source code in herepy/ev_charging_stations_api.py 
249
250
251
252
253
254
255
class UnauthorizedError(HEREError):

    """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 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
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)
    elif "error" in json_data and "error_description" in json_data:
        return HEREError(
            "Error occurred: "
            + json_data["error"]
            + ", description: "
            + json_data["error_description"]
        )
    # pylint: disable=W0212
    return HEREError("Error occurred on " + sys._getframe(1).f_code.co_name)