Distance matrix API is widely used in various applications, including logistics, Ride-hailing, Last Mile delivery, Fleet management and more. In this post, we will take a closer look at how it works, where it’s used and how to get started if you need it. We’ll also delve into the technical details of how the API calculates distances and discuss the factors that are taken into account when calculating travel times. So, let’s begin!
What does the distance matrix API do?
Distance matrix API allows developers to calculate the distances and travel times between multiple locations on a map. It takes a set of origin and destination locations as input and returns a matrix of distances and travel times between them. The API uses algorithms to calculate the shortest possible distance and time required to travel between each pair of locations. This enables businesses to optimize their operations, reduce costs, and enhance the user experience by providing accurate and timely information about travel times and distances.
For example, let’s say you are a Domino’s Pizza franchise owner and you have five delivery points that you need to assign to your delivery driver. You have 5 drivers in the neighbourhood but you want to know which one driver can make all 5 deliveries. So, the question you have as the owner of the pizza shop is:
Which driver out of the 5, can make all 5 deliveries while travelling the shortest distance?
Using the Distance Matrix API, you can input the addresses of the five delivery points as the origins and destinations. The API will then calculate the distance and travel time between each pair of points, resulting in a matrix that looks something like this:
| Driver | Delivery Point 1 | Delivery Point 2 | Delivery Point 3 | Delivery Point 4 | Delivery Point 5 |
|---|---|---|---|---|---|
| Driver 1 | 5.3 miles | 5.2 miles | 3.8 miles | 2.1 miles | 6.5 miles |
| Driver 2 | 6.7 miles | 2.1 miles | 4.3 miles | 7.2 miles | 8.9 miles |
| Driver 3 | 4.1 miles | 4.5 miles | 5.1 miles | 5.8 miles | 9.2 miles |
| Driver 4 | 2.5 miles | 7.3 miles | 5.7 miles | 2.3 miles | 4.4 miles |
| Driver 5 | 7.8 miles | 9.5 miles | 9.1 miles | 4.8 miles | 1.7 miles |
In this example, each row represents a driver, and each column represents a delivery point. The values in each cell represent the distance in miles between the corresponding origin and destination points. By analyzing this matrix, you can determine the optimal route for each driver. For example, Driver 1 should start with Delivery Point 4, then move on to Delivery Point 3, followed by Delivery Point 1, Delivery Point 2, and finally Delivery Point 5, in order to minimize the total distance and travel time.
Distance Matrix API is utilized by various industries in diverse manners, and here are a few examples:
| Use Cases | Description |
|---|---|
| Logistics management | Calculate the distances and travel times between different locations to optimize route planning and scheduling. |
| Ride-hailing services | Calculate fares and travel times for customers and optimize drivers’ routes. |
| Fleet management | Track vehicles’ movements and optimize routes based on real-time traffic conditions and other factors. |
| Location-based marketing | Target customers with location-based marketing campaigns based on distance to nearest store or service. |
| Real estate | Calculate distances between properties and important amenities, such as schools, hospitals, and shopping. |
How to implement distance matrix API
To implement the Distance Matrix API with LocationIQ, you can follow these steps:
- First, you will need to obtain an API key from LocationIQ. You can follow the steps here to register and obtain your API key
- Next, you will need to create a request to the Distance Matrix API endpoint, specifying the origins and destinations of your delivery points. You can use the actual real-world coordinates of your delivery points for this.
For example, let’s say your delivery points and drivers are located at the following coordinates:
| Driver | Delivery Points |
|---|---|
| 40.748817,-73.985428 40.707657,-74.012095 40.733355,-74.003366 40.723791,-73.998344 40.769071,-73.981247 | 40.714352,-74.005973 40.708405,-74.014679 40.715230,-74.003099 40.723612,-74.003965 40.755327,-73.996454 |
This is the visual representation of the plotted coordinates on a map. The driver’s locations are marked with red pins while the delivery points are indicated by green pins.
3. You can create a request to the LocationIQ Distance Matrix API endpoint like this:
https://us1.locationiq.com/v1/matrix/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&sources={elem1};{elem2};..&destinations={elem1};{elem2};...&annotations={duration|distance|duration,distance}Replace {origins} with the comma-separated list of your delivery point coordinates, and {destinations} with the same comma-separated list of coordinates.
Note: Coordinates (Latitude, Longidude) have to be flipped when passing to the distance matrix API (Longidude, Latitude). So,
40.748817,-73.985428becomes-73.985428, 40.748817
For example, the request for our delivery points would look like this:
https://us1.locationiq.com/v1/matrix/driving/-73.985428,40.748817;-74.012095,40.707657;-74.003366,40.733355;-73.998344,40.723791;-73.981247,40.769071;-74.005973,40.714352;-74.014679,40.708405;-74.003099,40.715230;-74.003965,40.723612;-73.996454,40.755327?sources=0;1;2;3;4&destinations=5;6;7;8;9&annotations=duration,distance&key=<YOUR_ACCESS_TOKEN>- Finally, you can parse the response from the API, which will contain the distance and travel time between each pair of origins and destinations in a matrix format, similar to the example table we saw earlier. You can use this information to optimize the routes for your delivery drivers. Here’s what the output looks like:
{
"code": "Ok",
"distances": [
[
4571.1,
9294.5,
4488.6,
3637.3,
8947.4
],
[
1843.7,
1042.2,
2068.3,
2567.4,
12997.4
],
[
2421.3,
3486.4,
2369.8,
1444.5,
10864.8
],
[
1230.5,
2760.3,
1148,
658.8,
11306.6
],
[
7576.2,
9653.7,
7524.8,
6599.5,
9713.3
]
],
"destinations": [
{
"hint": "Z6lFgP___38QAAAAKgAAABYAAAAKAAAASuJsQWoVtEHgZaBBTk4SQRAAAAAqAAAAFgAAAAoAAABUgQEApsGW-69AbQIrwpb7cEBtAgIAPw3H89Mq",
"distance": 13.236533,
"name": "Broadway",
"location": [
-74.006106,
40.714415
]
},
{
"hint": "edRFgP___38mAAAASQAAAAsAAAAAAAAAxxILQjoo90GsFRdBAAAAACYAAABJAAAACwAAAAAAAABUgQEABaCW-_QobQIpoJb7NSltAgIADwfH89Mq",
"distance": 7.832678,
"name": "Rector Street",
"location": [
-74.014715,
40.70834
]
},
{
"hint": "gNFFgP___38gAAAANgAAAA0AAAB3AAAA6tDsQVACl0EgHjVB167VQiAAAAA2AAAADQAAAHcAAABUgQEAbM2W-91DbQJlzZb73kNtAgEArwvH89Mq",
"distance": 0.601738,
"name": "Lafayette Street",
"location": [
-74.003092,
40.715229
]
},
{
"hint": "A75FgP___38JAAAASAAAAAgAAAANAAAAmZsCQbFKYEKao-ZASIE6QQkAAABIAAAACAAAAA0AAABUgQEA2cmW-xlkbQIDypb7nGRtAgEAvxHH89Mq",
"distance": 14.973652,
"name": "Watts Street",
"location": [
-74.004007,
40.723481
]
},
{
"hint": "6PXAhP___38GAAAADAAAAAAAAAAPAAAAr6myQKl5mUAAAAAAz9lYQQYAAAAMAAAAAAAAAA8AAABUgQEAD-eW-57gbQJa55b7f-BtAgAADw3H89Mq",
"distance": 7.207033,
"name": "Dyer Avenue",
"location": [
-73.996529,
40.755358
]
}
],
"durations": [
[
618.6,
794.3,
610.7,
503.4,
924.7
],
[
258.6,
127.6,
286,
360.6,
1464.6
],
[
344.2,
486.7,
332.7,
205,
1179.2
],
[
163.6,
382.2,
155.7,
90.1,
1233.4
],
[
956.6,
1055.3,
945.1,
817.4,
1012.1
]
],
"sources": [
{
"hint": "bK5FgJjIVqHWAAAAKgAAACMAAAAAAAAA8ThAQzSgFUJY_vtBAAAAANYAAAAqAAAAIwAAAAAAAABUgQEAZxKX-wrHbQJsEpf7EcdtAgIAfwfH89Mq",
"distance": 0.884695,
"name": "West 34th Street",
"location": [
-73.985433,
40.74881
]
},
{
"hint": "cdRFgP___39GAAAAVAAAAAoAAAAIAAAAqkl-Ql0oPkFbGxJBM-LQQEYAAABUAAAACgAAAAgAAABUgQEAAaqW-84lbQJBqpb7SSZtAgEA_wbH89Mq",
"distance": 14.690081,
"name": "Rector Street",
"location": [
-74.012159,
40.707534
]
},
{
"hint": "kK9FgP___381AAAAkwAAABIAAAAIAAAAuHYZQvBghULHJ1FBovC3QDUAAACTAAAAEgAAAAgAAABUgQEAL8yW-1KLbQJazJb7q4ptAgEAPxDH89Mq",
"distance": 18.897304,
"name": "Christopher Street",
"location": [
-74.003409,
40.733522
]
},
{
"hint": "kalFgP___38kAAAAhgAAACcAAAAHAAAA1F4BQqBJrkK1dgpC_vfGQCQAAACGAAAAJwAAAAcAAABUgQEAeuCW-xBlbQL435b7T2VtAgIATw3H89Mq",
"distance": 13.022058,
"name": "Broadway",
"location": [
-73.998214,
40.723728
]
},
{
"hint": "6nDDkP___38RAAAAKwAAAG0AAAAIAAAAqn9-QflstEGqYJ1C7aXgQBEAAAArAAAAbQAAAAgAAABUgQEA0SKX-ygWbgLBIpf7LxZuAgoA3wHH89Mq",
"distance": 1.558467,
"name": "Central Park West",
"location": [
-73.981231,
40.769064
]
}
]
}LocationIQ’s distance matrix API returns a JSON object with information on the distance and travel time between various locations. Here’s a breakdown of the output:
- This output is from LocationIQ’s distance matrix API, which calculates the distances and durations between a set of source and destination points.
- The
codekey indicates the status of the API request, where “Ok” indicates that the request was successful. - The
sourceskey lists the starting points with their respective names and coordinates, while the “destinations” key lists the ending points with their respective names and coordinates. - The
distanceskey is a 2D array that lists the distances in meters between each source and destination point. For example, the distance from the first source point to the first destination point is 4571.1 meters, and the distance from the second source point to the fourth destination point is 2567.4 meters. - The
durationskey is also a 2D array that lists the time taken in seconds to travel between each source and destination point. For example, the time taken to travel from the first source point to the first destination point is 618.6 seconds, and the time taken to travel from the second source point to the fourth destination point is 360.6 seconds.
Overall, this output provides a matrix of distances and durations between a set of source and destination points, which can be useful for applications such as logistics and transportation planning. This is how the output looks like in the form of a table:
| Sources | Destination 1 | Destination 2 | Destination 3 | Destination 4 | Destination 5 |
|---|---|---|---|---|---|
| Driver 1 | 4571.1 | 9294.5 | 4488.6 | 3637.3 | 8947.4 |
| Driver 2 | 1843.7 | 1042.2 | 2068.3 | 2567.4 | 12997.4 |
| Driver 3 | 2421.3 | 3486.4 | 2369.8 | 1444.5 | 10864.8 |
| Driver 4 | 1230.5 | 2760.3 | 1148.0 | 658.8 | 11306.6 |
| Driver 5 | 7576.2 | 9653.7 | 7524.8 | 6599.5 | 9713.3 |
From this, we see that Driver #4 will have the most efficient path as they will need to travel the shortest distance at 10981.7 meters while making all 5 deliveries. The driver can:
- First deliver at Destination #4 and then
- Destination #3, after which it’s
- Destination #2,
- Destination #1 and finally
- Destination #5
That concludes our discussion on the Distance Matrix API, and hopefully, you have gained a better understanding of its significance in different industries. We have explored its purpose and use cases, and also examined how it can be integrated with LocationIQ. With this information, you now have a solid foundation to work with if you need to incorporate the API into your own applications. You can now utilize the Distance Matrix API with confidence to enhance the productivity and efficiency of your transportation, logistics, or delivery operations.
If you’re ready to take advantage of the APIs, sign up for a LocationIQ account today! Whether you’re a small business owner or a large enterprise, LocationIQ has everything you need to succeed in today’s competitive landscape.