How to Use the TomTom Routing API for Estimated Time of Arrival

The Routing API is a powerful tool which can be used to get accurate directions for diverse types of vehicles-- with routes like the fastest, shortest, and most exciting. But one overlooked feature from the API is the option to fetch a summary of the requested routes. The Matrix Routing API lets us fetch different summaries with a single call, where we can get ETAs from different destinations.

A Quick Summary of the Routing API

The Routing API is a powerful tool which can be used to get accurate directions for diverse types of vehicles-- with routes like the fastest, shortest, most exciting, etc. It can also provide you with the geometrical shape of the desired route and instructions.

But one overlooked feature from the API is the option to fetch a summary of the requested routes. It is useful to display possibilities to the user, like in this example: we need to find the closest hospital or pharmacy. By getting the summaries, we can offer a better selection using the Matrix Routing Example found here.

Another classic use case for this is a Ride Sharing application. Calculating a best choice driver from a list of providers spread around an area gets tricky when we don’t need to actually create routes to compare, since we only need either driving distance or ETAs. This is when the Summary works its magic.

The summary is requested with the following parameter:

The value ‘polyline’ will return the route graphical representation in a LatLng pairs array, while the summaryOnly will get you an extra JSON section in the response like this :

There are some interesting data here that differentiates this API itself in particular from others:

1. You can see there are different ETAs with No traffic, Live Traffic and Historical traffic consideration.

2. You can get alternative routes and see how much deviation from the original one there is.

Now let’s go and check out a real-life example…

Different types, different ETAs

We are going to check a few different ETAs from our hotel in downtown Chicago – how about "La Quinta Inn"? For this hotel, we’ll use the location :

{
  "lat": 42.37806,
  "lon": -87.94427
}

From the hotel, we would like to find a close by a restaurant, a Cajun creole style restaurant. For this we can use the Category search API [] to get a list of possible restaurants around the hotel (using the LatLng of the Hotel as the Position Bias).

Removing unused data, we get a small list. This is the first element:

{
  "type": "POI",
  "id": "US/POI/p0/6986772",
  "score": 5.66156005859375,
  "dist": 1841.0411486661037,
  "info": "search:ta:840179003788996-US",
  "poi": {
    "name": "Cajun Grill",
  },
  "position": {
    "lat": 42.39081,
    "lon": -87.95857
  }
}

So you can see, we also get the distance to our hotel as part of the result. But this value – in meters– is a direct point of view distance, not the real distance by driving or walking. You can replicate my results by executing this Curl Command.

curl -X GET "https://api.tomtom.com/search/2/categorySearch/creole-cajun.json?countrySet=US&lat=42.37806&lon=-87.94427&key=*****" -H "accept: */*"

For the real driving distance we use the Routing API, requesting only the Summary and adding the option to calculate for different travel times. This is the API Endpoint that we can use:

curl -X GET "https://api.tomtom.com/routing/1/calculateRoute/42.37806%2C-
87.94427%3A42.39081%2C-87.95857/json?routeRepresentation=summaryOnly&computeTravelTimeFor=all&routeType=fastest&traffic=true&avoid=unpavedRoads&key=*****" -H "accept: */*"

Which gives us:

{
  "formatVersion": "0.0.12",
  "routes": [
    {
      "summary": {
        "lengthInMeters": 3428,
        "travelTimeInSeconds": 526,
        "trafficDelayInSeconds": 0,
        "departureTime": "2020-02-17T06:40:53-06:00",
        "arrivalTime": "2020-02-17T06:49:38-06:00",
        "noTrafficTravelTimeInSeconds": 518,
        "historicTrafficTravelTimeInSeconds": 526,
        "liveTrafficIncidentsTravelTimeInSeconds": 526
      },
      "legs": [
        {
          "summary": {
            "lengthInMeters": 3428,
            "travelTimeInSeconds": 526,
            "trafficDelayInSeconds": 0,
            "departureTime": "2020-02-17T06:40:53-06:00",
            "arrivalTime": "2020-02-17T06:49:38-06:00",
            "noTrafficTravelTimeInSeconds": 518,
            "historicTrafficTravelTimeInSeconds": 526,
            "liveTrafficIncidentsTravelTimeInSeconds": 526
          }
        }
      ],
      "sections": [
        {
          "startPointIndex": 0,
          "endPointIndex": 157,
          "sectionType": "TRAVEL_MODE",
          "travelMode": "car"
        }
      ]
    }
  ]
}

While this is good enough for now, we need to get even MORE routes to compare, and for that nothing is better than using the Matrix Routing API.

Getting all possible routes / Routes to many destinations

From the documentation in our Developer Portal:

• For every given origin, this service calculates the cost of routing from that origin to every given destination.
• The set of origins and the set of destinations can be thought of as the column and row headers of a table, while each cell in the table contains the costs of routing from the origin to the destination for that cell.

• Travel times
• Distances

Check the full documentation here :

This looks like exactly what we need.

In our case we are going to calculate driving and pedestrian summaries so we can decide if we want to walk or drive and since the requests are simple enough – no complicated routes here – so we can use the synchronous version: We will wait for a response once all the routes have been calculated.

The end point is a HTTP-POST request. This is the URL we are going to use:

https://api.tomtom.com/routing/1/matrix/sync/json?key=Your_API_Key&routeType=fastest&travelMode=car

The POST Body: Here we will set the different routes (same origin, different destinations) requests. It follows this format:

So in our case this is our POST Body:

{
  "origins": [
    {
      "point": {"latitude":42.37806,"longitude": -87.94427}
    }
  ],
  "destinations": [
    {"point": {"latitude": 42.39081,"longitude": -87.95857}},
    {"point": {"latitude": 42.24304,"longitude": -87.94959}},
    {"point": {"latitude": 42.17424,"longitude": -87.82099}},
    {"point": {"latitude": 42.13930,"longitude": -87.95802}},
    {"point": {"latitude": 42.06633,"longitude": -88.04281}},
    {"point": {"latitude": 42.05039,"longitude": -87.83661}},
    {"point": {"latitude": 42.03845,"longitude": -88.14389}},
    {"point": {"latitude": 42.04051,"longitude": -87.71484}},
    {"point": {"latitude": 42.04204,"longitude": -87.68083}},
    {"point": {"latitude": 42.01446,"longitude": -88.14491}}
  ]
}

With this request we get the following result, truncated for editorial purposes:

{
    "formatVersion": "0.0.1",
    "matrix": [
        [
            {
                "statusCode": 200,
                "response": {
                    "routeSummary": {
                        "lengthInMeters": 3144,
                        "travelTimeInSeconds": 2264,
                        "trafficDelayInSeconds": 0,
                        "departureTime": "2020-02-20T07:00:33-06:00",
                        "arrivalTime": "2020-02-20T07:38:16-06:00"
                    }
                }
            },
            {
                "statusCode": 200,
                "response": {
                    "routeSummary": {
                        "lengthInMeters": 17385,
                        "travelTimeInSeconds": 12517,
                        "trafficDelayInSeconds": 0,
                        "departureTime": "2020-02-20T07:00:33-06:00",
                        "arrivalTime": "2020-02-20T10:29:10-06:00"
                    }
                }
            } ….

For every destination we get a response object and its RouteSummary with the same needed information we got from executing a simple call. Here we see that the ‘Cajun Grill’ restaurant is the closest to us for driving. With this we can populate a list or a display for the user. Try to change the travel Mode to Pedestrian if you want a walking route. Ex. For pedestrian routes:

https://api.tomtom.com/routing/1/matrix/sync/json?key=Your_API_Key&travelMode=pedestrian

Using this request, we see that the ‘Cajun Grill’ restaurant is ALSO the closest to us by walking distance, but in the case that we have different restaurants to choose from, we can always use the Batch Routing API to create all the needed routes using a single call:

This way we only create the routes that we need to display to the user.

In Summary

In this article we took a look at the Routing API and how to fetch ETAs and real driving or walking distances via the Summary object in the response of the Matrix Routing API.

The Matrix Routing API let us fetch different summaries with a single call where we can get such ETAs from different destinations.

I hope this article helps you understand the TomTom Routing API better- thank you for reading and Happy Mapping!