Complete Guide to the Distance Matrix API

The matrix size, or number of elements the API can support in a single call, is arguably the biggest defining feature of any Distance Matrix API, as this dictates how many origins and destinations it can handle with each call.

Most existing APIs support the market standard 25×25 matrix. This means they can resolve up to 25 origins and 25 destinations in a single call, giving you the distances and ETAs between every possible combination. NextBillion.ai’s Distance Matrix API, though, is capable of supporting a much larger matrix of 5000×5000 elements.

Such huge matrices are critical to maximizing the efficiency of large-scale operations like trucking and e-commerce that involve lots of vehicles and destinations. The flexibility of a large matrix enables you to optimize for however many stops you need, and even re-ordering of drop-off points if required. Improved batching, dispatching and routing all naturally follow as a consequence.

Customizability is one of the tenets upon which NextBillion.ai’s Distance Matrix API was built. This is why it was engineered to ingest and process real-time traffic data as well as first- and third-party business-specific data with the help of advanced AI and ML algorithms.

No matter what line of business you’re in — logistics, ride hailing, last mile delivery, etc. — NextBillion.ai’s API can use relevant data from other similar companies to optimize its distance and ETA predictions for your operations. It has the ability to incorporate all those use-case-specific nuances we covered previously.

More importantly, it’s capable of analyzing your own historical ops data — driver behaviors, speed profiles, preferred routes, travel times, frequented POIs, etc. — and modifying its output accordingly. This means that the API can be heavily customized to your business and its unique intricacies. The more relevant data you feed the API, the better suited for your operations its output will be.

Such deep customization, combined with the capacity to process live traffic information, gives rise to incredibly accurate and reliable travel time and distance predictions, and all the benefits that entails.

Another example of NextBillion.ai’s commitment to performance and customizability lies in the ability of its Distance Matrix API to optimize for vehicle types. Most maps generally only support features for cars and sometimes two-wheelers. Enterprise fleets, though, are far more varied, often depending on everything from e-scooters and motorbikes to cars, vans, trucks and more.

This is an important factor to consider because these vehicles don’t all navigate the roads in the same manner; each type of vehicle will have its own routing characteristics and restrictions that must be accounted for. Apart from the weight, height and cargo restrictions we discussed earlier, it’s also worth keeping in mind that cars can’t access some of the routes that two-wheelers can, and larger vehicles can’t access some routes that cars can easily traverse.

NextBillion.ai’s Distance Matrix API incorporates all of these considerations into its calculations, delivering precise predictions consistently. It has profiles for all custom vehicle types and can even be used to optimize mixed-fleet operations. Without vehicle-specific profiles, a Distance Matrix APIs outputs are practically meaningless, unless your entire fleet is made up of regular cars.

When it comes to deployment modes, you’re looking for three things: flexibility, independence and performance. NextBillion.ai’s Distance Matrix API offers all three in abundance.

With the cloud-agnostic deployment feature, you can run the NextBillion.ai API on any cloud service of your choosing; you are not restricted to the services of any particular provider. Such flexibility allows you to seamlessly integrate the API into your existing infrastructure — no disruptions, no unnecessary expenses.

As great as cloud-agnostic deployment is, on-premise deployment offers even more value! Our API can be hosted on your internal infrastructure, delivering performance gains of up to 20x higher throughput and 3x lower latency. Better yet, this gives you complete control over the API deployment; no more dependence on cloud providers to maintain their servers or make any changes you need.

This level of performance and flexibility empowers you to scale at your own convenience without ever having to worry about whether your Distance Matrix API can keep up with the operational demands. Another factor in this regard is that on-premise deployments of the NextBillion.ai Distance Matrix API entitle you to an unlimited number of API calls at a fixed price, helping keep costs in check even at scale.

How many vehicles do you have in your fleet? How many deliveries/rides/stops do you typically need to optimize for? Do you envision your business scaling into something bigger down the line? All of these questions will affect your choice of API. After all, if you’re running a large operation that involves numerous vehicles, pick ups and drop offs, then you’ll need an API that can keep up accordingly.

We know that the size of the matrix matters when it comes to bigger operations, and that one of the NextBillion.ai API’s differentiating features is its large matrix of 5000×5000 elements. How do the Google and Mapbox offerings compare? Well, they both support no more than the market standard 25×25 matrix.

So then, the answer is quite clear cut as far as scale is concerned. If you’re running a relatively small operation, either the Google or Mapbox API should suffice. However, if you’re running a larger operation, you would be best served by the NextBillion.ai Distance Matrix API’s bigger matrix size.

Even if your operation is currently a small one but you want to one day expand it to something bigger, NextBillion.ai would be the choice for you. Why? Our API offers the most bang for your buck for every tier of usage-based pricing (more on this later in this section)! So, while cost can quickly become a bottleneck when scaling up with other APIs, it’ll never be a cause for worry with NextBillion.ai.

Intensive tasks like route optimization and live data integration often require a huge number of API calls in very short periods of time. If your business functions involve a lot of such tasks, you’re going to need a high-performance solution for seamless operations.

This is one of the areas where the deployment modes we went over earlier come into play. We already saw that NextBillion.ai’s Distance Matrix API, with its on-premise deployment option, offers 20x higher throughput and 3x lower latency when compared to typical cloud deployments.

Mapbox’s Matrix API and Google’s Distance Matrix API, though, do not support on-premise deployments; these solutions must be deployed in the cloud. This limitation means that regardless of the quality of the APIs themselves, they will be muzzled by the inherent performance drawbacks of the cloud, which local servers can circumvent.

So, the question then becomes, how important is API performance to the smooth running of your business operations? If high performance is mandatory, then on-premise deployment — and by extension, NextBillion.ai’s Distance Matrix API — is the only way to go.

Independence is another consideration where deployment modes are relevant. First, let’s address independence from being locked in with a specific cloud provider. Some APIs are required to be deployed in a specific cloud provider’s environment. This can be undesirable for many reasons, the most common of which is that it’s quite costly to uproot your existing infrastructure and replace it — possibly even with an inferior solution — for the sake of API compatibility. Thankfully, all three of the Distance Matrix APIs in discussion here support cloud-agnostic deployments, so you’ll never be beholden to the services of a particular cloud provider with them.

Since all three APIs are on even footing in that regard, let’s discuss another level of independence: independence from cloud providers altogether. Liaising with your cloud provider’s support team every time you need to make an adjustment can quickly become a cumbersome process, especially if it’s a frequent occurrence in your operations. In the case of critical and time-sensitive issues, this quickly goes from being a mere inconvenience to a costly liability. Server maintenance and downtime is another possible point of failure that lies in the hands of a third party in typical cloud deployments. If you want complete control over your operation, this is not acceptable. That’s why we have on-premise deployments — to eliminate any sort of dependence on external cloud providers.

Here, the APIs in focus are no longer on even footing, as Mapbox and Google do not allow for on-premise deployments — only NextBillion.ai does. Thus, if you’re looking for total control of your API deployment, there’s only one solution that will give you what you need.

Customizability is a big one if you’re in pursuit of the most reliably precise travel times and distances from your Distance Matrix API. For optimal results, the API needs to be able to ingest and intelligently learn from relevant proprietary as well as external data to modify its output accordingly.

We’ve already seen how NextBillion.ai’s Distance Matrix API has this capability for vehicle- and use-case-specific customizations. Practically any data that’s germaine to the context of your business can be harnessed to enhance the output of the API. Vehicle type, cargo type, time of day during travel, hyper-local nuances like regional road rules and disruptions, and so much more can all be put to good use in refining your vehicle-based operations.

In contrast to this, neither the Google Distance Matrix API nor the Mapbox Matrix API afford you anywhere near such granular customization. As a result of this lack of customizability to any given use case, these APIs are simply unable to match the extreme accuracy that their NextBillion.ai counterpart brings to the table. In this facet of the comparison, your choice of API becomes a function of the level of precision you require for your business operations.

It will come as no surprise to anybody at all that cost is one of the first and biggest considerations behind any business decision — no explanations required there.

Every organization makes and spends money differently, and this has huge implications on how purchase and renewal decisions are made. This is why NextBillion.ai’s Distance Matrix API gives you flexible pricing options — you can find something that works for you, no matter what kind of business model you operate on. Pricing models are as follows:

Pay-as-you-go — Pricing based on volume of API calls

Subscription — Fixed fee with unlimited API calls for on-premise deployment

Customized — Pricing based on ML model deployed

Yes, you read that right — with an on-premise deployment of our API, you get unlimited calls at a fixed cost! It’s not hard to see the value you could draw from this.

So, how do Google’s and Mapbox’s Distance Matrix APIs stack up as far as pricing is concerned? Not well; their pricing models are rigid and inflexible. As we touched upon previously, NextBillion.ai offers the most value for money at every level of usage. Below is a direct comparison of the usage-based pricing for each of the APIs.

As you can see, it’s clear that NextBillion.ai offers more for less. But that’s not all — NextBillion.ai gives you the opportunity to save even more with its BYOD (bring your own data) plan. If you furnish your own historical ops data to feed into the API, we’ll give you a 20% discount. This means that with us, you get the best-performing API at a significantly lower cost than its competitors!

There’s only one winner in this comparison, and it’s NextBillion.ai, without a shadow of a doubt.

With the Google Distance Matrix service, some of your API calls probably look similar to the code presented below. Here we use the Axios library to fetch from the Google Maps API endpoint with a set of origins and destinations, and output results to the terminal to show travel times between each start and end point.

 
var axios = require(‘axios’); 
const colorize = require(‘./utils’); 
module.exports = async function dm(originArray, destArray, points_origins, points_destinations, precision) 
{ 
  let idx = 0; 
  let origin_index = ‘’;
  let dest_index = ‘’;
  orig_pts = ‘’, dest_pts = ‘’; 
  points_origins.forEach(pt => { 
    orig_pts += pt.geometry.coordinates[0].toFixed(precision) + ‘,’ + pt.geometry.coordinates[1].toFixed(precision) + ‘;’; 
    origin_index += idx++ + ‘;’; 
}); 

points_destinations.forEach(pt => { 
  dest_pts += pt.geometry.coordinates[0].toFixed(precision) + ‘,’ + pt.geometry.coordinates[1].toFixed(precision) + ‘;’; 
  dest_index += idx++ + ‘;’; 
}); 

dest_pts = dest_pts.slice(0, dest_pts.length - 1); 
origin_index = origin_index.slice(0, origin_index.length - 1); 
dest_index = dest_index.slice(0, dest_index.length - 1); 

let mbUrl = `https://api.mapbox.com/directions-matrix/v1/mapbox/driving-traffic/${orig_pts}${dest_pts}?sources=${origin_index}&destinations=${dest_index}&access_token=${process.env['MAPBOX_TOKEN']}`; 

var config = { 
  method: ‘get’, 
  url: mbUrl, 
  headers: {} 
} 

await axios(config) 
.then( res => { 
   process.stdout.write(colorize(44,’…Mapbox result… ‘));     
   process.stdout.write(‘\n’);

Output from the Mapbox API call will look similar to this. 
…Mapbox result… 
                 | 37.7027,-122.4330| 37.7373,-122.4477| 37.7698,-122.4552| 
37.6195,-122.4756|              1198|              1180|              1695| 
37.6334,-122.4450|              1122|              1104|              1555| 
37.5791,-122.3562|              1547|              1373|              1829|
                    
                    

The highlighted portion of the code block above is where you’ll need to make changes in order to start using NextBillion.ai’s distance matrix service for the same set of points.

There are very few changes needed; the highlighted section in the below image shows what the modified code and its output should look like.

For NextBillion.ai, we make use of a HTTP POST with the body containing the origins, destinations, travel profile (car, truck etc.) and optional departure timestamp. This enables us to present large matrix problems, in the order of thousands of elements, to the endpoint without exceeding URI length limits.

 
let axios = require(‘axios’); 
const colorize = require(‘./utils’); 

module.exports = async function dm(originArray, destArray, orig_pts, dest_pts, precision) { 

// NBAI JSON will use POST endpoint (concise) 
   const apiKey = process.env[‘API_KEY’]; 
   const apiHost = process.env[‘API_HOST’]; 
// With NBAI, you can set departure time and it will 
// use historic traffic patterns for this date/time 
// Change mode to other transport modes as needed 
let bodyRequest = { 
   “departure_time”: Math.round(new Date().getTime() / 1000), 
   “origins”: orig_pts, 
   “destinations”: dest_pts, 
   “mode”: “car” 
}; 
let config = { 
   method: ‘post’, 
   url: `${apiHost}/distancematrix/json-concise?key=${apiKey}`, 
   data: bodyRequest 
} 

await axios(config) 
  .then((res) => { 
     process.stdout.write(colorize(45,’…NB.ai result… ‘)); 
     process.stdout.write(‘\n’); 
     process.stdout.write(colorize(91, ‘ ‘.toString().padStart(19, ‘ ‘))); 
     destArray.forEach( pt => { 
        process.stdout.write(‘|’ + colorize(91, pt.padStart(19, ‘ ‘))); 
     }); 
     process.stdout.write(‘|’ + ‘\n’); 
     var idx = 0; 
     var dm = res.data; 
     dm.rows.forEach( row => { 
       process.stdout.write(colorize(93, originArray[idx++].padStart(19, ‘ ‘) + ‘|’)); 
      row.forEach( element => { 
         process.stdout.write(colorize(92, element[0].toString().padStart(precision + 15, ‘ ‘))); 
         process.stdout.write(‘|’); 
      }); 
      process.stdout.write(‘\n’); 
    }); 
 }).catch((err) => { 
      console.log(err); 
  }) 
}

Output from the NB.ai API call will look similar to this. 
…NB.ai result… 
                 | 37.6735,-122.4531| 37.6157,-122.4595| 37.6825,-122.4387| 
37.7109,-122.4893|               551|              1125|               775| 
37.6431,-122.4792|               538|               699|               745| 
37.7401,-122.4408|               703|              1277|               927|
               
                    

Migrating from the Mapbox API is a similarly painless process — we just need a bit more modification of inputs and outputs to deal with the returned elements from Mapbox and lat/lon input ordering. See the module `mb_dm.js` in the code repository for the reference implementation from Mapbox that we modified and transitioned to NextBillion.ai.

 
var axios = require(‘axios’); 
const colorize = require(‘./utils’); 
module.exports = async function dm(originArray, destArray, points_origins, points_destinations, precision) 
{ 
  let idx = 0; 
  let origin_index = ‘’;
  let dest_index = ‘’;
  orig_pts = ‘’, dest_pts = ‘’; 
  points_origins.forEach(pt => { 
    orig_pts += pt.geometry.coordinates[0].toFixed(precision) + ‘,’ + pt.geometry.coordinates[1].toFixed(precision) + ‘;’; 
    origin_index += idx++ + ‘;’; 
}); 

points_destinations.forEach(pt => { 
  dest_pts += pt.geometry.coordinates[0].toFixed(precision) + ‘,’ + pt.geometry.coordinates[1].toFixed(precision) + ‘;’; 
  dest_index += idx++ + ‘;’; 
}); 

dest_pts = dest_pts.slice(0, dest_pts.length - 1); 
origin_index = origin_index.slice(0, origin_index.length - 1); 
dest_index = dest_index.slice(0, dest_index.length - 1); 

let mbUrl = `https://api.mapbox.com/directions-matrix/v1/mapbox/driving-traffic/${orig_pts}${dest_pts}?sources=${origin_index}&destinations=${dest_index}&access_token=${process.env['MAPBOX_TOKEN']}`; 

var config = { 
  method: ‘get’, 
  url: mbUrl, 
  headers: {} 
} 

await axios(config) 
.then( res => { 
   process.stdout.write(colorize(44,’…Mapbox result… ‘));     
   process.stdout.write(‘\n’);

Output from the Mapbox API call will look similar to this. 
…Mapbox result… 
                 | 37.7027,-122.4330| 37.7373,-122.4477| 37.7698,-122.4552| 
37.6195,-122.4756|              1198|              1180|              1695| 
37.6334,-122.4450|              1122|              1104|              1555| 
37.5791,-122.3562|              1547|              1373|              1829|

                    

Once again, the migration just requires some changes to the API endpoint, HTTP method and the request body. The sample code shown in the Google example above applies to this migration as well.

Take a look at the sample project in our repo, where we have the three implementations side by side for comparison.