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
23
24
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]

array including latitude and longitude in order or string with the location name

required
waypoint_b Union[List[float], str]

array including latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

array including 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
 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
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:
        array including latitude and longitude in order
        or string with the location name
      waypoint_b:
        array including latitude and longitude in order
        or string with the location name.
      modes (array):
        array including 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]

array including latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

array including latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

array including 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
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
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 (array):
        array including latitude and longitude in order
        or string with the location name.
      waypoint_b (array):
        array including latitude and longitude in order
        or string with the location name.
      modes (array):
        array including 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 array including latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

Intermediate array including latitude and longitude in order or string with the location name.

required
waypoint_c Union[List[float], str]

Last array including latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

array including 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
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
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 (array):
        Starting array including latitude and longitude in order
        or string with the location name.
      waypoint_b (array):
        Intermediate array including latitude and longitude in order
        or string with the location name.
      waypoint_c (array):
        Last array including latitude and longitude in order
        or string with the location name.
      modes (array):
        array including 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]

array including latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

array including latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

array including 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
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
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 (array):
        array including latitude and longitude in order
        or string with the location name.
      waypoint_b (array):
        array including latitude and longitude in order
        or string with the location name.
      modes (array):
        array including 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]

array of arrays of coordinates [lat,long] of start waypoints. or array of string with the location names.

required
destination_waypoints Union[List[float], str]

array of arrays of coordinates [lat,long] of destination waypoints. or array 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]

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

[]
summary_attributes List[herepy.here_enum.MatrixSummaryAttribute]

array 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
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
348
349
350
351
352
353
354
355
356
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 (array):
        array of arrays of coordinates [lat,long] of start waypoints.
        or array of string with the location names.
      destination_waypoints (array):
        array of arrays of coordinates [lat,long] of destination waypoints.
        or array of string with the location names.
      departure (str):
        time when travel is expected to start, e.g.: '2013-07-04T17:00:00+02'
      modes (array):
        array of RouteMode enums following [Type, TransportMode, TrafficMode, Feature].
      summary_attributes (array):
        array 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.__array_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.__array_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]

array including latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

array including latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

array including 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
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
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 (array):
        array including latitude and longitude in order
        or string with the location name.
      waypoint_b (array):
        array including latitude and longitude in order
        or string with the location name.
      modes (array):
        array including 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 array including latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

Intermediate array including 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]

array including 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
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
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 (array):
        Starting array including latitude and longitude in order
        or string with the location name.
      waypoint_b (array):
        Intermediate array including 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 (array):
        array including 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 array including latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

Intermediate array including 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]

array including 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
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
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 (array):
        Starting array including latitude and longitude in order
        or string with the location name.
      waypoint_b (array):
        Intermediate array including 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 (array):
        array including 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]

array including latitude and longitude in order or string with the location name.

required
waypoint_b Union[List[float], str]

array including latitude and longitude in order or string with the location name.

required
modes List[herepy.here_enum.RouteMode]

array including 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
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
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 (array):
        array including latitude and longitude in order
        or string with the location name.
      waypoint_b (array):
        array including latitude and longitude in order
        or string with the location name.
      modes (array):
        array including 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
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
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)