Skip to content

Routing API

InvalidCredentialsError

Invalid Credentials Error Type.

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

InvalidInputDataError

Invalid Input Data Error Type.

This error is returned if the specified request parameters contain invalid
data, such as due to wrong parameter syntax or invalid parameter
combinations.

LinkIdNotFoundError

Link Not Found Error Type.

This error indicates that a link ID passed as input parameter could not be
found in the underlying map data.

NoRouteFoundError

No Route Found Error Type.

This error indicates that no route could be constructed based on the input
parameter.

RouteNotReconstructedError

Route Not Reconstructed Error Type.

This error indicates that the RouteId is invalid (RouteId can not be
decoded into valid data) or route failed to be reconstructed from the
RouteId. In every case a mitigation is to re-run CalculateRoute request to
acquire a new proper RouteId.

RoutingApi

A python interface into the HERE Routing API

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

Returns a RoutingApi 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/routing_api.py
25
26
27
28
29
30
31
32
33
34
def __init__(self, api_key: str = None, timeout: int = None):
    """Returns a RoutingApi instance.
    Args:
      api_key (str):
        API key taken from HERE Developer Portal.
      timeout (int):
        Timeout limit for requests.
    """

    super(RoutingApi, self).__init__(api_key, timeout)

bicycle_route(self, waypoint_a, waypoint_b, modes=None, departure='now')

Request a bicycle route between two points

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

List contains latitude and longitude in order or string with the location name

required
waypoint_b Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default now.

'now'

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
 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
def bicycle_route(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    modes: List[RouteMode] = None,
    departure: str = "now",
) -> Optional[RoutingResponse]:
    """Request a bicycle route between two points
    Args:
      waypoint_a:
        List contains latitude and longitude in order
        or string with the location name
      waypoint_b:
        List contains latitude and longitude in order
        or string with the location name.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `now`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.bicycle, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure)

car_route(self, waypoint_a, waypoint_b, modes=None, departure='now')

Request a driving route between two points

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default now.

'now'

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
def car_route(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    modes: List[RouteMode] = None,
    departure: str = "now",
) -> Optional[RoutingResponse]:
    """Request a driving route between two points
    Args:
      waypoint_a (List):
        List contains latitude and longitude in order
        or string with the location name.
      waypoint_b (List):
        List contains latitude and longitude in order
        or string with the location name.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `now`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.car, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure)

intermediate_route(self, waypoint_a, waypoint_b, waypoint_c, modes=None, departure='now')

Request a intermediate route from three points

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

Starting List contains latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

Intermediate List contains latitude and longitude in order or string with the location name.

required
waypoint_c Union[List[float], str]

Last List contains latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default now.

'now'

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
def intermediate_route(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    waypoint_c: Union[List[float], str],
    modes: List[RouteMode] = None,
    departure: str = "now",
) -> Optional[RoutingResponse]:
    """Request a intermediate route from three points
    Args:
      waypoint_a (List):
        Starting List contains latitude and longitude in order
        or string with the location name.
      waypoint_b (List):
        Intermediate List contains latitude and longitude in order
        or string with the location name.
      waypoint_c (List):
        Last List contains latitude and longitude in order
        or string with the location name.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `now`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.car, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure)

location_near_motorway(self, waypoint_a, waypoint_b, modes=None, departure='now')

Calculates the fastest car route between two location

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default now.

'now'

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
def location_near_motorway(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    modes: List[RouteMode] = None,
    departure: str = "now",
) -> Optional[RoutingResponse]:
    """Calculates the fastest car route between two location
    Args:
      waypoint_a (List):
        List contains latitude and longitude in order
        or string with the location name.
      waypoint_b (List):
        List contains latitude and longitude in order
        or string with the location name.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `now`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.car, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure)

matrix(self, start_waypoints, destination_waypoints, departure='now', modes=[], summary_attributes=[])

Request a matrix of route summaries between M starts and N destinations.

Parameters:

Name Type Description Default
start_waypoints Union[List[float], str]

List of lists of coordinates [lat,long] of start waypoints. or list of string with the location names.

required
destination_waypoints Union[List[float], str]

List of lists of coordinates [lat,long] of destination waypoints. or list of string with the location names.

required
departure str

time when travel is expected to start, e.g.: '2013-07-04T17:00:00+02'

'now'
modes List[herepy.here_enum.RouteMode]

List of RouteMode enums following [Type, TransportMode, TrafficMode, Feature].

[]
summary_attributes List[herepy.here_enum.MatrixSummaryAttribute]

List of MatrixSummaryAttribute enums.

[]

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingMatrixResponse

Exceptions:

Type Description
HEREError

If an error is received from the server.

Source code in herepy/routing_api.py
336
337
338
339
340
341
342
343
344
345
346
347
348
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
def matrix(
    self,
    start_waypoints: Union[List[float], str],
    destination_waypoints: Union[List[float], str],
    departure: str = "now",
    modes: List[RouteMode] = [],
    summary_attributes: List[MatrixSummaryAttribute] = [],
) -> Optional[RoutingResponse]:
    """Request a matrix of route summaries between M starts and N destinations.
    Args:
      start_waypoints (List):
        List of lists of coordinates [lat,long] of start waypoints.
        or list of string with the location names.
      destination_waypoints (List):
        List of lists of coordinates [lat,long] of destination waypoints.
        or list of string with the location names.
      departure (str):
        time when travel is expected to start, e.g.: '2013-07-04T17:00:00+02'
      modes (List):
        List of RouteMode enums following [Type, TransportMode, TrafficMode, Feature].
      summary_attributes (List):
        List of MatrixSummaryAttribute enums.
    Returns:
      RoutingMatrixResponse
    Raises:
      HEREError: If an error is received from the server.
    """

    data = {
        "apikey": self._api_key,
        "departure": departure,
        "mode": self.__prepare_mode_values(modes),
        "summaryAttributes": ",".join(
            [attribute.__str__() for attribute in summary_attributes]
        ),
    }
    for i, start_waypoint in enumerate(start_waypoints):
        if isinstance(start_waypoint, str):
            start_waypoint = self._get_coordinates_for_location_name(start_waypoint)
        data["start" + str(i)] = self.__list_to_waypoint(start_waypoint)
    for i, destination_waypoint in enumerate(destination_waypoints):
        if isinstance(destination_waypoint, str):
            destination_waypoint = self._get_coordinates_for_location_name(
                destination_waypoint
            )
        data["destination" + str(i)] = self.__list_to_waypoint(destination_waypoint)
    response = self.__get(self.URL_CALCULATE_MATRIX, data, RoutingMatrixResponse)
    return response

pedastrian_route(self, waypoint_a, waypoint_b, modes=None, departure='now')

Request a pedastrian route between two points

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default now.

'now'

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
def pedastrian_route(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    modes: List[RouteMode] = None,
    departure: str = "now",
) -> Optional[RoutingResponse]:
    """Request a pedastrian route between two points
    Args:
      waypoint_a (List):
        List contains latitude and longitude in order
        or string with the location name.
      waypoint_b (List):
        List contains latitude and longitude in order
        or string with the location name.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `now`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.pedestrian, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure)

public_transport(self, waypoint_a, waypoint_b, combine_change, modes=None, departure='now')

Request a public transport route between two points

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

Starting List contains latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

Intermediate List contains latitude and longitude in order or string with the location name.

required
combine_change bool

Enables the change manuever in the route response, which indicates a public transit line change.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default now.

'now'

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
def public_transport(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    combine_change: bool,
    modes: List[RouteMode] = None,
    departure="now",
) -> Optional[RoutingResponse]:
    """Request a public transport route between two points
    Args:
      waypoint_a (List):
        Starting List contains latitude and longitude in order
        or string with the location name.
      waypoint_b (List):
        Intermediate List contains latitude and longitude in order
        or string with the location name.
      combine_change (bool):
        Enables the change manuever in the route response, which
        indicates a public transit line change.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `now`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.publicTransport, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure)

public_transport_timetable(self, waypoint_a, waypoint_b, combine_change, modes=None, departure=None, arrival=None)

Request a public transport route between two points based on timetables

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

Starting List contains latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

Intermediate List contains latitude and longitude in order or string with the location name.

required
combine_change bool

Enables the change manuever in the route response, which indicates a public transit line change.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default None.

None
arrival str

Date time str in format yyyy-mm-ddThh:mm:ss. Default None.

None

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
def public_transport_timetable(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    combine_change: bool,
    modes: List[RouteMode] = None,
    departure: str = None,
    arrival: str = None,
) -> Optional[RoutingResponse]:
    """Request a public transport route between two points based on timetables
    Args:
      waypoint_a (List):
        Starting List contains latitude and longitude in order
        or string with the location name.
      waypoint_b (List):
        Intermediate List contains latitude and longitude in order
        or string with the location name.
      combine_change (bool):
        Enables the change manuever in the route response, which
        indicates a public transit line change.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `None`.
      arrival (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `None`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.publicTransportTimeTable, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure, arrival)

truck_route(self, waypoint_a, waypoint_b, modes=None, departure='now')

Calculates the fastest truck route between two location

Parameters:

Name Type Description Default
waypoint_a Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

List contains latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

List contains RouteMode enums.

None
departure str

Date time str in format yyyy-mm-ddThh:mm:ss. Default now.

'now'

Returns:

Type Description
Optional[herepy.models.RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
def truck_route(
    self,
    waypoint_a: Union[List[float], str],
    waypoint_b: Union[List[float], str],
    modes: List[RouteMode] = None,
    departure: str = "now",
) -> Optional[RoutingResponse]:
    """Calculates the fastest truck route between two location
    Args:
      waypoint_a (List):
        List contains latitude and longitude in order
        or string with the location name.
      waypoint_b (List):
        List contains latitude and longitude in order
        or string with the location name.
      modes (List):
        List contains RouteMode enums.
      departure (str):
        Date time str in format `yyyy-mm-ddThh:mm:ss`. Default `now`.
    Returns:
      RoutingResponse
    Raises:
      HEREError"""

    if modes is None:
        modes = [RouteMode.truck, RouteMode.fastest]
    return self._route(waypoint_a, waypoint_b, modes, departure)

WaypointNotFoundError

Waypoint not found Error Type.

This error indicates that one of the requested waypoints
(start/end or via point) could not be found in the routing network.

error_from_routing_service_error(json_data)

Return the correct subclass for routing errors

Source code in herepy/routing_api.py
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
def error_from_routing_service_error(json_data):
    """Return the correct subclass for routing errors"""

    if "error" in json_data:
        if json_data["error"] == "Unauthorized":
            return InvalidCredentialsError(json_data["error_description"])

    if "subtype" in json_data:
        subtype = json_data["subtype"]
        details = json_data["details"]

        if subtype == "InvalidInputData":
            return InvalidInputDataError(details)
        if subtype == "WaypointNotFound":
            return WaypointNotFoundError(details)
        if subtype == "NoRouteFound":
            return NoRouteFoundError(details)
        if subtype == "LinkIdNotFound":
            return LinkIdNotFoundError(details)
        if subtype == "RouteNotReconstructed":
            return RouteNotReconstructedError(details)
    # pylint: disable=W0212
    return HEREError("Error occured on " + sys._getframe(1).f_code.co_name)