Understanding how the TomTom Routing API Provides Accurate ETAs

Accurate ETAs are crucial to on-demand applications — the difference between delivering a hot meal or handling a hangry customer. We'll look at how the TomTom Routing API provides business-critical routes and ETA data.

Obtaining accurate estimated time of arrival (ETA) calculations is essential for applications supporting fleet and mobility routing, planning, and productivity. Routing, speeds, traffic, and ETA form a matrix of intersecting data that are the foundation of real-world fleet and on-demand applications.

• Fleet management applications need to know whether a vehicle can be available, how soon it can get to its destination, how many orders they can complete, and so on.

• On-demand applications ask which drivers can pick up a customer or an order quickly, what's the fastest route to the customer, when should the customer expect their meal/parcel to arrive, and so on.

This article will explain what ETA is and why it's important to mobility and fleet businesses, and will explore how to take advantage of TomTom’s Routing API and ETA calculations to meet demanding on-demand business needs and customer expectations.

Please note the code section of this article uses an API key, which can be obtained by signing up for a free account at TomTom Developer Portal.

ETA Explained

Accurate estimates of ETA are at the heart of on-demand, delivery, and ride-hailing services, but providing reliable and accurate ETA is not an easy task. The accuracy of the ETA depends on the accuracy of the data used to generate it.

Consistently providing accurate ETA to customers leaves them satisfied with the service, builds trust between the customer and the business, and means they will likely use it again.

A ride-hailing service uses ETA to estimate how much they charge a customer. Its driver could make less than expected if the ETA does not match up to the actual arrival time. The customer could end up paying extra for arriving later than they expected, reducing not only customer satisfaction but also trust among the drivers.

But how does routing affect ETA? Reliable routing utilizes reliable data. It is essential to take traffic information into account. For example, it may take 30 minutes to travel on a given path at 2:00 PM with no traffic. The same route could take up to an hour to travel at 5:00 PM. A different route may be more efficient during that time.

Routing without traffic data produces an unreliable estimate. Great routing not only increases productivity by finding efficient routes, it generates reliable and accurate ETA that will lead to customer satisfaction.

Therefore, an efficient and reliable traffic and routing provider is essential for an application serving a fleet or on-demand business's needs.

Routing ETA with TomTom

As the leading location technology specialist, TomTom uses its traffic data and an extensive database of historical speed and traffic patterns to calculate both reliable and efficient routes, as well as accurate ETA.

The service is available to developers directly through the Routing API or through the Maps SDK for Web, Android, and iOS applications.

When making routing calculations, TomTom API uses its traffic data for immediate departure. It is aware of current traffic conditions, speed restrictions, road closure and so on.

A developer can also ask TomTom to provide alternate routes using a plethora of options. Some of the more common ones include the type of vehicle, preferred roads, and cargo types for restrictions. You can ask for the fastest, shortest, or the most fuel-economical suggestions.

Let's dive into an example.

Using the Routing API for ETA Prediction

In this example, a delivery driver is expected to start just north of San Bruno, drop off the packages along the points marked Stop #2, Stop #3, and Stop #4 and finish in Daly City. We want to find out how long it would take for the driver to complete the trip.

Although it is not necessary, the code samples of this section use the Maps SDK for Web, an equivalent cURL call is provided with each sample. To install the Maps SDK and set up your application, see the Display a vector map tutorial.

Using the Maps SDK, we can use the Routing API Calculate Route service to determine the fastest path by following these steps:

Combine the coordinates of each stop into a string with the following format:

'${coord1.lng}, ${coord1.lat}: ${coord2.lng}, ${coord2.lat}: ${coord3.lng}, ${coord3.lat}.....'

Longitude and latitude are separated by a comma, different pairs of coordinates are delimited using a colon.

We will use the following path in our example. The coordinates listed were obtained via the Search API Geocoding service and expanded below for demonstration purposes.

const path = ‘-122.40098, 37.63029:-122.41563, 37.6567:-122.39311, 37.79135:-122.45272, 37.74609: -122.48996, 37.68315’;

Now make the call to the Routing API through the Maps SDK:

const path = ‘-122.40098, 37.63029:-122.41563, 37.6567:-122.39311, 37.79135:-122.45272, 37.74609: -122.48996, 37.68315’;
const eta = await tt.services.calculateRoute({
    key: key,
    locations: path
}).go();

return eta;

This is equivalent as making a GET call through cURL:

curl --location --request GET 'https://api.tomtom.com/routing/1/calculateRoute/{path}/json?key={your_key}'

The following path was generated and projected onto the map through the Maps SDK for Web:

Understanding Route Types

By default, Calculate Route returns the fastest path matching the given criteria. We can request the shortest or the most economical path as well.

Specifying a type of route is done through passing a routeType option in the API or SDK call.

If we wanted to find the shortest path instead of the fastest, we could do so by specifying routeType as “shortest”:

const eta = await tt.services.calculateRoute({
    key: key,
    locations: path,
    routeType: 'shortest'
}).go();

This is equivalent to the cURL call:

curl --location --request GET 'https://api.tomtom.com/routing/1/calculateRoute/{path}/json?key={your_key}&routeType=shortest'

TomTom provides a few options to calculate the best path based on fuel economy. In the simplest case, we specify ‘eco’ as our routeType.

const eta = await tt.services.calculateRoute({
        key: key,
        locations: path,
        routeType:'eco',
    }).go();

Equivalent cURL:

curl --location --request GET 'https://api.tomtom.com/routing/1/calculateRoute/{path}/json?key={your_key}&routeType=eco'

In addition to the basic types of routes, we can apply many more conditions to the calculation. For example, we can choose to avoid certain types of roads by passing in a string array to the option avoid.

const eta = await tt.services.calculateRoute({
    key: key,
    locations: path,
    avoid: ['motorways','tollRoads']
}).go();

Alternative Routes and ETA Details

Due to the uncertain nature of traffic, we can expect drivers to take detours. Sometimes, we may want to plan using the assumption that suboptimal routes or departure times will be followed. TomTom allows us to do that as well.

By default, TomTom recommends one route, but we can ask it to provide alternative routes using the parameter maxAlternatives.

    const eta = await tt.services.calculateRoute({
        key: key,
        locations: path,
        computeTravelTimeFor: 'all',
        sectionType: ['tollRoad', 'motorway', 'tunnel','traffic'],
        maxAlternatives: 5
    }).go();

Equivalent cURL call:

curl --location --request GET 'https://api.tomtom.com/routing/1/calculateRoute/{path}/json?maxAlternatives=5&computeTravelTimeFor=all&sectionType=tollRoad&sectionType=motorway&sectionType=tunnel&sectionType=traffic&key={your_key}

Notice in this sample, I have also set the computeTravelTimeFor property, asking for a detailed analysis of travel time for each alternative route.

I have also enabled sectionType to help us decide based on how many different types of roads are on the path.

Here is the response of the recommended route:

    {
      "summary": {
       "lengthInMeters": 47192,
       "travelTimeInSeconds": 4755,
       "trafficDelayInSeconds": 0,
       "departureTime": "2020-11-15T16:24:13-08:00",
       "arrivalTime": "2020-11-15T17:43:25-08:00",
       "noTrafficTravelTimeInSeconds": 4095,
       "historicTrafficTravelTimeInSeconds": 4755,
       "liveTrafficIncidentsTravelTimeInSeconds": 4755
      }

And here's where we see the ETA details. The route response shows not just the estimated travel time (), but also important details like arrival time and traffic delays.

The noTrafficTravelTimeInSeconds, historicTrafficTravelTimeInSeconds, and liveTrafficIncidentsTravelTimeInSeconds details enable you to compare the current ETA with baseline details like historical traffic and live traffic travel times. Perhaps no traffic travel time suggests rescheduling a delivery to a different time of day.

Keep in mind that when building a functional application for end users, it would make sense to translate these fields into a cohesive time in minutes or hours, or several, denoting the total travel time, delay time, and so on in a more readable measurement.

Here is the response to one of the alternate routes:

{
      "summary": {
       "lengthInMeters": 53589,
       "travelTimeInSeconds": 5808,
       "trafficDelayInSeconds": 30,
       "departureTime": "2020-11-15T16:24:13-08:00",
       "arrivalTime": "2020-11-15T18:00:59-08:00",
       "noTrafficTravelTimeInSeconds": 4968,
       "historicTrafficTravelTimeInSeconds": 5796,
       "liveTrafficIncidentsTravelTimeInSeconds": 5808,
       "deviationDistance": 292,
       "deviationTime": 25,
       "deviationPoint": {
        "latitude": 37.6321,
        "longitude": -122.39887
       },
      …
      "sections": [
       {
        "startPointIndex": 124,
        "endPointIndex": 128,
        "sectionType": "TUNNEL"
       },
       ...
       {
        "startPointIndex": 258,
        "endPointIndex": 572,
        "sectionType": "MOTORWAY"
       },
       {
        "startPointIndex": 829,
        "endPointIndex": 845,
        "sectionType": "TRAFFIC",
        "simpleCategory": "JAM",
        "effectiveSpeedInKmh": 36,
        "delayInSeconds": 30,
        "magnitudeOfDelay": 1,
        "tec": {
         "causes": [
          {
           "mainCauseCode": 1
          }
         ],
         "effectCode": 4
        }
       }
      ]
      }

In this response, we can see a traffic jam where the effective travel speed has been limited to 36 km/h in one of the alternate routes.

Historically, it takes about 96 minutes (5796 seconds) to make this 53km trip at the time. With the current traffic condition, it would take about the same amount of time (5808 seconds). Having information about the alternative routes as a driver allows us to make more reasonable projections.

Next Steps

In this article, we have established the importance of using reliable, up-to-date traffic data to generate ETA for any fleet management/on-demandapplication. Calculating an accurate ETA is essential in providing predictability for both a business and its customers, and efficient routing plays an integral part in producing such an ETA.

Getting started is as simple as signing up for a free developer account and trying it out yourself.

The API Explorer is a great place to see what options are available and try out the different API calls.

The Pizza Delivery example is a great introduction on the application of the Routing API.

Finally, to cap out routing and ETA, we can improve the performance of the operation using Batch and Matrix Routing Requests.

Happy mapping!