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
22
23
24
25
26
27
28
29
30
31
32
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
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
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
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
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
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
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
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
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
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
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
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
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
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
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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
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")