Skip to content

Routing API

InvalidCredentialsError

Bases: HEREError

Invalid Credentials Error Type.

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

Source code in herepy/routing_api.py
926
927
928
929
930
931
932
class InvalidCredentialsError(HEREError):

    """Invalid Credentials Error Type.

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

InvalidInputDataError

Bases: HEREError

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.

Source code in herepy/routing_api.py
935
936
937
938
939
940
941
942
class InvalidInputDataError(HEREError):

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

Bases: HEREError

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.

Source code in herepy/routing_api.py
963
964
965
966
967
968
969
class LinkIdNotFoundError(HEREError):

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

Bases: HEREError

No Route Found Error Type.

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

Source code in herepy/routing_api.py
954
955
956
957
958
959
960
class NoRouteFoundError(HEREError):

    """No Route Found Error Type.

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

RouteNotReconstructedError

Bases: HEREError

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.

Source code in herepy/routing_api.py
972
973
974
975
976
977
978
979
980
class RouteNotReconstructedError(HEREError):

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

Bases: HEREApi

A python interface into the HERE Routing API

Source code in herepy/routing_api.py
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 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
 86
 87
 88
 89
 90
 91
 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
117
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
143
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
169
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
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
227
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
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
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
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
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
class RoutingApi(HEREApi):
    """A python interface into the HERE Routing API"""

    URL_CALCULATE_ROUTE = "https://route.ls.hereapi.com/routing/7.2/calculateroute.json"
    URL_CALCULATE_ROUTE_V8 = "https://router.hereapi.com/v8/routes"
    URL_CALCULATE_MATRIX = "https://matrix.router.hereapi.com/v8/matrix"

    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)

    def __get(
        self,
        base_url,
        data,
        key,
        response_cls,
        manipulation_key: str = None,
        keys_for_manipulation: List = None,
    ):
        url = Utils.build_url(base_url, extra_params=data)
        if manipulation_key and keys_for_manipulation:
            for k in keys_for_manipulation:
                url = url.replace(k, manipulation_key)
        response = requests.get(url, timeout=self._timeout)
        json_data = json.loads(response.content.decode("utf8"))
        if response.status_code == requests.codes.OK:
            return response_cls.new_from_jsondict(json_data)
        else:
            raise error_from_routing_service_error(json_data)

    @classmethod
    def __prepare_mode_values(cls, modes):
        mode_values = ""
        for mode in modes:
            mode_values += mode.__str__() + ";"
        mode_values = mode_values[:-1]
        return mode_values

    @classmethod
    def __list_to_waypoint(cls, waypoint_a):
        return str.format("geo!{0},{1}", waypoint_a[0], waypoint_a[1])

    def _route(self, waypoint_a, waypoint_b, modes=None, departure=None, arrival=None):
        if isinstance(waypoint_a, str):
            waypoint_a = self._get_coordinates_for_location_name(waypoint_a)
        if isinstance(waypoint_b, str):
            waypoint_b = self._get_coordinates_for_location_name(waypoint_b)
        data = {
            "waypoint0": self.__list_to_waypoint(waypoint_a),
            "waypoint1": self.__list_to_waypoint(waypoint_b),
            "mode": self.__prepare_mode_values(modes),
            "apikey": self._api_key,
        }
        if departure is not None and arrival is not None:
            raise HEREError("Specify either departure or arrival, not both.")
        if departure is not None:
            departure = self._convert_datetime_to_isoformat(departure)
            data["departure"] = departure
        if arrival is not None:
            arrival = self._convert_datetime_to_isoformat(arrival)
            data["arrival"] = arrival
        response = self.__get(
            self.URL_CALCULATE_ROUTE, data, "response", RoutingResponse
        )
        route = response.response["route"]
        maneuver = route[0]["leg"][0]["maneuver"]

        if any(mode in modes for mode in [RouteMode.car, RouteMode.truck]):
            # Get Route for Car and Truck
            response.route_short = self._get_route_from_vehicle_maneuver(maneuver)
        elif any(
            mode in modes
            for mode in [RouteMode.publicTransport, RouteMode.publicTransportTimeTable]
        ):
            # Get Route for Public Transport
            public_transport_line = route[0]["publicTransportLine"]
            response.route_short = self._get_route_from_public_transport_line(
                public_transport_line
            )
        elif any(mode in modes for mode in [RouteMode.pedestrian, RouteMode.bicycle]):
            # Get Route for Pedestrian and Biyclce
            response.route_short = self._get_route_from_non_vehicle_maneuver(maneuver)
        return response

    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)

    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)

    def pedestrian_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 pedestrian 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)

    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)

    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)

    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)

    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)

    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)

    def route_v8(
        self,
        transport_mode: RoutingTransportMode,
        origin: Union[List[float], str],
        destination: Union[List[float], str],
        via: Optional[List[List[float]]] = None,
        departure_time: Optional[str] = None,
        routing_mode: RoutingMode = RoutingMode.fast,
        alternatives: Optional[int] = None,
        avoid: Optional[Dict[str, List[str]]] = None,
        exclude: Optional[Dict[str, List[str]]] = None,
        units: Optional[RoutingMetric] = None,
        lang: Optional[str] = None,
        return_fields: List[RoutingApiReturnField] = [RoutingApiReturnField.polyline],
        span_fields: Optional[List[RoutingApiSpanField]] = None,
        truck: Optional[Dict[str, List[str]]] = None,
        scooter: Optional[Dict[str, str]] = None,
        headers: Optional[dict] = None,
    ) -> Optional[RoutingResponseV8]:
        """Calculates the route between given origin and destination.
        Args:
          transport_mode (RoutingTransportMode):
            Mode of transport to be used for the calculation of the route.
          origin (Union[List[float], str]):
            List contains latitude and longitude in order
            or string with the location name.
          destination (Union[List[float], str]):
            List contains latitude and longitude in order
            or string with the location name.
          via (Optional[List[List[float]]]):
            Locations defining via waypoints.
            Locations between origin and destination.
          departure_time (Optional[str]):
            Specifies the time of departure as defined by
            either date-time or full-date T partial-time in RFC 3339,
            section 5.6 (for example, 2019-06-24T01:23:45).
          routing_mode (RoutingMode):
            Specifies which optimization is applied during route calculation,
            fast as default value.
          alternatives (Optional[int]):
            Number of alternative routes to return aside from the optimal route.
          avoid (Optional[Dict[str, List[str]]]):
            Avoid routes that violate certain features of road network or
            that go through user-specified geographical bounding boxes.
            Sample use of parameter: `{"features": [controlledAccessHighway, tunnel]}`
          exclude (Optional[Dict[str, List[str]]]):
            Defines properties which will be strictly excluded from route calculation.
            Sample use of parameter:
            `{"countries": [A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code)]}`
          units (Optional[RoutingMetric]):
            Units of measurement used in guidance instructions. The default is metric.
          lang (Optional[str]):
            Default: "en-US"
            Specifies the preferred language of the response.
            The value should comply with the IETF BCP 47.
          return_fields (List[RoutingApiReturnField]):
            Defines which attributes are included in the response as part of data
            representation of a Route or Section.
          span_fields (Optional[List[RoutingApiSpanField]]):
            Defines which attributes are included in the response spans.
            For example, attributes,length will enable the fields attributes and length in the route response.
            This parameter also requires that the polyline option is set within the return parameter.
          truck (Optional[Dict[str, List[str]]]):
            Comma-separated list of shipped hazardous goods in the vehicle.
            Sample use of parameter: `{"shippedHazardousGoods": [explosive, gas, flammable]}`
          scooter (Optional[Dict[str, str]]):
            Scooter specific parameters.
            Sample use of parameter: `{"allowHighway": "true"}`
          headers (Optional[dict]):
            HTTP headers for requests.
            Sample:
            X-Request-ID
            User-provided token that can be used to trace a request or
            a group of requests sent to the service.
        Returns:
          RoutingResponseV8
        Raises:
          HEREError
        """

        if isinstance(origin, str):
            origin = self._get_coordinates_for_location_name(origin)
        if isinstance(destination, str):
            destination = self._get_coordinates_for_location_name(destination)
        data = {
            "transportMode": transport_mode.__str__(),
            "origin": str.format("{0},{1}", origin[0], origin[1]),
            "destination": str.format("{0},{1}", destination[0], destination[1]),
            "apiKey": self._api_key,
        }

        via_keys = []
        if via:
            for i, v in enumerate(via):
                key = str.format("{0}{1}", "via", i)
                via_keys.append(key)
                data[key] = str.format("{0},{1}", v[0], v[1])
        if departure_time:
            data["departureTime"] = departure_time
        data["routingMode"] = routing_mode.__str__()
        if alternatives:
            data["alternatives"] = alternatives
        if avoid:
            key = list(avoid.keys())[0]
            values = list(avoid.values())[0]
            data["avoid"] = {
                key: ",".join(values),
            }
        if exclude:
            key = list(avoid.keys())[0]
            values = list(avoid.values())[0]
            data["exclude"] = {
                key: ",".join(values),
            }
        if units:
            data["units"] = units.__str__()
        if lang:
            data["lang"] = lang
        if return_fields:
            data["return"] = ",".join([field.__str__() for field in return_fields])
        if span_fields:
            data["spans"] = ",".join([field.__str__() for field in span_fields])
        if truck:
            key = list(avoid.keys())[0]
            values = list(avoid.values())[0]
            data["truck"] = {
                key: ",".join(values),
            }
        if scooter:
            data["scooter"] = scooter

        response = self.__get(
            self.URL_CALCULATE_ROUTE_V8,
            data,
            "routes",
            RoutingResponseV8,
            manipulation_key="via",
            keys_for_manipulation=via_keys,
        )
        return response

    def __prepare_matrix_request_body(
        self,
        origins: Union[List[float], str],
        destinations: Union[List[float], str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: Optional[List[float]] = None,
        radius: Optional[int] = None,
        profile: Optional[MatrixRoutingProfile] = None,
        departure: str = None,
        routing_mode: Optional[MatrixRoutingMode] = None,
        transport_mode: Optional[MatrixRoutingTransportMode] = None,
        avoid: Optional[Avoid] = None,
        truck: Optional[Truck] = None,
        matrix_attributes: Optional[List[MatrixSummaryAttribute]] = None,
    ) -> Dict:
        region_definition = {
            "type": matrix_type.__str__(),
        }
        if center:
            region_definition["center"] = {"lat": center[0], "lng": center[1]}
        if radius:
            region_definition["radius"] = radius
        request_body = {"regionDefinition": region_definition}

        if profile:
            request_body["profile"] = profile.__str__()
        if departure:
            request_body["departureTime"] = departure
        if routing_mode:
            request_body["routingMode"] = routing_mode.__str__()
        if transport_mode:
            request_body["transportMode"] = transport_mode.__str__()
        if matrix_attributes:
            request_body["matrixAttributes"] = [
                attribute.__str__() for attribute in matrix_attributes
            ]
        if avoid:
            request_body["avoid"] = {"features": avoid.features, "areas": avoid.areas}
        if truck:
            request_body["truck"] = {
                "shippedHazardousGoods": truck.shipped_hazardous_goods,
                "grossWeight": truck.gross_weight,
                "weightPerAxle": truck.weight_per_axle,
                "height": truck.height,
                "width": truck.width,
                "length": truck.length,
                "tunnelCategory": truck.tunnel_category,
                "axleCount": truck.axle_count,
                "type": truck.truck_type,
                "trailerCount": truck.trailer_count,
            }

        origin_list = []
        for i, origin in enumerate(origins):
            if isinstance(origin, str):
                origin_waypoint = self._get_coordinates_for_location_name(origin)
            else:
                origin_waypoint = origin
            lat_long = {"lat": origin_waypoint[0], "lng": origin_waypoint[1]}
            origin_list.append(lat_long)
        request_body["origins"] = origin_list

        destination_list = []
        for i, destination in enumerate(destinations):
            if isinstance(destination, str):
                destination_waypoint = self._get_coordinates_for_location_name(
                    destination
                )
            else:
                destination_waypoint = destination
            lat_long = {"lat": destination_waypoint[0], "lng": destination_waypoint[1]}
            destination_list.append(lat_long)
        request_body["destinations"] = destination_list

        return request_body

    def sync_matrix(
        self,
        origins: Union[List[float], str],
        destinations: Union[List[float], str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: Optional[List[float]] = None,
        radius: Optional[int] = None,
        profile: Optional[MatrixRoutingProfile] = None,
        departure: str = None,
        routing_mode: Optional[MatrixRoutingMode] = None,
        transport_mode: Optional[MatrixRoutingTransportMode] = None,
        avoid: Optional[Avoid] = None,
        truck: Optional[Truck] = None,
        matrix_attributes: Optional[List[MatrixSummaryAttribute]] = None,
    ) -> Optional[RoutingMatrixResponse]:
        """Sync request a matrix of route summaries between M starts and N destinations.
        Args:
          origins (List):
            List of lists of coordinates [lat,long] of start waypoints.
            or list of string with the location names.
          destinations (List):
            List of lists of coordinates [lat,long] of destination waypoints.
            or list of string with the location names.
          matrix_type (MatrixRoutingType):
            Routing type used in definition of a region in which the matrix will be calculated.
          center (Optional[List]):
            Center of region definition, latitude and longitude.
          radius (Optional[int]):
            Center  of region definition.
          profile (Optional[MatrixRoutingProfile]):
            A profile ID enables the calculation of matrices with routes of arbitrary length.
          departure (str):
            time when travel is expected to start, e.g.: '2013-07-04T17:00:00+02'
          routing_mode (Optional[MatrixRoutingMode]):
            Route mode used in optimization of route calculation.
          transport_mode (Optional[MatrixRoutingTransportMode]):
            Depending on the transport mode special constraints, speed attributes and weights
            are taken into account during route calculation.
          avoid (Optional[Avoid]):
            Avoid routes that violate these properties.
          truck (Optional[Truck]):
            Different truck options to use during route calculation when transportMode = truck.
          matrix_attributes (List):
            List of MatrixSummaryAttribute enums.
        Returns:
          RoutingMatrixResponse
        Raises:
          HEREError: If an error is received from the server.
        """

        query_params = {
            "apiKey": self._api_key,
            "async": "false",
        }

        request_body = self.__prepare_matrix_request_body(
            origins=origins,
            destinations=destinations,
            matrix_type=matrix_type,
            center=center,
            radius=radius,
            profile=profile,
            departure=departure,
            routing_mode=routing_mode,
            transport_mode=transport_mode,
            avoid=avoid,
            truck=truck,
            matrix_attributes=matrix_attributes,
        )

        url = Utils.build_url(self.URL_CALCULATE_MATRIX, extra_params=query_params)
        headers = {"Content-Type": "application/json"}
        response = requests.post(
            url, json=request_body, headers=headers, timeout=self._timeout
        )
        json_data = json.loads(response.content.decode("utf8"))
        if response.status_code == requests.codes.OK:
            if json_data.get("matrix") is not None:
                return RoutingMatrixResponse.new_from_jsondict(json_data)
            else:
                raise HEREError(
                    "Error occurred on routing_api sync_matrix "
                    + sys._getframe(1).f_code.co_name
                    + " response status code "
                    + str(response.status_code)
                )
        else:
            if "title" in json_data and "cause" in json_data:
                raise HEREError(
                    str.format(
                        "routing_api sync_matrix failed! title: {0}, cause: {1}",
                        json_data["title"],
                        json_data["cause"],
                    )
                )
            else:
                raise HEREError(
                    "Error occurred on routing_api sync_matrix "
                    + sys._getframe(1).f_code.co_name
                )

    def __download_file(self, fileurl: str):
        filename = os.path.basename(fileurl)
        with requests.get(fileurl, stream=True) as r:
            r.raise_for_status()
            with open(filename, "wb") as f:
                for chunk in r.iter_content(chunk_size=8192):
                    f.write(chunk)
        print("{} file saved!".format(filename))
        return filename

    def __is_correct_response(self, response):
        status_code = response.status_code
        json_data = response.json()
        if json_data.get("matrix") is not None:
            return json_data
        elif json_data.get("status") is not None:
            print(
                "Matrix {} calculation {}".format(
                    json_data["matrixId"], json_data["status"]
                )
            )
            return False
        elif json_data.get("error") is not None and json_data.get("error_description"):
            raise HEREError(
                "Error occurred on __is_correct_response: "
                + json_data["error"]
                + ", description: "
                + json_data["error_description"]
            )
        elif json_data.get("title") is not None and json_data.get("status"):
            raise HEREError(
                "Error occurred on __is_correct_response: "
                + json_data["title"]
                + ", status: "
                + json_data["status"]
            )

    def async_matrix(
        self,
        token: str,
        origins: Union[List[float], str],
        destinations: Union[List[float], str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: Optional[List[float]] = None,
        radius: Optional[int] = None,
        profile: Optional[MatrixRoutingProfile] = None,
        departure: str = None,
        routing_mode: Optional[MatrixRoutingMode] = None,
        transport_mode: Optional[MatrixRoutingTransportMode] = None,
        avoid: Optional[Avoid] = None,
        truck: Optional[Truck] = None,
        matrix_attributes: Optional[List[MatrixSummaryAttribute]] = None,
    ) -> Optional[RoutingMatrixResponse]:
        """Async request a matrix of route summaries between M starts and N destinations.
        Args:
          token (str):
            Bearer token required for async calls. This is the only working solution for now.
            How to create a bearer token:
            https://developer.here.com/documentation/identity-access-management/dev_guide/topics/sdk.html#step-1-register-your-application
            https://developer.here.com/documentation/identity-access-management/dev_guide/topics/postman.html
          origins (List):
            List of lists of coordinates [lat,long] of start waypoints.
            or list of string with the location names.
          destinations (List):
            List of lists of coordinates [lat,long] of destination waypoints.
            or list of string with the location names.
          matrix_type (MatrixRoutingType):
            Routing type used in definition of a region in which the matrix will be calculated.
          center (Optional[List]):
            Center of region definition, latitude and longitude.
          radius (Optional[int]):
            Center  of region definition.
          profile (Optional[MatrixRoutingProfile]):
            A profile ID enables the calculation of matrices with routes of arbitrary length.
          departure (str):
            time when travel is expected to start, e.g.: '2013-07-04T17:00:00+02'
          routing_mode (Optional[MatrixRoutingMode]):
            Route mode used in optimization of route calculation.
          transport_mode (Optional[MatrixRoutingTransportMode]):
            Depending on the transport mode special constraints, speed attributes and weights
            are taken into account during route calculation.
          avoid (Optional[Avoid]):
            Avoid routes that violate these properties.
          truck (Optional[Truck]):
            Different truck options to use during route calculation when transportMode = truck.
          matrix_attributes (List):
            List of MatrixSummaryAttribute enums.
        Returns:
          RoutingMatrixResponse.
        Raises:
          HEREError: If an error is received from the server.
        """

        query_params = {}

        request_body = self.__prepare_matrix_request_body(
            origins=origins,
            destinations=destinations,
            matrix_type=matrix_type,
            center=center,
            radius=radius,
            profile=profile,
            departure=departure,
            routing_mode=routing_mode,
            transport_mode=transport_mode,
            avoid=avoid,
            truck=truck,
            matrix_attributes=matrix_attributes,
        )

        url = Utils.build_url(self.URL_CALCULATE_MATRIX, extra_params=query_params)
        headers = {
            "Content-Type": "application/json",
            "Authorization": str.format("Bearer {0}", token),
        }
        json_data = json.dumps(request_body)
        response = requests.post(
            url, json=request_body, headers=headers, timeout=self._timeout
        )
        if response.status_code == requests.codes.ACCEPTED:
            json_data = response.json()
            print(
                "Matrix {} calculation {}".format(
                    json_data["matrixId"], json_data["status"]
                )
            )
            poll_url = json_data["statusUrl"]
            headers = {"Authorization": str.format("Bearer {0}", token)}
            print("Polling matrix calculation started!")
            result = polling.poll(
                lambda: requests.get(poll_url, headers=headers),
                check_success=self.__is_correct_response,
                step=5,
                poll_forever=True,
            )
            print("Polling matrix calculation completed!")
            poll_data = result.json()
            return RoutingMatrixResponse.new_from_jsondict(poll_data)
        else:
            json_data = response.json()
            if (
                json_data.get("error") is not None
                and json_data.get("error_description") is not None
            ):
                raise HEREError(
                    "Error occurred on async_matrix: "
                    + json_data["error"]
                    + ", description: "
                    + json_data["error_description"]
                )
            elif (
                json_data.get("title") is not None
                and json_data.get("cause") is not None
            ):
                raise HEREError(
                    "Error occurred on async_matrix: "
                    + json_data["title"]
                    + ", cause: "
                    + json_data["cause"]
                )
            else:
                raise HEREError(
                    "Error occurred on async_matrix " + sys._getframe(1).f_code.co_name
                )

    def _get_coordinates_for_location_name(self, location_name: str) -> List[float]:
        """Use the Geocoder API to resolve a location name to a set of coordinates."""

        geocoder_api = GeocoderApi(self._api_key)
        try:
            geocoder_response = geocoder_api.free_form(location_name)
            coordinates = geocoder_response.items[0]["position"]
            return [coordinates["lat"], coordinates["lng"]]
        except (HEREError) as here_error:
            raise WaypointNotFoundError(here_error.message)

    @staticmethod
    def _convert_datetime_to_isoformat(datetime_object):
        """Convert a datetime.datetime object to an ISO8601 string."""

        if isinstance(datetime_object, datetime.datetime):
            datetime_object = datetime_object.isoformat()
        return datetime_object

    @staticmethod
    def _get_route_from_non_vehicle_maneuver(maneuver):
        """Extract a short route description from the maneuver instructions."""

        road_names = []

        for step in maneuver:
            instruction = step["instruction"]
            try:
                road_name = instruction.split('<span class="next-street">')[1].split(
                    "</span>"
                )[0]
                road_name = road_name.replace("(", "").replace(")", "")

                # Only add if it does not repeat
                if not road_names or road_names[-1] != road_name:
                    road_names.append(road_name)
            except IndexError:
                pass  # No street name found in this maneuver step
        route = "; ".join(list(map(str, road_names)))
        return route

    @staticmethod
    def _get_route_from_public_transport_line(public_transport_line_segment):
        """Extract a short route description from the public transport lines."""

        lines = []
        for line_info in public_transport_line_segment:
            lines.append(line_info["lineName"] + " - " + line_info["destination"])

        route = "; ".join(list(map(str, lines)))
        return route

    @staticmethod
    def _get_route_from_vehicle_maneuver(maneuver):
        """Extract a short route description from the maneuver instructions."""

        road_names = []

        for step in maneuver:
            instruction = step["instruction"]
            try:
                road_number = instruction.split('<span class="number">')[1].split(
                    "</span>"
                )[0]
                road_name = road_number.replace("(", "").replace(")", "")

                try:
                    street_name = instruction.split('<span class="next-street">')[
                        1
                    ].split("</span>")[0]
                    street_name = street_name.replace("(", "").replace(")", "")

                    road_name += " - " + street_name
                except IndexError:
                    pass  # No street name found in this maneuver step

                # Only add if it does not repeat
                if not road_names or road_names[-1] != road_name:
                    road_names.append(road_name)
            except IndexError:
                pass  # No road number found in this maneuver step

        route = "; ".join(list(map(str, road_names)))
        return route

__init__(api_key=None, timeout=None)

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
33
34
35
36
37
38
39
40
41
42
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)

async_matrix(token, origins, destinations, matrix_type=MatrixRoutingType.world, center=None, radius=None, profile=None, departure=None, routing_mode=None, transport_mode=None, avoid=None, truck=None, matrix_attributes=None)

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

Parameters:

Name Type Description Default
token str

Bearer token required for async calls. This is the only working solution for now. How to create a bearer token: https://developer.here.com/documentation/identity-access-management/dev_guide/topics/sdk.html#step-1-register-your-application https://developer.here.com/documentation/identity-access-management/dev_guide/topics/postman.html

required
origins List

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

required
destinations List

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

required
matrix_type MatrixRoutingType

Routing type used in definition of a region in which the matrix will be calculated.

MatrixRoutingType.world
center Optional[List]

Center of region definition, latitude and longitude.

None
radius Optional[int]

Center of region definition.

None
profile Optional[MatrixRoutingProfile]

A profile ID enables the calculation of matrices with routes of arbitrary length.

None
departure str

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

None
routing_mode Optional[MatrixRoutingMode]

Route mode used in optimization of route calculation.

None
transport_mode Optional[MatrixRoutingTransportMode]

Depending on the transport mode special constraints, speed attributes and weights are taken into account during route calculation.

None
avoid Optional[Avoid]

Avoid routes that violate these properties.

None
truck Optional[Truck]

Different truck options to use during route calculation when transportMode = truck.

None
matrix_attributes List

List of MatrixSummaryAttribute enums.

None

Returns:

Type Description
Optional[RoutingMatrixResponse]

RoutingMatrixResponse.

Raises:

Type Description
HEREError

If an error is received from the server.

Source code in herepy/routing_api.py
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
def async_matrix(
    self,
    token: str,
    origins: Union[List[float], str],
    destinations: Union[List[float], str],
    matrix_type: MatrixRoutingType = MatrixRoutingType.world,
    center: Optional[List[float]] = None,
    radius: Optional[int] = None,
    profile: Optional[MatrixRoutingProfile] = None,
    departure: str = None,
    routing_mode: Optional[MatrixRoutingMode] = None,
    transport_mode: Optional[MatrixRoutingTransportMode] = None,
    avoid: Optional[Avoid] = None,
    truck: Optional[Truck] = None,
    matrix_attributes: Optional[List[MatrixSummaryAttribute]] = None,
) -> Optional[RoutingMatrixResponse]:
    """Async request a matrix of route summaries between M starts and N destinations.
    Args:
      token (str):
        Bearer token required for async calls. This is the only working solution for now.
        How to create a bearer token:
        https://developer.here.com/documentation/identity-access-management/dev_guide/topics/sdk.html#step-1-register-your-application
        https://developer.here.com/documentation/identity-access-management/dev_guide/topics/postman.html
      origins (List):
        List of lists of coordinates [lat,long] of start waypoints.
        or list of string with the location names.
      destinations (List):
        List of lists of coordinates [lat,long] of destination waypoints.
        or list of string with the location names.
      matrix_type (MatrixRoutingType):
        Routing type used in definition of a region in which the matrix will be calculated.
      center (Optional[List]):
        Center of region definition, latitude and longitude.
      radius (Optional[int]):
        Center  of region definition.
      profile (Optional[MatrixRoutingProfile]):
        A profile ID enables the calculation of matrices with routes of arbitrary length.
      departure (str):
        time when travel is expected to start, e.g.: '2013-07-04T17:00:00+02'
      routing_mode (Optional[MatrixRoutingMode]):
        Route mode used in optimization of route calculation.
      transport_mode (Optional[MatrixRoutingTransportMode]):
        Depending on the transport mode special constraints, speed attributes and weights
        are taken into account during route calculation.
      avoid (Optional[Avoid]):
        Avoid routes that violate these properties.
      truck (Optional[Truck]):
        Different truck options to use during route calculation when transportMode = truck.
      matrix_attributes (List):
        List of MatrixSummaryAttribute enums.
    Returns:
      RoutingMatrixResponse.
    Raises:
      HEREError: If an error is received from the server.
    """

    query_params = {}

    request_body = self.__prepare_matrix_request_body(
        origins=origins,
        destinations=destinations,
        matrix_type=matrix_type,
        center=center,
        radius=radius,
        profile=profile,
        departure=departure,
        routing_mode=routing_mode,
        transport_mode=transport_mode,
        avoid=avoid,
        truck=truck,
        matrix_attributes=matrix_attributes,
    )

    url = Utils.build_url(self.URL_CALCULATE_MATRIX, extra_params=query_params)
    headers = {
        "Content-Type": "application/json",
        "Authorization": str.format("Bearer {0}", token),
    }
    json_data = json.dumps(request_body)
    response = requests.post(
        url, json=request_body, headers=headers, timeout=self._timeout
    )
    if response.status_code == requests.codes.ACCEPTED:
        json_data = response.json()
        print(
            "Matrix {} calculation {}".format(
                json_data["matrixId"], json_data["status"]
            )
        )
        poll_url = json_data["statusUrl"]
        headers = {"Authorization": str.format("Bearer {0}", token)}
        print("Polling matrix calculation started!")
        result = polling.poll(
            lambda: requests.get(poll_url, headers=headers),
            check_success=self.__is_correct_response,
            step=5,
            poll_forever=True,
        )
        print("Polling matrix calculation completed!")
        poll_data = result.json()
        return RoutingMatrixResponse.new_from_jsondict(poll_data)
    else:
        json_data = response.json()
        if (
            json_data.get("error") is not None
            and json_data.get("error_description") is not None
        ):
            raise HEREError(
                "Error occurred on async_matrix: "
                + json_data["error"]
                + ", description: "
                + json_data["error_description"]
            )
        elif (
            json_data.get("title") is not None
            and json_data.get("cause") is not None
        ):
            raise HEREError(
                "Error occurred on async_matrix: "
                + json_data["title"]
                + ", cause: "
                + json_data["cause"]
            )
        else:
            raise HEREError(
                "Error occurred on async_matrix " + sys._getframe(1).f_code.co_name
            )

bicycle_route(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

List contains RouteMode enums.

None
departure str

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

'now'

Returns:

Type Description
Optional[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
143
144
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(waypoint_a, waypoint_b, modes=None, departure='now')

Request a driving route between two points

Parameters:

Name Type Description Default
waypoint_a List

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

required
waypoint_b List

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

required
modes List

List contains RouteMode enums.

None
departure str

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

'now'

Returns:

Type Description
Optional[RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
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(waypoint_a, waypoint_b, waypoint_c, modes=None, departure='now')

Request a intermediate route from three points

Parameters:

Name Type Description Default
waypoint_a List

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

required
waypoint_b List

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

required
waypoint_c List

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

required
modes List

List contains RouteMode enums.

None
departure str

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

'now'

Returns:

Type Description
Optional[RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
229
230
231
232
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(waypoint_a, waypoint_b, modes=None, departure='now')

Calculates the fastest car route between two location

Parameters:

Name Type Description Default
waypoint_a List

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

required
waypoint_b List

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

required
modes List

List contains RouteMode enums.

None
departure str

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

'now'

Returns:

Type Description
Optional[RoutingResponse]

RoutingResponse

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

pedestrian_route(waypoint_a, waypoint_b, modes=None, departure='now')

Request a pedestrian route between two points

Parameters:

Name Type Description Default
waypoint_a List

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

required
waypoint_b List

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

required
modes List

List contains RouteMode enums.

None
departure str

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

'now'

Returns:

Type Description
Optional[RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
199
200
def pedestrian_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 pedestrian 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(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 List

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

required
waypoint_b List

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

List contains RouteMode enums.

None
departure str

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

'now'

Returns:

Type Description
Optional[RoutingResponse]

RoutingResponse

Source code in herepy/routing_api.py
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
263
264
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(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 List

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

required
waypoint_b List

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

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[RoutingResponse]

RoutingResponse

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

route_v8(transport_mode, origin, destination, via=None, departure_time=None, routing_mode=RoutingMode.fast, alternatives=None, avoid=None, exclude=None, units=None, lang=None, return_fields=[RoutingApiReturnField.polyline], span_fields=None, truck=None, scooter=None, headers=None)

Calculates the route between given origin and destination.

Parameters:

Name Type Description Default
transport_mode RoutingTransportMode

Mode of transport to be used for the calculation of the route.

required
origin Union[List[float], str]

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

required
destination Union[List[float], str]

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

required
via Optional[List[List[float]]]

Locations defining via waypoints. Locations between origin and destination.

None
departure_time Optional[str]

Specifies the time of departure as defined by either date-time or full-date T partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45).

None
routing_mode RoutingMode

Specifies which optimization is applied during route calculation, fast as default value.

RoutingMode.fast
alternatives Optional[int]

Number of alternative routes to return aside from the optimal route.

None
avoid Optional[Dict[str, List[str]]]

Avoid routes that violate certain features of road network or that go through user-specified geographical bounding boxes. Sample use of parameter: {"features": [controlledAccessHighway, tunnel]}

None
exclude Optional[Dict[str, List[str]]]

Defines properties which will be strictly excluded from route calculation. Sample use of parameter: {"countries": [A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code)]}

None
units Optional[RoutingMetric]

Units of measurement used in guidance instructions. The default is metric.

None
lang Optional[str]

Default: "en-US" Specifies the preferred language of the response. The value should comply with the IETF BCP 47.

None
return_fields List[RoutingApiReturnField]

Defines which attributes are included in the response as part of data representation of a Route or Section.

[RoutingApiReturnField.polyline]
span_fields Optional[List[RoutingApiSpanField]]

Defines which attributes are included in the response spans. For example, attributes,length will enable the fields attributes and length in the route response. This parameter also requires that the polyline option is set within the return parameter.

None
truck Optional[Dict[str, List[str]]]

Comma-separated list of shipped hazardous goods in the vehicle. Sample use of parameter: {"shippedHazardousGoods": [explosive, gas, flammable]}

None
scooter Optional[Dict[str, str]]

Scooter specific parameters. Sample use of parameter: {"allowHighway": "true"}

None
headers Optional[dict]

HTTP headers for requests. Sample: X-Request-ID User-provided token that can be used to trace a request or a group of requests sent to the service.

None

Returns:

Type Description
Optional[RoutingResponseV8]

RoutingResponseV8

Source code in herepy/routing_api.py
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
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
def route_v8(
    self,
    transport_mode: RoutingTransportMode,
    origin: Union[List[float], str],
    destination: Union[List[float], str],
    via: Optional[List[List[float]]] = None,
    departure_time: Optional[str] = None,
    routing_mode: RoutingMode = RoutingMode.fast,
    alternatives: Optional[int] = None,
    avoid: Optional[Dict[str, List[str]]] = None,
    exclude: Optional[Dict[str, List[str]]] = None,
    units: Optional[RoutingMetric] = None,
    lang: Optional[str] = None,
    return_fields: List[RoutingApiReturnField] = [RoutingApiReturnField.polyline],
    span_fields: Optional[List[RoutingApiSpanField]] = None,
    truck: Optional[Dict[str, List[str]]] = None,
    scooter: Optional[Dict[str, str]] = None,
    headers: Optional[dict] = None,
) -> Optional[RoutingResponseV8]:
    """Calculates the route between given origin and destination.
    Args:
      transport_mode (RoutingTransportMode):
        Mode of transport to be used for the calculation of the route.
      origin (Union[List[float], str]):
        List contains latitude and longitude in order
        or string with the location name.
      destination (Union[List[float], str]):
        List contains latitude and longitude in order
        or string with the location name.
      via (Optional[List[List[float]]]):
        Locations defining via waypoints.
        Locations between origin and destination.
      departure_time (Optional[str]):
        Specifies the time of departure as defined by
        either date-time or full-date T partial-time in RFC 3339,
        section 5.6 (for example, 2019-06-24T01:23:45).
      routing_mode (RoutingMode):
        Specifies which optimization is applied during route calculation,
        fast as default value.
      alternatives (Optional[int]):
        Number of alternative routes to return aside from the optimal route.
      avoid (Optional[Dict[str, List[str]]]):
        Avoid routes that violate certain features of road network or
        that go through user-specified geographical bounding boxes.
        Sample use of parameter: `{"features": [controlledAccessHighway, tunnel]}`
      exclude (Optional[Dict[str, List[str]]]):
        Defines properties which will be strictly excluded from route calculation.
        Sample use of parameter:
        `{"countries": [A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code)]}`
      units (Optional[RoutingMetric]):
        Units of measurement used in guidance instructions. The default is metric.
      lang (Optional[str]):
        Default: "en-US"
        Specifies the preferred language of the response.
        The value should comply with the IETF BCP 47.
      return_fields (List[RoutingApiReturnField]):
        Defines which attributes are included in the response as part of data
        representation of a Route or Section.
      span_fields (Optional[List[RoutingApiSpanField]]):
        Defines which attributes are included in the response spans.
        For example, attributes,length will enable the fields attributes and length in the route response.
        This parameter also requires that the polyline option is set within the return parameter.
      truck (Optional[Dict[str, List[str]]]):
        Comma-separated list of shipped hazardous goods in the vehicle.
        Sample use of parameter: `{"shippedHazardousGoods": [explosive, gas, flammable]}`
      scooter (Optional[Dict[str, str]]):
        Scooter specific parameters.
        Sample use of parameter: `{"allowHighway": "true"}`
      headers (Optional[dict]):
        HTTP headers for requests.
        Sample:
        X-Request-ID
        User-provided token that can be used to trace a request or
        a group of requests sent to the service.
    Returns:
      RoutingResponseV8
    Raises:
      HEREError
    """

    if isinstance(origin, str):
        origin = self._get_coordinates_for_location_name(origin)
    if isinstance(destination, str):
        destination = self._get_coordinates_for_location_name(destination)
    data = {
        "transportMode": transport_mode.__str__(),
        "origin": str.format("{0},{1}", origin[0], origin[1]),
        "destination": str.format("{0},{1}", destination[0], destination[1]),
        "apiKey": self._api_key,
    }

    via_keys = []
    if via:
        for i, v in enumerate(via):
            key = str.format("{0}{1}", "via", i)
            via_keys.append(key)
            data[key] = str.format("{0},{1}", v[0], v[1])
    if departure_time:
        data["departureTime"] = departure_time
    data["routingMode"] = routing_mode.__str__()
    if alternatives:
        data["alternatives"] = alternatives
    if avoid:
        key = list(avoid.keys())[0]
        values = list(avoid.values())[0]
        data["avoid"] = {
            key: ",".join(values),
        }
    if exclude:
        key = list(avoid.keys())[0]
        values = list(avoid.values())[0]
        data["exclude"] = {
            key: ",".join(values),
        }
    if units:
        data["units"] = units.__str__()
    if lang:
        data["lang"] = lang
    if return_fields:
        data["return"] = ",".join([field.__str__() for field in return_fields])
    if span_fields:
        data["spans"] = ",".join([field.__str__() for field in span_fields])
    if truck:
        key = list(avoid.keys())[0]
        values = list(avoid.values())[0]
        data["truck"] = {
            key: ",".join(values),
        }
    if scooter:
        data["scooter"] = scooter

    response = self.__get(
        self.URL_CALCULATE_ROUTE_V8,
        data,
        "routes",
        RoutingResponseV8,
        manipulation_key="via",
        keys_for_manipulation=via_keys,
    )
    return response

sync_matrix(origins, destinations, matrix_type=MatrixRoutingType.world, center=None, radius=None, profile=None, departure=None, routing_mode=None, transport_mode=None, avoid=None, truck=None, matrix_attributes=None)

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

Parameters:

Name Type Description Default
origins List

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

required
destinations List

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

required
matrix_type MatrixRoutingType

Routing type used in definition of a region in which the matrix will be calculated.

MatrixRoutingType.world
center Optional[List]

Center of region definition, latitude and longitude.

None
radius Optional[int]

Center of region definition.

None
profile Optional[MatrixRoutingProfile]

A profile ID enables the calculation of matrices with routes of arbitrary length.

None
departure str

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

None
routing_mode Optional[MatrixRoutingMode]

Route mode used in optimization of route calculation.

None
transport_mode Optional[MatrixRoutingTransportMode]

Depending on the transport mode special constraints, speed attributes and weights are taken into account during route calculation.

None
avoid Optional[Avoid]

Avoid routes that violate these properties.

None
truck Optional[Truck]

Different truck options to use during route calculation when transportMode = truck.

None
matrix_attributes List

List of MatrixSummaryAttribute enums.

None

Returns:

Type Description
Optional[RoutingMatrixResponse]

RoutingMatrixResponse

Raises:

Type Description
HEREError

If an error is received from the server.

Source code in herepy/routing_api.py
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
def sync_matrix(
    self,
    origins: Union[List[float], str],
    destinations: Union[List[float], str],
    matrix_type: MatrixRoutingType = MatrixRoutingType.world,
    center: Optional[List[float]] = None,
    radius: Optional[int] = None,
    profile: Optional[MatrixRoutingProfile] = None,
    departure: str = None,
    routing_mode: Optional[MatrixRoutingMode] = None,
    transport_mode: Optional[MatrixRoutingTransportMode] = None,
    avoid: Optional[Avoid] = None,
    truck: Optional[Truck] = None,
    matrix_attributes: Optional[List[MatrixSummaryAttribute]] = None,
) -> Optional[RoutingMatrixResponse]:
    """Sync request a matrix of route summaries between M starts and N destinations.
    Args:
      origins (List):
        List of lists of coordinates [lat,long] of start waypoints.
        or list of string with the location names.
      destinations (List):
        List of lists of coordinates [lat,long] of destination waypoints.
        or list of string with the location names.
      matrix_type (MatrixRoutingType):
        Routing type used in definition of a region in which the matrix will be calculated.
      center (Optional[List]):
        Center of region definition, latitude and longitude.
      radius (Optional[int]):
        Center  of region definition.
      profile (Optional[MatrixRoutingProfile]):
        A profile ID enables the calculation of matrices with routes of arbitrary length.
      departure (str):
        time when travel is expected to start, e.g.: '2013-07-04T17:00:00+02'
      routing_mode (Optional[MatrixRoutingMode]):
        Route mode used in optimization of route calculation.
      transport_mode (Optional[MatrixRoutingTransportMode]):
        Depending on the transport mode special constraints, speed attributes and weights
        are taken into account during route calculation.
      avoid (Optional[Avoid]):
        Avoid routes that violate these properties.
      truck (Optional[Truck]):
        Different truck options to use during route calculation when transportMode = truck.
      matrix_attributes (List):
        List of MatrixSummaryAttribute enums.
    Returns:
      RoutingMatrixResponse
    Raises:
      HEREError: If an error is received from the server.
    """

    query_params = {
        "apiKey": self._api_key,
        "async": "false",
    }

    request_body = self.__prepare_matrix_request_body(
        origins=origins,
        destinations=destinations,
        matrix_type=matrix_type,
        center=center,
        radius=radius,
        profile=profile,
        departure=departure,
        routing_mode=routing_mode,
        transport_mode=transport_mode,
        avoid=avoid,
        truck=truck,
        matrix_attributes=matrix_attributes,
    )

    url = Utils.build_url(self.URL_CALCULATE_MATRIX, extra_params=query_params)
    headers = {"Content-Type": "application/json"}
    response = requests.post(
        url, json=request_body, headers=headers, timeout=self._timeout
    )
    json_data = json.loads(response.content.decode("utf8"))
    if response.status_code == requests.codes.OK:
        if json_data.get("matrix") is not None:
            return RoutingMatrixResponse.new_from_jsondict(json_data)
        else:
            raise HEREError(
                "Error occurred on routing_api sync_matrix "
                + sys._getframe(1).f_code.co_name
                + " response status code "
                + str(response.status_code)
            )
    else:
        if "title" in json_data and "cause" in json_data:
            raise HEREError(
                str.format(
                    "routing_api sync_matrix failed! title: {0}, cause: {1}",
                    json_data["title"],
                    json_data["cause"],
                )
            )
        else:
            raise HEREError(
                "Error occurred on routing_api sync_matrix "
                + sys._getframe(1).f_code.co_name
            )

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

Calculates the fastest truck route between two location

Parameters:

Name Type Description Default
waypoint_a List

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

required
waypoint_b List

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

required
modes List

List contains RouteMode enums.

None
departure str

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

'now'

Returns:

Type Description
Optional[RoutingResponse]

RoutingResponse

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

Bases: HEREError

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.

Source code in herepy/routing_api.py
945
946
947
948
949
950
951
class WaypointNotFoundError(HEREError):

    """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
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
def error_from_routing_service_error(json_data):
    """Return the correct subclass for routing errors"""

    # V8 error handling
    if "error" in json_data and json_data["error"] == "Unauthorized":
        return InvalidCredentialsError(json_data["error_description"])
    elif "status" in json_data:
        error_msg = str.format(
            "Cause: {0}; Action: {1}", json_data["cause"], json_data["action"]
        )
        if json_data["status"] == 400:
            return InvalidRequestError(error_msg)
        elif json_data["status"] == 403:
            return AccessDeniedError(error_msg)

    # V7 error handling
    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 occurred on " + sys._getframe(1).f_code.co_name)