Skip to content

EV Charging Stations API

EVChargingStationsApi

A python interface into the HERE EV Charging Stations API

__init__(self, api_key=None, timeout=None) special

Returns a EVChargingStationsApi instance.

Parameters:

Name Type Description Default
api_key str

API key taken from HERE Developer Portal.

None
timeout int

Timeout limit for requests.

None
Source code in herepy/ev_charging_stations_api.py
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(self, 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.

Parameters:

Name Type Description Default
station_id str

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

required
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.

50
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.

0

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
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(self, 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.

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
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.

50
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.

0

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
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.

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
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.

50
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.

0

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
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(self, points, connectortypes=None, maxresults=50, offset=0)

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
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.

50
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.

0

Returns:

Type Description
Optional[herepy.models.EVChargingStationsResponse]

EVChargingStationsResponse

Source code in herepy/ev_charging_stations_api.py
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

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
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)