Routing API

Client for the HERE 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 src/herepy/routing_api.py

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 src/herepy/routing_api.py

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 src/herepy/routing_api.py

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 src/herepy/routing_api.py

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 src/herepy/routing_api.py

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 src/herepy/routing_api.py

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):
        """
        Initialize the Routing API client.

        Args:
          api_key (str):
            API key taken from HERE Developer Portal.
          timeout (int):
            Timeout limit for requests.

        """
        super().__init__(api_key, timeout)

    def __get(
        self,
        base_url,
        data,
        key,
        response_cls,
        manipulation_key: str = None,
        keys_for_manipulation: list = None,
        headers: dict[str, str] | None = 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, headers=headers)
        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: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        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: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        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: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        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: list[float] | str,
        waypoint_b: list[float] | str,
        waypoint_c: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        Request a route through 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: list[float] | str,
        waypoint_b: list[float] | str,
        combine_change: bool,
        modes: list[RouteMode] = None,
        departure="now",
    ) -> RoutingResponse | None:
        """
        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: list[float] | str,
        waypoint_b: list[float] | str,
        combine_change: bool,
        modes: list[RouteMode] = None,
        departure: str = None,
        arrival: str = None,
    ) -> RoutingResponse | None:
        """
        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: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        Calculate the fastest car route between two locations.

        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: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        Calculate the fastest truck route between two locations.

        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: list[float] | str,
        destination: list[float] | str,
        via: list[list[float]] | None = None,
        departure_time: str | None = None,
        routing_mode: RoutingMode = RoutingMode.fast,
        alternatives: int | None = None,
        avoid: dict[str, list[str]] | None = None,
        exclude: dict[str, list[str]] | None = None,
        units: RoutingMetric | None = None,
        lang: str | None = None,
        return_fields: list[RoutingApiReturnField] = [RoutingApiReturnField.polyline],
        span_fields: list[RoutingApiSpanField] | None = None,
        truck: dict[str, list[str]] | None = None,
        vehicle: dict[str, list[str]] | None = None,
        scooter: dict[str, str] | None = None,
        headers: dict | None = None,
    ) -> RoutingResponseV8 | None:
        """
        Calculate the route between the 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]]]):
            Deprecated. Use `vehicle` parameter.
          vehicle (Optional[Dict[str, List[str]]]):
            Comma-separated list of vehicle-specific parameters.
            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:
            data["avoid"] = {key: ",".join(vals) for key, vals in avoid.items()}
        if exclude:
            data["exclude"] = {key: ",".join(vals) for key, vals in exclude.items()}
        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:
            warn(
                "'truck' parameter is deprecated in Routing API. Use 'vehicle' parameter instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            if vehicle is None:
                vehicle = truck
        if vehicle:
            data["vehicle"] = {key: ",".join(vals) for key, vals in vehicle.items()}
        if scooter:
            data["scooter"] = scooter

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

    def __prepare_matrix_request_body(
        self,
        origins: list[list[float] | str],
        destinations: list[list[float] | str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: list[float] | None = None,
        radius: int | None = None,
        profile: MatrixRoutingProfile | None = None,
        departure: str = None,
        routing_mode: MatrixRoutingMode | None = None,
        transport_mode: MatrixRoutingTransportMode | None = None,
        avoid: Avoid | None = None,
        truck: Truck | None = None,
        matrix_attributes: list[MatrixSummaryAttribute] | None = None,
    ) -> dict[str, Any]:
        region_definition: dict[str, Any] = {
            "type": matrix_type.__str__(),
        }
        if center:
            region_definition["center"] = {"lat": center[0], "lng": center[1]}
        if radius:
            region_definition["radius"] = radius
        request_body: dict[str, Any] = {"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: list[dict[str, float]] = []
        for origin in 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: list[dict[str, float]] = []
        for destination in 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: list[list[float] | str],
        destinations: list[list[float] | str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: list[float] | None = None,
        radius: int | None = None,
        profile: MatrixRoutingProfile | None = None,
        departure: str = None,
        routing_mode: MatrixRoutingMode | None = None,
        transport_mode: MatrixRoutingTransportMode | None = None,
        avoid: Avoid | None = None,
        truck: Truck | None = None,
        matrix_attributes: list[MatrixSummaryAttribute] | None = None,
    ) -> RoutingMatrixResponse | None:
        """
        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(f"{filename} file saved!")
        return filename

    def __is_correct_response(self, response):
        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: list[list[float] | str],
        destinations: list[list[float] | str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: list[float] | None = None,
        radius: int | None = None,
        profile: MatrixRoutingProfile | None = None,
        departure: str = None,
        routing_mode: MatrixRoutingMode | None = None,
        transport_mode: MatrixRoutingTransportMode | None = None,
        avoid: Avoid | None = None,
        truck: Truck | None = None,
        matrix_attributes: list[MatrixSummaryAttribute] | None = None,
    ) -> RoutingMatrixResponse | None:
        """
        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: dict[str, str | None] = {}

        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)
        except HEREError as here_error:
            raise WaypointNotFoundError(here_error.message)
        items = getattr(geocoder_response, "items", None) if geocoder_response is not None else None
        if not items:
            raise WaypointNotFoundError(f"No geocoding results found for {location_name!r}.")
        coordinates = items[0]["position"]
        return [coordinates["lat"], coordinates["lng"]]

    @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

    async def __get_async(
        self,
        base_url,
        data,
        key,
        response_cls,
        manipulation_key: str = None,
        keys_for_manipulation: list = None,
        headers: dict[str, str] | None = 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 = await self._get_async_client().get(url, timeout=self._timeout, headers=headers)
        json_data = json.loads(response.content.decode("utf8"))
        if response.status_code == 200:
            return response_cls.new_from_jsondict(json_data)
        else:
            raise error_from_routing_service_error(json_data)

    async def _route_async(self, waypoint_a, waypoint_b, modes=None, departure=None, arrival=None):
        if isinstance(waypoint_a, str):
            waypoint_a = await self._get_coordinates_for_location_name_async(waypoint_a)
        if isinstance(waypoint_b, str):
            waypoint_b = await self._get_coordinates_for_location_name_async(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 = await self.__get_async(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

    async def async_bicycle_route(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

    async def async_car_route(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

    async def async_pedestrian_route(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

    async def async_intermediate_route(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        waypoint_c: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        Request a route through 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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

    async def async_public_transport(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        combine_change: bool,
        modes: list[RouteMode] = None,
        departure="now",
    ) -> RoutingResponse | None:
        """
        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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

    async def async_public_transport_timetable(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        combine_change: bool,
        modes: list[RouteMode] = None,
        departure: str = None,
        arrival: str = None,
    ) -> RoutingResponse | None:
        """
        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 await self._route_async(waypoint_a, waypoint_b, modes, departure, arrival)

    async def async_location_near_motorway(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        Calculate the fastest car route between two locations.

        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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

    async def async_truck_route(
        self,
        waypoint_a: list[float] | str,
        waypoint_b: list[float] | str,
        modes: list[RouteMode] = None,
        departure: str = "now",
    ) -> RoutingResponse | None:
        """
        Calculate the fastest truck route between two locations.

        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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

    async def async_route_v8(
        self,
        transport_mode: RoutingTransportMode,
        origin: list[float] | str,
        destination: list[float] | str,
        via: list[list[float]] | None = None,
        departure_time: str | None = None,
        routing_mode: RoutingMode = RoutingMode.fast,
        alternatives: int | None = None,
        avoid: dict[str, list[str]] | None = None,
        exclude: dict[str, list[str]] | None = None,
        units: RoutingMetric | None = None,
        lang: str | None = None,
        return_fields: list[RoutingApiReturnField] = [RoutingApiReturnField.polyline],
        span_fields: list[RoutingApiSpanField] | None = None,
        truck: dict[str, list[str]] | None = None,
        vehicle: dict[str, list[str]] | None = None,
        scooter: dict[str, str] | None = None,
        headers: dict | None = None,
    ) -> RoutingResponseV8 | None:
        """
        Calculate the route between the 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]]]):
            Deprecated. Use `vehicle` parameter.
          vehicle (Optional[Dict[str, List[str]]]):
            Comma-separated list of vehicle-specific parameters.
            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 = await self._get_coordinates_for_location_name_async(origin)
        if isinstance(destination, str):
            destination = await self._get_coordinates_for_location_name_async(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:
            data["avoid"] = {key: ",".join(vals) for key, vals in avoid.items()}
        if exclude:
            data["exclude"] = {key: ",".join(vals) for key, vals in exclude.items()}
        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:
            warn(
                "'truck' parameter is deprecated in Routing API. Use 'vehicle' parameter instead.",
                DeprecationWarning,
                stacklevel=2,
            )
            if vehicle is None:
                vehicle = truck
        if vehicle:
            data["vehicle"] = {key: ",".join(vals) for key, vals in vehicle.items()}
        if scooter:
            data["scooter"] = scooter

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

    async def __prepare_matrix_request_body_async(
        self,
        origins: list[list[float] | str],
        destinations: list[list[float] | str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: list[float] | None = None,
        radius: int | None = None,
        profile: MatrixRoutingProfile | None = None,
        departure: str = None,
        routing_mode: MatrixRoutingMode | None = None,
        transport_mode: MatrixRoutingTransportMode | None = None,
        avoid: Avoid | None = None,
        truck: Truck | None = None,
        matrix_attributes: list[MatrixSummaryAttribute] | None = None,
    ) -> dict[str, Any]:
        region_definition: dict[str, Any] = {
            "type": matrix_type.__str__(),
        }
        if center:
            region_definition["center"] = {"lat": center[0], "lng": center[1]}
        if radius:
            region_definition["radius"] = radius
        request_body: dict[str, Any] = {"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: list[dict[str, float]] = []
        for origin in origins:
            if isinstance(origin, str):
                origin_waypoint = await self._get_coordinates_for_location_name_async(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: list[dict[str, float]] = []
        for destination in destinations:
            if isinstance(destination, str):
                destination_waypoint = await self._get_coordinates_for_location_name_async(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

    async def async_sync_matrix(
        self,
        origins: list[list[float] | str],
        destinations: list[list[float] | str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: list[float] | None = None,
        radius: int | None = None,
        profile: MatrixRoutingProfile | None = None,
        departure: str = None,
        routing_mode: MatrixRoutingMode | None = None,
        transport_mode: MatrixRoutingTransportMode | None = None,
        avoid: Avoid | None = None,
        truck: Truck | None = None,
        matrix_attributes: list[MatrixSummaryAttribute] | None = None,
    ) -> RoutingMatrixResponse | None:
        """
        Asynchronously 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 = await self.__prepare_matrix_request_body_async(
            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 = await self._get_async_client().post(url, json=request_body, headers=headers, timeout=self._timeout)
        json_data = json.loads(response.content.decode("utf8"))
        if response.status_code == 200:
            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)

    async def _get_coordinates_for_location_name_async(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, self._timeout)
        try:
            async with geocoder_api:
                geocoder_response = await geocoder_api.async_free_form(location_name)
        except HEREError as here_error:
            raise WaypointNotFoundError(here_error.message)
        items = getattr(geocoder_response, "items", None) if geocoder_response is not None else None
        if not items:
            raise WaypointNotFoundError(f"No geocoding results found for {location_name!r}.")
        coordinates = items[0]["position"]
        return [coordinates["lat"], coordinates["lng"]]

    async def __download_file_async(self, fileurl: str):
        filename = os.path.basename(fileurl)
        async with self._get_async_client().stream("GET", fileurl, timeout=self._timeout) as response:
            response.raise_for_status()
            with open(filename, "wb") as file:
                async for chunk in response.aiter_bytes(chunk_size=8192):
                    file.write(chunk)
        print(f"{filename} file saved!")
        return filename

    async def async_matrix_async(
        self,
        token: str,
        origins: list[list[float] | str],
        destinations: list[list[float] | str],
        matrix_type: MatrixRoutingType = MatrixRoutingType.world,
        center: list[float] | None = None,
        radius: int | None = None,
        profile: MatrixRoutingProfile | None = None,
        departure: str = None,
        routing_mode: MatrixRoutingMode | None = None,
        transport_mode: MatrixRoutingTransportMode | None = None,
        avoid: Avoid | None = None,
        truck: Truck | None = None,
        matrix_attributes: list[MatrixSummaryAttribute] | None = None,
    ) -> RoutingMatrixResponse | None:
        """Asynchronously request a matrix and poll until its calculation completes."""
        request_body = await self.__prepare_matrix_request_body_async(
            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={})
        headers = {
            "Content-Type": "application/json",
            "Authorization": str.format("******", token),
        }
        response = await self._get_async_client().post(url, json=request_body, headers=headers, timeout=self._timeout)
        if response.status_code != 202:
            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"]
                )
            if 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"])
            raise HEREError("Error occurred on async_matrix " + sys._getframe(1).f_code.co_name)

        json_data = response.json()
        print("Matrix {} calculation {}".format(json_data["matrixId"], json_data["status"]))
        poll_url = json_data["statusUrl"]
        headers = {"Authorization": str.format("******", token)}
        print("Polling matrix calculation started!")
        while True:
            poll_response = await self._get_async_client().get(poll_url, headers=headers, timeout=self._timeout)
            poll_data = self.__is_correct_response(poll_response)
            if poll_data:
                break
            await asyncio.sleep(5)
        print("Polling matrix calculation completed!")
        return RoutingMatrixResponse.new_from_jsondict(poll_data)

__init__(api_key=None, timeout=None)

Initialize the Routing API client.

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 src/herepy/routing_api.py

def __init__(self, api_key: str = None, timeout: int = None):
    """
    Initialize the Routing API client.

    Args:
      api_key (str):
        API key taken from HERE Developer Portal.
      timeout (int):
        Timeout limit for requests.

    """
    super().__init__(api_key, timeout)

async_bicycle_route(waypoint_a, waypoint_b, modes=None, departure='now') async

Request a bicycle route between two points.

Parameters:

Name	Type	Description	Default
waypoint_a	list[float] | str	List contains latitude and longitude in order or string with the location name	required
waypoint_b	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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_bicycle_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

async_car_route(waypoint_a, waypoint_b, modes=None, departure='now') async

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_car_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

async_intermediate_route(waypoint_a, waypoint_b, waypoint_c, modes=None, departure='now') async

Request a route through 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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_intermediate_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    waypoint_c: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    Request a route through 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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

async_location_near_motorway(waypoint_a, waypoint_b, modes=None, departure='now') async

Calculate the fastest car route between two locations.

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_location_near_motorway(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    Calculate the fastest car route between two locations.

    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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

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.	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
RoutingMatrixResponse | None	RoutingMatrixResponse.

Raises:

Type	Description
HEREError	If an error is received from the server.

Source code in src/herepy/routing_api.py

def async_matrix(
    self,
    token: str,
    origins: list[list[float] | str],
    destinations: list[list[float] | str],
    matrix_type: MatrixRoutingType = MatrixRoutingType.world,
    center: list[float] | None = None,
    radius: int | None = None,
    profile: MatrixRoutingProfile | None = None,
    departure: str = None,
    routing_mode: MatrixRoutingMode | None = None,
    transport_mode: MatrixRoutingTransportMode | None = None,
    avoid: Avoid | None = None,
    truck: Truck | None = None,
    matrix_attributes: list[MatrixSummaryAttribute] | None = None,
) -> RoutingMatrixResponse | None:
    """
    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: dict[str, str | None] = {}

    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)

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

Asynchronously request a matrix and poll until its calculation completes.

Source code in src/herepy/routing_api.py

async def async_matrix_async(
    self,
    token: str,
    origins: list[list[float] | str],
    destinations: list[list[float] | str],
    matrix_type: MatrixRoutingType = MatrixRoutingType.world,
    center: list[float] | None = None,
    radius: int | None = None,
    profile: MatrixRoutingProfile | None = None,
    departure: str = None,
    routing_mode: MatrixRoutingMode | None = None,
    transport_mode: MatrixRoutingTransportMode | None = None,
    avoid: Avoid | None = None,
    truck: Truck | None = None,
    matrix_attributes: list[MatrixSummaryAttribute] | None = None,
) -> RoutingMatrixResponse | None:
    """Asynchronously request a matrix and poll until its calculation completes."""
    request_body = await self.__prepare_matrix_request_body_async(
        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={})
    headers = {
        "Content-Type": "application/json",
        "Authorization": str.format("******", token),
    }
    response = await self._get_async_client().post(url, json=request_body, headers=headers, timeout=self._timeout)
    if response.status_code != 202:
        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"]
            )
        if 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"])
        raise HEREError("Error occurred on async_matrix " + sys._getframe(1).f_code.co_name)

    json_data = response.json()
    print("Matrix {} calculation {}".format(json_data["matrixId"], json_data["status"]))
    poll_url = json_data["statusUrl"]
    headers = {"Authorization": str.format("******", token)}
    print("Polling matrix calculation started!")
    while True:
        poll_response = await self._get_async_client().get(poll_url, headers=headers, timeout=self._timeout)
        poll_data = self.__is_correct_response(poll_response)
        if poll_data:
            break
        await asyncio.sleep(5)
    print("Polling matrix calculation completed!")
    return RoutingMatrixResponse.new_from_jsondict(poll_data)

async_pedestrian_route(waypoint_a, waypoint_b, modes=None, departure='now') async

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_pedestrian_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

async_public_transport(waypoint_a, waypoint_b, combine_change, modes=None, departure='now') async

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_public_transport(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    combine_change: bool,
    modes: list[RouteMode] = None,
    departure="now",
) -> RoutingResponse | None:
    """
    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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

async_public_transport_timetable(waypoint_a, waypoint_b, combine_change, modes=None, departure=None, arrival=None) async

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_public_transport_timetable(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    combine_change: bool,
    modes: list[RouteMode] = None,
    departure: str = None,
    arrival: str = None,
) -> RoutingResponse | None:
    """
    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 await self._route_async(waypoint_a, waypoint_b, modes, departure, arrival)

async_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, vehicle=None, scooter=None, headers=None) async

Calculate the route between the 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.	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.	[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]]]	Deprecated. Use vehicle parameter.	None
vehicle	Optional[Dict[str, List[str]]]	Comma-separated list of vehicle-specific parameters. 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
RoutingResponseV8 | None	RoutingResponseV8

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_route_v8(
    self,
    transport_mode: RoutingTransportMode,
    origin: list[float] | str,
    destination: list[float] | str,
    via: list[list[float]] | None = None,
    departure_time: str | None = None,
    routing_mode: RoutingMode = RoutingMode.fast,
    alternatives: int | None = None,
    avoid: dict[str, list[str]] | None = None,
    exclude: dict[str, list[str]] | None = None,
    units: RoutingMetric | None = None,
    lang: str | None = None,
    return_fields: list[RoutingApiReturnField] = [RoutingApiReturnField.polyline],
    span_fields: list[RoutingApiSpanField] | None = None,
    truck: dict[str, list[str]] | None = None,
    vehicle: dict[str, list[str]] | None = None,
    scooter: dict[str, str] | None = None,
    headers: dict | None = None,
) -> RoutingResponseV8 | None:
    """
    Calculate the route between the 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]]]):
        Deprecated. Use `vehicle` parameter.
      vehicle (Optional[Dict[str, List[str]]]):
        Comma-separated list of vehicle-specific parameters.
        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 = await self._get_coordinates_for_location_name_async(origin)
    if isinstance(destination, str):
        destination = await self._get_coordinates_for_location_name_async(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:
        data["avoid"] = {key: ",".join(vals) for key, vals in avoid.items()}
    if exclude:
        data["exclude"] = {key: ",".join(vals) for key, vals in exclude.items()}
    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:
        warn(
            "'truck' parameter is deprecated in Routing API. Use 'vehicle' parameter instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        if vehicle is None:
            vehicle = truck
    if vehicle:
        data["vehicle"] = {key: ",".join(vals) for key, vals in vehicle.items()}
    if scooter:
        data["scooter"] = scooter

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

async_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) async

Asynchronously 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.	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
RoutingMatrixResponse | None	RoutingMatrixResponse

Raises: HEREError: If an error is received from the server.

Source code in src/herepy/routing_api.py

async def async_sync_matrix(
    self,
    origins: list[list[float] | str],
    destinations: list[list[float] | str],
    matrix_type: MatrixRoutingType = MatrixRoutingType.world,
    center: list[float] | None = None,
    radius: int | None = None,
    profile: MatrixRoutingProfile | None = None,
    departure: str = None,
    routing_mode: MatrixRoutingMode | None = None,
    transport_mode: MatrixRoutingTransportMode | None = None,
    avoid: Avoid | None = None,
    truck: Truck | None = None,
    matrix_attributes: list[MatrixSummaryAttribute] | None = None,
) -> RoutingMatrixResponse | None:
    """
    Asynchronously 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 = await self.__prepare_matrix_request_body_async(
        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 = await self._get_async_client().post(url, json=request_body, headers=headers, timeout=self._timeout)
    json_data = json.loads(response.content.decode("utf8"))
    if response.status_code == 200:
        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)

async_truck_route(waypoint_a, waypoint_b, modes=None, departure='now') async

Calculate the fastest truck route between two locations.

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

async def async_truck_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    Calculate the fastest truck route between two locations.

    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 await self._route_async(waypoint_a, waypoint_b, modes, departure)

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

Request a bicycle route between two points.

Parameters:

Name	Type	Description	Default
waypoint_a	list[float] | str	List contains latitude and longitude in order or string with the location name	required
waypoint_b	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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def bicycle_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def car_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    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 route through 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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def intermediate_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    waypoint_c: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    Request a route through 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')

Calculate the fastest car route between two locations.

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def location_near_motorway(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    Calculate the fastest car route between two locations.

    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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def pedestrian_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def public_transport(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    combine_change: bool,
    modes: list[RouteMode] = None,
    departure="now",
) -> RoutingResponse | None:
    """
    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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def public_transport_timetable(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    combine_change: bool,
    modes: list[RouteMode] = None,
    departure: str = None,
    arrival: str = None,
) -> RoutingResponse | None:
    """
    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, vehicle=None, scooter=None, headers=None)

Calculate the route between the 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.	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.	[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]]]	Deprecated. Use vehicle parameter.	None
vehicle	Optional[Dict[str, List[str]]]	Comma-separated list of vehicle-specific parameters. 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
RoutingResponseV8 | None	RoutingResponseV8

Raises: HEREError

Source code in src/herepy/routing_api.py

def route_v8(
    self,
    transport_mode: RoutingTransportMode,
    origin: list[float] | str,
    destination: list[float] | str,
    via: list[list[float]] | None = None,
    departure_time: str | None = None,
    routing_mode: RoutingMode = RoutingMode.fast,
    alternatives: int | None = None,
    avoid: dict[str, list[str]] | None = None,
    exclude: dict[str, list[str]] | None = None,
    units: RoutingMetric | None = None,
    lang: str | None = None,
    return_fields: list[RoutingApiReturnField] = [RoutingApiReturnField.polyline],
    span_fields: list[RoutingApiSpanField] | None = None,
    truck: dict[str, list[str]] | None = None,
    vehicle: dict[str, list[str]] | None = None,
    scooter: dict[str, str] | None = None,
    headers: dict | None = None,
) -> RoutingResponseV8 | None:
    """
    Calculate the route between the 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]]]):
        Deprecated. Use `vehicle` parameter.
      vehicle (Optional[Dict[str, List[str]]]):
        Comma-separated list of vehicle-specific parameters.
        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:
        data["avoid"] = {key: ",".join(vals) for key, vals in avoid.items()}
    if exclude:
        data["exclude"] = {key: ",".join(vals) for key, vals in exclude.items()}
    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:
        warn(
            "'truck' parameter is deprecated in Routing API. Use 'vehicle' parameter instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        if vehicle is None:
            vehicle = truck
    if vehicle:
        data["vehicle"] = {key: ",".join(vals) for key, vals in vehicle.items()}
    if scooter:
        data["scooter"] = scooter

    response = self.__get(
        self.URL_CALCULATE_ROUTE_V8,
        data,
        "routes",
        RoutingResponseV8,
        manipulation_key="via",
        keys_for_manipulation=via_keys,
        headers=headers,
    )
    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.	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
RoutingMatrixResponse | None	RoutingMatrixResponse

Raises: HEREError: If an error is received from the server.

Source code in src/herepy/routing_api.py

def sync_matrix(
    self,
    origins: list[list[float] | str],
    destinations: list[list[float] | str],
    matrix_type: MatrixRoutingType = MatrixRoutingType.world,
    center: list[float] | None = None,
    radius: int | None = None,
    profile: MatrixRoutingProfile | None = None,
    departure: str = None,
    routing_mode: MatrixRoutingMode | None = None,
    transport_mode: MatrixRoutingTransportMode | None = None,
    avoid: Avoid | None = None,
    truck: Truck | None = None,
    matrix_attributes: list[MatrixSummaryAttribute] | None = None,
) -> RoutingMatrixResponse | None:
    """
    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')

Calculate the fastest truck route between two locations.

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
RoutingResponse | None	RoutingResponse

Raises: HEREError

Source code in src/herepy/routing_api.py

def truck_route(
    self,
    waypoint_a: list[float] | str,
    waypoint_b: list[float] | str,
    modes: list[RouteMode] = None,
    departure: str = "now",
) -> RoutingResponse | None:
    """
    Calculate the fastest truck route between two locations.

    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 src/herepy/routing_api.py

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 error class for routing errors.

Source code in src/herepy/routing_api.py

def error_from_routing_service_error(json_data):
    """Return the correct error class for routing errors."""
    if "error" in json_data:
        return _auth_error(json_data)
    elif "status" in json_data:
        return _status_error(json_data)
    elif "subtype" in json_data:
        return _request_error(json_data)
    else:
        return _default_error(json_data)