Skip to content

Public Transit API

PublicTransitApi

A python interface into the HERE Public Transit API

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

Returns a PublicTransitApi 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/public_transit_api.py
def __init__(self, api_key: str = None, timeout: int = None):
    """Returns a PublicTransitApi instance.
    Args:
      api_key (str):
        API key taken from HERE Developer Portal.
      timeout (int):
        Timeout limit for requests.
    """

    super(PublicTransitApi, self).__init__(api_key, timeout)
    self._base_url = "https://transit.ls.hereapi.com/v3/"

calculate_route(self, departure, arrival, time, max_connections=3, changes=-1, lang='en', include_modes=None, exclude_modes=None, units='metric', max_walking_distance=2000, walking_speed=100, show_arrival_times=True, graph=False, routing_mode=<PublicTransitRoutingMode.schedule: 'schedule'>)

Request a public transit route between any two places.

Parameters:

Name Type Description Default
departure List[float]

List contains latitude and longitude in order.

required
arrival List[float]

List contains latitude and longitude in order.

required
time str

time formatted in yyyy-mm-ddThh:mm:ss.

required
max_connections int

Specifies the number of following departure/arrivals the response should include. The possible values are: 1-6.

3
changes int

Specifies the maximum number of changes or transfers allowed in a route. 0-6 or -1. The default is -1 (which disables the filter, or unlimited no of changes permitted).

-1
lang str

Specifies the language of the response.

'en'
include_modes List[herepy.here_enum.PublicTransitModeType]

Specifies the transit type filter used to determine which types of transit to include in the response.

None
exclude_modes List[herepy.here_enum.PublicTransitModeType]

Specifies the transit type filter used to determine which types of transit to exclude in the response.

None
units str

Units of measurement used. metric oder imperial.

'metric'
max_walking_distance int

Specifies a maximum walking distance in meters. Allowed values are 0-6000.

2000
walking_speed int

Specifies the walking speed in percent of normal walking speed. Allowed values are 50-200.

100
show_arrival_times bool

flag to indicate if response should show arrival times or departure times.

True
graph bool

flag to indicate if response should contain coordinate pairs to allow the drawing of a polyline for the route.

False
routing_type PublicTransitRoutingType

type of routing. Default is time_tabled.

required

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def calculate_route(
    self,
    departure: List[float],
    arrival: List[float],
    time: str,
    max_connections: int = 3,
    changes: int = -1,
    lang: str = "en",
    include_modes: List[PublicTransitModeType] = None,
    exclude_modes: List[PublicTransitModeType] = None,
    units: str = "metric",
    max_walking_distance: int = 2000,
    walking_speed: int = 100,
    show_arrival_times: bool = True,
    graph: bool = False,
    routing_mode: PublicTransitRoutingMode = PublicTransitRoutingMode.schedule,
) -> Optional[PublicTransitResponse]:
    """Request a public transit route between any two places.
    Args:
      departure (List):
        List contains latitude and longitude in order.
      arrival (List):
        List contains latitude and longitude in order.
      time (str):
        time formatted in yyyy-mm-ddThh:mm:ss.
      max_connections (int):
        Specifies the number of following departure/arrivals the response should include.
        The possible values are: 1-6.
      changes (int):
        Specifies the maximum number of changes or transfers allowed in a route.
        0-6 or -1.
        The default is -1 (which disables the filter, or unlimited no of changes permitted).
      lang (str):
        Specifies the language of the response.
      include_modes (List[PublicTransitModeType]):
        Specifies the transit type filter used to determine which types of transit to include in the response.
      exclude_modes (List[PublicTransitModeType]):
        Specifies the transit type filter used to determine which types of transit to exclude in the response.
      units (str):
        Units of measurement used. metric oder imperial.
      max_walking_distance (int):
        Specifies a maximum walking distance in meters. Allowed values are 0-6000.
      walking_speed (int):
        Specifies the walking speed in percent of normal walking speed. Allowed values are 50-200.
      show_arrival_times (boolean):
        flag to indicate if response should show arrival times or departure times.
      graph (boolean):
        flag to indicate if response should contain coordinate pairs to allow the drawing of a polyline for the route.
      routing_type (PublicTransitRoutingType):
        type of routing. Default is time_tabled.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "dep": str.format("{0},{1}", departure[0], departure[1]),
        "arr": str.format("{0},{1}", arrival[0], arrival[1]),
        "max": max_connections,
        "time": time,
        "changes": changes,
        "lang": lang,
        "units": units,
        "walk": ",".join([str(max_walking_distance), str(walking_speed)]),
        "arrival": 1 if show_arrival_times == True else 0,
        "apikey": self._api_key,
        "graph": 1 if graph == True else 0,
        "routingMode": routing_mode.__str__(),
    }

    modes = None
    if include_modes is not None and exclude_modes is not None:
        raise HEREError("Specify either include_modes or exclude_modes, not both.")
    if include_modes is not None:
        modes = ",".join(mode.__str__() for mode in include_modes)
    if exclude_modes is not None:
        modes = ",".join("-" + mode.__str__() for mode in exclude_modes)
    if modes is not None:
        data["modes"] = modes

    response = self.__get(data, "route.json", "Connections")
    response_with_short_route = self._get_response_with_short_route(response)
    return response_with_short_route

coverage_nearby(self, details, center)

Request a list of transit operators and station coverage nearby.

Parameters:

Name Type Description Default
details int

0 disables showing line info, 1 enables showing line info.abs

required
center List[float]

List contains latitude and longitude in order.

required

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def coverage_nearby(
    self, details: int, center: List[float]
) -> Optional[PublicTransitResponse]:
    """Request a list of transit operators and station coverage nearby.
    Args:
      details (int):
        0 disables showing line info, 1 enables showing line info.abs
      center (List):
        List contains latitude and longitude in order.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """
    data = {
        "details": details,
        "center": str.format("{0},{1}", center[0], center[1]),
        "apikey": self._api_key,
    }
    return self.__get(data, "coverage/nearby.json", "LocalCoverage")

coverage_witin_a_city(self, city_name, political_view, max=None, details=1, lang='en')

Request a list of transit operator coverage within a specified city.

Parameters:

Name Type Description Default
city_name str

the name or part of the name of the search city.

required
political_view int

1 enables, 0 disables grouping results.

required
max int

maximum number of results.

None
details int

with 1 supported list of operators and population added to response. Set to 0 just return the matching city names.

1
lang str

the language of the response, default en.

'en'

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def coverage_witin_a_city(
    self,
    city_name: str,
    political_view: int,
    max: int = None,
    details: int = 1,
    lang: str = "en",
) -> Optional[PublicTransitResponse]:
    """Request a list of transit operator coverage within a specified city.
    Args:
      city_name (str):
        the name or part of the name of the search city.
      political_view (int):
        1 enables, 0 disables grouping results.
      max (int):
        maximum number of results.
      details (int):
        with 1 supported list of operators and population added to response.
        Set to 0 just return the matching city names.
      lang (str):
        the language of the response, default `en`.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "name": city_name,
        "apikey": self._api_key,
        "max": max,
        "details": details,
        "politicalview": political_view,
        "lang": lang,
    }
    if max is None:
        del data["max"]
    return self.__get(data, "coverage/search.json", "Coverage")

find_stations_by_id(self, ids, lang)

Request details of a specific transit station based on a previous request.

Parameters:

Name Type Description Default
ids List[int]

List contains station ids.

required
lang str

language code for response like en.

required

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def find_stations_by_id(
    self, ids: List[int], lang: str
) -> Optional[PublicTransitResponse]:
    """Request details of a specific transit station based on a previous request.
    Args:
      ids (List):
        List contains station ids.
      lang (str):
        language code for response like `en`.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "stnIds": self.__prepare_station_ids(ids),
        "lang": lang,
        "apikey": self._api_key,
    }
    return self.__get(data, "stations/by_ids.json", "Stations")

find_stations_by_name(self, center, name, max_count=5, method=<PublicTransitSearchMethod.fuzzy: 'fuzzy'>, radius=20000)

Request a list of public transit stations based on name.

Parameters:

Name Type Description Default
center List[float]

List contains latitude and longitude in order.

required
name str

station name.

required
max_count int

maximum number of stations (Default is 5).

5
method PublicTransitSearchMethod

Matching method from PublicTransitSearchMethod (Default is fuzzy).

<PublicTransitSearchMethod.fuzzy: 'fuzzy'>
radius int

specifies radius in kilometers (Default is 20000km).

20000

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def find_stations_by_name(
    self,
    center: List[float],
    name: str,
    max_count: int = 5,
    method: PublicTransitSearchMethod = PublicTransitSearchMethod.fuzzy,
    radius: int = 20000,
) -> Optional[PublicTransitResponse]:
    """Request a list of public transit stations based on name.
    Args:
      center (List):
        List contains latitude and longitude in order.
      name (str):
        station name.
      max_count (int):
        maximum number of stations  (Default is 5).
      method (enum):
        Matching method from PublicTransitSearchMethod (Default is fuzzy).
      radius (int):
        specifies radius in kilometers (Default is 20000km).
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "center": str.format("{0},{1}", center[0], center[1]),
        "name": name,
        "apikey": self._api_key,
        "max": max_count,
        "method": method.__str__(),
        "radius": radius,
    }
    return self.__get(data, "stations/by_name.json", "Stations")

find_stations_nearby(self, center, radius=500, max_count=5)

Request a list of public transit stations within a given geo-location.

Parameters:

Name Type Description Default
center List[float]

List contains latitude and longitude in order.

required
radius int

specifies radius in meters (Default is 500m).

500
max_count int

maximum number of stations (Default is 5).

5

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def find_stations_nearby(
    self, center: List[float], radius: int = 500, max_count: int = 5
) -> Optional[PublicTransitResponse]:
    """Request a list of public transit stations within a given geo-location.
    Args:
      center (List):
        List contains latitude and longitude in order.
      radius (int):
        specifies radius in meters (Default is 500m).
      max_count (int):
        maximum number of stations  (Default is 5).
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "center": str.format("{0},{1}", center[0], center[1]),
        "radius": radius,
        "apikey": self._api_key,
        "max": max_count,
    }
    return self.__get(data, "stations/by_geocoord.json", "Stations")

find_transit_coverage_in_cities(self, center, political_view, radius)

Request a list of transit operators available in cities nearby.

Parameters:

Name Type Description Default
center List[float]

List contains latitude and longitude in order.

required
political_view str

switch for grouping results like CHN.

required
radius int

specifies radius in meters.

required

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def find_transit_coverage_in_cities(
    self, center: List[float], political_view: str, radius: int
) -> Optional[PublicTransitResponse]:
    """Request a list of transit operators available in cities nearby.
    Args:
      center (List):
        List contains latitude and longitude in order.
      political_view (str):
        switch for grouping results like `CHN`.
      radius (int):
        specifies radius in meters.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "center": str.format("{0},{1}", center[0], center[1]),
        "politicalview": political_view,
        "radius": radius,
        "apikey": self._api_key,
    }
    return self.__get(data, "coverage/city.json", "Coverage")

next_departures_for_stations(self, station_ids, time, lang='en', max=40, max_station=40)

Request a list of all next departure times and destinations for a give list of stations.

Parameters:

Name Type Description Default
station_ids List[int]

a list of stop ids.

required
time str

time formattes in yyyy-mm-ddThh:mm:ss.

required
lang str

language code for response like en. Default is en.

'en'
max int

maximum number of next departures per station. Default is 40.

40
max_station int

maximum number of stations for which departures are required. Default is 40.

40

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def next_departures_for_stations(
    self,
    station_ids: List[int],
    time: str,
    lang: str = "en",
    max: int = 40,
    max_station: int = 40,
) -> Optional[PublicTransitResponse]:
    """Request a list of all next departure times and destinations for a give list of stations.
    Args:
      station_ids (List):
        a list of stop ids.
      time (str):
        time formattes in yyyy-mm-ddThh:mm:ss.
      lang (str):
        language code for response like `en`. Default is `en`.
      max (int):
        maximum number of next departures per station. Default is 40.
      max_station (int):
        maximum number of stations for which departures are required. Default is 40.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "lang": lang,
        "time": time,
        "apikey": self._api_key,
        "max": max,
        "maxStn": max_station,
        "stnIds": self.__prepare_station_ids(station_ids),
    }
    return self.__get(data, "multiboard/by_stn_ids.json", "MultiNextDepartures")

next_departures_from_location(self, center, time, lang='en', max=40, max_station=40)

Request a list of all next departure times and destinations from a given location.

Parameters:

Name Type Description Default
center List[float]

List contains latitude and longitude in order.

required
time str

time formattes in yyyy-mm-ddThh:mm:ss.

required
lang str

language code for response like en. Default is en.

'en'
max int

maximum number of next departures per station. Default is 40.

40
max_station int

maximum number of stations for which departures are required. Default is 40.

40

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def next_departures_from_location(
    self,
    center: List[float],
    time: str,
    lang: str = "en",
    max: int = 40,
    max_station: int = 40,
) -> Optional[PublicTransitResponse]:
    """Request a list of all next departure times and destinations from a given location.
    Args:
      center (List):
        List contains latitude and longitude in order.
      time (str):
        time formattes in yyyy-mm-ddThh:mm:ss.
      lang (str):
        language code for response like `en`. Default is `en`.
      max (int):
        maximum number of next departures per station. Default is 40.
      max_station (int):
        maximum number of stations for which departures are required. Default is 40.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "lang": lang,
        "center": str.format("{0},{1}", center[0], center[1]),
        "time": time,
        "apikey": self._api_key,
        "max": max,
        "maxStn": max_station,
    }
    return self.__get(data, "multiboard/by_geocoord.json", "MultiNextDepartures")

next_nearby_departures_of_station(self, station_id, time, lang='en')

Request a list of next departure times and destinations of a particular station.

Parameters:

Name Type Description Default
lang str

language code for response like en Default is en.

'en'
station_id int

station id for departures.

required
time str

time formattes in yyyy-mm-ddThh:mm:ss.

required

Returns:

Type Description
Optional[herepy.models.PublicTransitResponse]

PublicTransitResponse

Source code in herepy/public_transit_api.py
def next_nearby_departures_of_station(
    self, station_id: int, time: str, lang: str = "en"
) -> Optional[PublicTransitResponse]:
    """Request a list of next departure times and destinations of a particular station.
    Args:
      lang (str):
        language code for response like `en` Default is `en`.
      station_id (int):
        station id for departures.
      time (str):
        time formattes in yyyy-mm-ddThh:mm:ss.
    Returns:
      PublicTransitResponse
    Raises:
      HEREError
    """

    data = {
        "lang": lang,
        "stnId": station_id,
        "time": time,
        "apikey": self._api_key,
    }
    return self.__get(data, "board.json", "NextDepartures")