GuidesAPI Reference
Guides
  1. HERE Routing API v8 Developer Guide
  2. Restrictions and regulations

Time-dependent routing

In your request for a route, you can use the departureTime or arrivalTime parameter to specify a time at which the route begins or ends respectively.

You have several possibilities:

  • Default: The current time is used as a departureTime
  • Specify a departure time, for example: departureTime=2021-09-03T08:30:25+02:00
  • Specify an arrival time, for example: arrivalTime=2021-09-03T08:30:25
  • Specify an unknown departure time: departureTime=any. We refer to this as "planning mode".

You can use either departureTime or arrivalTime in a route request, but not both.

📘

Note

The Routing API specifies time in the date-time or full-date T partial-time format according to RFC 3339.

Specify a known departure time

When you specify a known departureTime the service will start the route at that time, and then project the time along the route into the future. Each part of the route is evaluated assuming the user would arrive there according to the travel time estimates of the preceding parts.

For example, setting departureTime=2021-09-03T08:00:00+00:00 has the following effect:

  • the route starts at the origin waypoint at 08:00 UTC
  • 1 hour along the route, map data is evaluated using a time value of 09:00 UTC
  • 2 hours along the route, map data is evaluated using a time value of 10:00 UTC

Specify a known arrival time

When you specify a known arrivalTime, it works similarly to specifying a known departureTime, except that time progresses backwards from the destination waypoint instead of forwards from the origin.

For example, setting arrivalTime=2021-09-03T08:00:00+00:00 has the following effect:

  • the route ends at the destination waypoint at 08:00 UTC
  • 1 hour from the destination, map data is evaluated using a time value of 07:00 UTC
  • 2 hours from the destination, map data is evaluated using a time value of 06:00 UTC

Specify a time without time zone

If you specify departureTime or arrivalTime without specifying a time zone, then the service uses the time zone local to the corresponding waypoint:

  • departureTime: The service uses the time zone at the origin waypoint
  • arrivalTime: The service uses the time zone at the destination waypoint

For example, with departureTime=2021-09-03T08:00:00 (summer time) and origin=52.53095, 13.38517 (located in Berlin, Germany), the resulting time zone is CEST (UTC+02:00). The resulting departure time is the same as if we had requested departureTime=2021-09-03T08:00:00+02:00.

Specify an unknown departure time

By sending departureTime=any you indicate to the service that you do not know when the route will be traversed.

This is often called "planning mode", as it's a useful tool to get an estimate for the route without knowing when to schedule it exactly. it's important to note, though, that the resulting route is usually more optimistic than a route with a known departure or arrival time.

The service then disregards most time-dependent attributes and data, for example:

  • Time-dependent restrictions
  • Reversible lanes
  • Current and predicted traffic

The service does take the following traffic data into account:

  • Free-flow traffic speeds
  • Long-term closures

Arrival and departure time in resulting route

If you specify a known departureTime or arrivalTime, each section in the route response contains a departure and arrival time, indicating when that section starts and ends. This time is specified in the time zone local to the location associated with the location.

The following example specifies departureTime=2021-09-03T08:30:25-05:00:

curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'transportMode=car&'\
'origin=52.5308,13.3847&'\
'destination=52.5323,13.3789&'\
'departureTime=2021-09-03T08:30:25-05:00&'\
'apiKey=YOUR_API_KEY'

The origin location is in Berlin, which is in the CEST time zone (UTC+02:00) at this time of year. The resulting response contains a departure time of 2021-09-03T15:30:25+02:00 (which is 2021-09-03T08:30:25-05:00 expressed in Berlin's +02:00 time zone), and an arrival time of 2021-09-03T15:31:47+02:00:

"routes": [
  {
    "id": "46a98eca-44d8-40b0-9e3c-cf813766b247",
    "sections": [
      {
        "departure": {
          "time": "2021-09-03T15:30:25+02:00",
          ...
        },
        "arrival": {
          "time": "2021-09-03T15:31:47+02:00",
          ...
        },
        ...
      }
    ]
  }
]

Having the time output in this format is useful for displaying departure and arrival time in local time.

Updated last month