How the TomTom Matrix Routing API can Power Complex Fleet Routing Applications

Fleet management and routing applications have special needs — from shortest travel time to traffic to routing hundreds of vehicles at once. We'll take a look at how the TomTom Matrix Routing API can power complex fleet routing applications.

Some people think fleet management or fleet vehicle routing means scaled-up basic vehicle routing — from point A to point B by the best route possible. But what does “best route” mean? You might need to consider the shortest travel time, traffic, compliant routes, and fuel efficiency. And you probably prefer that your trucks don’t get stuck under low bridges.

In this article, we’ll take a closer look at where and how you can use TomTom Routing services for fleet management, with a particular emphasis on using the TomTom Matrix Routing API to power complex and unique fleet logistics and mobility and on-demand applications.

Fleet Routing and Batch Routing

Before we get to the TomTom Matrix Routing API, let’s review features of the standard TomTom Routing API and the TomTom Batch Routing API, since both are also useful in most logistics applications.

The Routing API calculates standard A-B routes (routes between 2 points), routes with waypoints, common options such as departure time, arrival time, as well as many other useful options. The "vehicleCommercial" option, for example, avoids sending trucks and commercial vehicles to streets where they are not allowed. There are also options to make sure routes consider vehicle dimensions (height, width, and length), to create routes that prevent sending trucks under low bridges, and to specify the type of cargo for consideration of restricted roads.

These options are demonstrated in the TomTom Maps SDK For Web examples — each sample runs online and includes clear, documented source. Between the complete list of options in the Routing API documentation and the examples, you’ll soon get ideas or building blocks you can use in your own solutions.

The TomTom Batch Routing API can save you multiple calls to the standard Routing API, as a single call to the Batch Routing API can fetch up to 100 routes synchronously or 700 routes asynchronously, making this very useful for filtering large lists of alternate routes. Matrix Routing supports all the same options as the standard Routing API.

The Batch Routing API is well-supported with documentation and many samples, including this example demonstrating how a single call can fetch 16 different routes with different start times, varied by 30 minute intervals over an 8-hour period—a very useful technique to show the effects on ETA and delays during peak-hour traffic on delivery times.

TomTom Matrix Routing for Fleet Routing

The TomTom Matrix Routing API uses a single API call where you can specify a matrix of origin points and destination points. Matrix Routing does not return detailed routes. It does return travel times and distances for each origin-destination pair in the matrix. The calculated route matrix includes all combinations of origin points and destination points. Out of the box you get one-to-many, many-to-one, and many-to-many route options simply by varying the number of origin points and/or destination points. For example, 1 call with 3 origin points + 4 destination points returns information about 12 routes (3x4).

The main benefit compared to Batch Routing is that Matrix Routing is more lightweight, allowing you to find the best combinations without having to calculate the full detailed route.

Now let’s look at how to call the TomTom Matrix Routing API and what the response should look like, to see how you can extract travel times and distances for each route combination.

Once you’ve tried the online examples, the next step to test the TomTom Matrix Routing API and understand the format of the response is to sign up for a free TomTom developer API key, then try out your own calls into the actual API. You can construct the call as a POST using a REST test tool such as Postman or Insomnia. Once you’ve installed the tool, create a new POST request and build up the URL using your API key, following this template:

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

Now go to the body of the request in your REST tool, add a Raw/JSON request body comprising your list of origin points and destination points, as below:

{

  "origins": [

    {"point": {"latitude": 45.458545,"longitude": 9.150490}},

    {"point": {"latitude": 45.403337,"longitude": 11.050541}}

  ],

  "destinations": [

    {"point": {"latitude": 48.149853,"longitude": 11.499931}},

    {"point": {"latitude": 50.033688,"longitude": 14.538226}}

  ]

}

Submit the request and you should see a response that includes four routes (2x2 because we started with 2 origin points and had 2 destination points). Note that the image below shows the result from Postman, truncated for brevity here:

By using the REST API tool, you can try out various options, work out how to compose your requests, and see clearly what’s sent back to you in the response — and all of this without any JavaScript errors!

Note that, as shown in the Synchronous Matrix documentation, some options are sent in the POST using JSON, but most routing options are sent in the query string. If you have questions, drop by the TomTom for Developers Forum.

A REST API tool such as Postman gives you a great head start as you'll have working tests of your API calls in the tool side-by-side with your code as it’s taking shape.

Building Fleet Routing Applications with Matrix Routing

There are many kinds of fleet application scenarios that can benefit from the TomTom Matrix Routing API. Here are a couple of examples:

[]Delivery Service: You need to build an application to create routes to deliver 100 orders per day from a chain of five grocery stores, and those deliveries could be all over town. How do you determine which orders should be delivered from each of the five stores?

Start with a single call to the TomTom Matrix Routing API using many-to-many routing, with each store address as an origin point and each order’s delivery address a destination point.

From the API response, select the route between each order to find the closest store, (sort order will be the distance to store, grouped by order). Now collect the orders nearest to each store, to form five lists of orders: one list for each store.

Finally, for the optimal route for each store’s delivery truck, you could call the TomTom Routing API Batch Routing services for the selected routes using the same parameters as used for Matrix Routing. Set start and end points as the store address and set each order delivery address as a waypoint.

[]Taxi Service: The scope of matrix routing is not only trucks. How do you match a taxi (from a varying number of cars) with a passenger from incoming requests? This actually involves several questions, which the TomTom API can help answer:

Track status (available, busy, booked/enroute, off work, and so forth) and geographical location for all taxis using the Position Service from TomTom Location history API, assuming the taxi reports its location and changing attributes frequently.

Pickup requests made by a mobile app can send location automatically, while voice calls can use the Geocode method from TomTom Search API to translate a street address to geographical coordinates.

Call the TomTom Matrix Routing API with each available taxi and each pickup request to find the closest taxi, then callthe TomTom Routing API to generate driver directions to the customer. (You could use Batch Routing for this, as well.) Flag the taxi and client as booked/enroute until actual pickup is completed.

Filter the list of pickup requests waiting for a taxi and include these in a regular call using polling to the TomTom Matrix Routing API to match each with the nearest free taxi.

The TomTom Matrix Routing API can determine the best taxi/pickup combinations.

This doesn’t work so well for people who are a long way from the nearest taxi, so you’ll need to track wait times and prioritize pickups to service such people and ensure they’re not stranded.

You could also include handling taxi breakdowns and filtering pickups for special-needs clients to ensure only suitable taxis are dispatched.

For more information on how to create a web application for a taxi company using version 5 of the TomTom Maps SDK for Web, check out the use case tutorial here.

For a ste-by-step tutorial on using the Matrix Routing API in the TomTom Maps SDK for Web, check out this video:

Wrapping Up

In this article, we looked at how the TomTom Matrix Routing API can help with practical, real-world situations concerned with fleet routing and logistics. We also saw how to call the Matrix Routing API and how to extract the data returned from the API.

Here are other articles that can help you build successful routing applications:

• How to Use the TomTom Routing API for Estimated Time of Arrival
• What is Batch Routing and Matrix Routing?

• TomTom Routing API Documentation