Using the Distance Matrix API for Bing Maps
Introduction
The Distance Matrix API allows you to generate travel time and distances (with the help of the Bing Maps Route API) for a given set of origins and destinations.
It can also factor in predictive traffic information when generating times thereby allowing you to avoid any potential delays. Some of the other features include, but are not limited to:
- Calculating 1 days’ worth of travel in 15 minute intervals
- Support for multiple transport modes
- Support for GET and POST requests
- Asynchronous support (for larger requests)
- JSON and XML support
- Option to cache results for up to 72 hours
In this blog post:
- we introduce the Bing Distance Matrix API
- identify some of the applications
- discuss how the Bing Distance Matrix API helps solve real world problems
- walk through some sample code
First, a few concepts:
Distance Matrix
A distance matrix is a 2d array that contains N origins and N destinations.
Way Point
A geographical location defined by longitude and latitude used for navigational purposes.
Travel Mode
This is the mode of travel for a given route. This can be Driving, Public Transit or Walking.
Applications
A distance matrix has numerous applications in routing and fleet management and can be applied to many sectors such as Retail, Logistics, Manufacturing and Property / Real Estate.
Implementing a distance matrix allows you to:
- determine arrival times based on start times
- sort search results by their travel distance or time
- calculate the different in commuter times between locations
- cluster data based on travel time/distance. E.g. Find me all restaurants within a 3-mile radius of the property you’re about to purchase.
- …and much more!
These features can be important if you need to consider time windows, have multiple pickup and delivery locations or split deliveries.
One of the most common applications of the distance matrix is to help power algorithms related to logistics problems, specifically the Vehicle Routing (VRP) and Travelling Salesman Problems (TSP) (route optimisation).
The Traveling Salesman Problem (TSP)
The travelling salesman problem, which was first formulated in 1930, asks the following question:
“Given a list of cities and the distances between each pair of cities, what is the shortest possible route that visits each city exactly once and returns to the origin city?”
A problem like this has many variables, and it’s out-with the scope of this blog post to go into mathematics, linear programming and computation required to arrive at such answers. An in-depth explanation of the TSP can be found here if you’re interested.
How does the Distance Matrix API to solve this problem?
The Bing Maps Distance Matrix API shields you from the complexity of this problem and helps solve it for you with ease.
By encapsulating complex algorithms in easy to use endpoints, you can quickly develop solutions in a language of your choice and integrate TSP solutions with your existing tech stack or business application.
You supply a set of Origins, Destinations and Travel Mode, invoke the Distance Matrix API, and a distance matrix will be returned that contains Travel Distances and Travel Durations.
Armed with this data you can then identify an optimum route for your fleet or sales team.
An Example
In this example, we have a salesperson that has several client meetings across the UK. They’re from London and they need to visit the following places in one day:
- Leeds
- York
- Liverpool
A solution that leverages the Bing Distance Matrix API can help optimise our journey times by prompting the salesperson as to which clients are closest.
In the following screen shot, a request has been constructed in Postman with the following parameters: 
This request is then sent to the Distance Matrix API Endpoint and returns the following response which you can see in the code extract below:
{
"authenticationResultCode": "ValidCredentials",
"resourceSets": [
{
"estimatedTotal": 1,
"resources": [
{
"__type": "DistanceMatrix:http://schemas.microsoft.com/search/local/ws/rest/v1",
"destinations": [
{
"latitude": 53.7947998046875,
"longitude": -1.54653000831604
},
{
"latitude": 51.506420135498,
"longitude": -0.127210006117821
},
{
"latitude": 53.4100914001465,
"longitude": -2.9784300327301
}
],
"errorMessage": "Request accepted.",
"origins": [
{
"latitude": 51.506420135498,
"longitude": -0.127210006117821
}
],
"results": [
{
"destinationIndex": 0,
"originIndex": 0,
"travelDistance": 194.086344075461,
"travelDuration": 12104.9
},
{
"destinationIndex": 1,
"originIndex": 0,
"travelDistance": 0.0317589719333333,
"travelDuration": 36.8
},
{
"destinationIndex": 2,
"originIndex": 0,
"travelDistance": 210.211478785907,
"travelDuration": 13215.8
}
]
}
]
}
],
"statusCode": 200,
"statusDescription": "OK",
"> {
"authenticationResultCode": "ValidCredentials",
"resourceSets": [
{
"estimatedTotal": 1,
"resources": [
{
"__type": "DistanceMatrix:http://schemas.microsoft.com/search/local/ws/rest/v1",
"destinations": [
{
"latitude": 53.7947998046875,
"longitude": -1.54653000831604
},
{
"latitude": 51.506420135498,
"longitude": -0.127210006117821
},
{
"latitude": 53.4100914001465,
"longitude": -2.9784300327301
}
],
"errorMessage": "Request accepted.",
"origins": [
{
"latitude": 51.506420135498,
"longitude": -0.127210006117821
}
],
"results": [
{
"destinationIndex": 0,
"originIndex": 0,
"travelDistance": 194.086344075461,
"travelDuration": 12104.9
},
{
"destinationIndex": 1,
"originIndex": 0,
"travelDistance": 0.0317589719333333,
"travelDuration": 36.8
},
{
"destinationIndex": 2,
"originIndex": 0,
"travelDistance": 210.211478785907,
"travelDuration": 13215.8
}
]
}
]
}
],
"statusCode": 200,
"statusDescription": "OK",
The JSON is straight forward enough to read. The key nodes are:
- Origins
- Destinations
- Results
The Origin and Destination nodes are self-explanatory – these contain the starting point and destinations that are relevant to our salesperson.
Results Node
In the Results node however, you can see the travelDisance and travelDuration values have been calculated for each destination by the Distance Matrix API.
As our fictitious salesperson completes each meeting, their mobile CRM tool, powered by the Distance Matrix API, can auto-suggest the next closest meeting, thereby allowing them to focus on value-add tasks as opposed to journey planning.
“Under the hood”, you can query this JSON in your application, sort and display the results in whichever way you see fit. This just one way that a Bing Distance Matrix API can help businesses run more efficiently.
Another example – Property and Real Estate
Imagine for a minute that you’re working on a mobile application for a property / real estate business. When searching for properties in the mobile application, users must be able to plan a potential commute from the property they’re currently viewing.
With the Distance Matrix API, you can supply the latitude/longitude of the property and the respective destinations (office or train station for example) – along with the mode of travel (driving, public transit or walking) and the API will return data that allows you to determine the quickest routes.
You might also want to further enrich your datasets by introducing the Spatial Data Services API to identify Points of Interest Data (POI).
Predictive Intelligence
Another layer of intelligence can be applied by leveraging predictive traffic data which can help you further provide more accurate timing estimates.
If this is something that you’re interested in, the Distance Matrix Histogram endpoint is something you should explore.
Summary
In this blog post, we’ve looked at the Bing Distance Matrix API and explored some of the features and what’s possible with it. We’ve seen how easy it is to consume the Distance Matrix API using a tool like Postman.
Alternatively, if you’re interested in seeing how the API can be consumed using .NET, you can check out the Bing Maps REST Toolkit for .NET project on GitHub here.
Are you using Bing Maps in any of your solutions?
~~~
For reference:
You’ll need a Bing Maps Account and Key prior to making any requests, you can get one for free here .
The entire request that was sent to the Distance Matrix API endpoint via Postman:
https://dev.virtualearth.net/REST/v1/Routes/DistanceMatrix?origins=51.506420135498,-0.127210006117821&destinations=53.7947998046875,-1.54653000831604;51.506420135498,-0.127210006117821;53.4100914001465,-2.9784300327301&travelMode=driving&key=****YOUR%20BING%20KEY****&distanceUnit=mile&timeUnit=minutes">https://dev.virtualearth.net/REST/v1/Routes/DistanceMatrix?origins=51.506420135498,-0.127210006117821&destinations=53.7947998046875,-1.54653000831604;51.506420135498,-0.127210006117821;53.4100914001465,-2.9784300327301&travelMode=driving&key=****YOUR BING KEY****&distanceUnit=mile&timeUnit=minutes
You might also be wondering how to identify the latitude and longitude of each location, you can get this information by making a request to the following Endpoint:
http://dev.virtualearth.net/REST/v1/Locations?q=YOUR_LOCATION">http://dev.virtualearth.net/REST/v1/Locations?q=YOUR_LOCATION .
