# How to Use the Distance Matrix API

February 11, 2020
##### Yaron Fidler

Get started

When you use Google Maps Platform to plot multiple locations, you can see nearby markers visually. However, their true distance isn’t always clear, especially when factoring in traffic. You can quantify how close two points are by calculating the distance using the Maps Javascript API, but when you want to determine many distances at once, the Distance Matrix API can help you out and get all the data you need in a single call. For example, you can narrow a list of restaurants by delivery time, assign multiple delivery drivers based on proximity, or determine the nearest technician to a customer to dispatch.

In this post, we’ll show you how to use the Distance Matrix API using a common use case–technician dispatching. First, it’s important to understand all the data that is returned from the API, so we’ll start with a basic example identifying the driving distances between major Midwestern cities.

Add map markers for each city

Before you calculate any distances, it’s useful to see the locations on a map. To do that, you’ll need to create markers for our quintet of cities: Chicago, Milwaukee, Detroit, Indianapolis, and St. Louis.

Here’s some HTML and JavaScript to create a map with these cities marked:

Find your API Key in the Google Cloud Console and put it in place of YOUR_API_KEY in the code above. In addition to creating a basic map centered in the midwestern United States, the code above creates five markers—one for each of the cities in our example.

When you save the code and load it in a browser, you’ll see a map like the one above. You can probably tell just by looking which city is closest to Chicago, but let’s see how a distance matrix can quantify the solution.

Visualize the distance matrix with a mileage table

The concept behind the Distance Matrix API comes from a time before smartphones and ubiquitous GPS. Travelers would reference printed materials to determine driving distances and durations. You could find two-dimensional mileage tables with city names along the left side and top. Within those tables, found on a paper map in your car or posted on a wall at a gas station, were the distances between the cities in each row and column.

If you were near Chicago, for example, you could quickly read across the first row to see the distance to Milwaukee (92 miles) or Detroit (281 miles). The diagonal pattern of empty cells is a quick heads up that you’re looking at a mileage table—there’s no driving from Chicago to Chicago, after all.

The Distance Matrix API is a modernized take on this glove box classic. You have complete control over the origins in each row and destinations in each column, which allows you to recreate a classic distance matrix, or use a single origin with multiple destinations. Best of all, there’s no need to print these out. You can make a request and have your answer in JSON in seconds.

Calculate drive times from multiple origins

Distances between cities may be fine for paper road maps, but today’s applications have more granular needs that can be supported by the Distance Matrix API. For example, the API is useful for dispatch and delivery, where you have a number of origins or destinations. Let’s see how you can use the Distance Matrix API to choose the closest repair technician.

This usage of the Distance Matrix API includes one destination (the customer) and multiple origins (each potential technician). We’ll assume you know the current position of each technician, such as from GPS.

Add the following code to your map JavaScript after the `// Add Distance Matrix here` comment:

Since there is a single destination and multiple origins, the results will include multiple rows, each with a single result. In visual distance matrix terms, you’ll be parsing a single column. When the results are returned to the callback function, the code simply logs the response to the browser console. You can inspect it with your browser’s developer tools, or review the JSON payload:

The origin and destination addresses are returned at the top level of the response. They can help you make sense of which distance is which. The origins, which were input as latitude/longitude coordinates, have automatically been reverse geocoded to the nearest address.

The `rows` array has three items, one for each origin (the technicians). Within each row, there is an elements array that includes a result for each destination. Individual results include a status, duration, and distance.

Now that you understand the Distance Matrix data, you’ll want to use it. For example, you could populate a table, share distances on the map, or search through for the shortest drive.

Find the nearest location by drive time

We want to dispatch the nearest technician to the customer location. To do that, we’ll parse the distance matrix JSON to find the shortest drive time.

Add this code after the `console.log` of the Distance Matrix callback: