Blog

This article was originally written in 2018 and there have been a number of additions to the API since then.

Azure Maps is a suite of services for working with constantly changing location-based information. These cover everything you’ll need whether managing systems with moving elements (Route, Traffic), finding contextual information (Search, Time Zone) or presenting location to users (Render, Map Control).

Setting up an account is easy, as with all other Azure services you create and manage your Maps account through Azure Portal. This gives you a unique subscription key to pass with each API call. Azure Portal lets you monitor usage and handling billing through your Azure subscription. You can get started in seconds and there is a generous free usage quota per month.

On the move

A courier business needs to keep its trucks moving as efficiently as possible to minimize fuel costs and cut down time taken to deliver goods. This requires the ability to both track packages and the vehicles they travel on in real-time and plan complex routes for the drivers to follow.

On point

Azure Maps Search service can be used to get physical map coordinates for each delivery address. You can either pass a free form query containing a full or partial address or use the structured API for more direct matches.

https://atlas.microsoft.com/search/address/json?subscription-key={subscription-key}&api-version=1.0&query=One Microsoft Way&countrySet=US

This process is known as geocoding and once you have a latitude and longitude you can plot the location on a map or use it to build a route.

En route

Once a set of coordinates is available for a particular delivery area they can be passed to the Route service to calculate the best driving route. You can calculate routes with up to 50 waypoints. For up to 20 waypoints you can have the Route service calculate the best order for you. But it doesn’t stop there, there are many more options available to improve the route calculation. If route calculation is done just-in-time you can request that the service use its traffic data to help decide the route to use. Traffic data is updated every few minutes and could save in both wasted fuel and time by avoiding problems.

https://atlas.microsoft.com/route/directions/json?subscription-key={subscription-key}&api-version=1.0&query=56.551095,14.161954:55.73535,9.131333&traffic=true&instructionsType=text

In order to support long lists of waypoints you can send the request as a POST and write the lat/long points in the body of the request using a GeoJSON document.

You can specify vehicle information in great detail, such as weight, height, and width which will exclude unsuitable roads. There is also built in support for hazardous cargos so you can specify standard Hazmat codes to exclude restricted roads. You can also supply fuel consumption information for combustion or electric engines.

On the way

Having the best route planned is one thing, to make use of it you need to provide instructions to the driver. You can request either coded instructions which you can render locally or full text instructions in the requested language with optional HTML style tags for context.

"message": "Keep left at <street>Taulovmotorvejen</street>/<roadNumber>E20</roadNumber> toward <signpostText>Kolding</signpostText>"

The “instructionsType” parameter to a Route API call specifies the flavor of instructions to return.

On time

A customer who has a package in transit will want to be able to track its progress. The package probably has a log with its progress across the globe but to present this to a customer you probably need to convert time stamps into local time for each point. The Time Zone service will allow you to do this. It handles daylight saving changes and the service is backed by the IANA time zone database which is regularly updated. It requires a lat/long coordinate and a UTC timestamp as reference:

https://atlas.microsoft.com/timezone/byCoordinates/json?subscription-key={subscription-key}&api-version=1.0&options=zoneinfo&query=-13.606902,-172.486005&timeStamp=2015-01-01T12:00:00Z

Your customer will see that their delivery arrived at their local depot at 4am and they’ll be confident it’ll be delivered that day. The Search service also supports multiple languages which means you can customize the addresses you display to the customer based on their language preferences.

On screen

In the back office of your business you need to be able to see that your deliveries are progressing smoothly. You can easily build a map view into your dashboard using the Azure Maps Control. This is a JavaScript control you can easily integrate with an HTML user interface.

It has a simple API for adding pins and drawing a variety of geometric shapes. You can even toggle live traffic display with a single line of code. You don’t have to write custom code to load individual map tiles and handle zooming and panning – all this functionality is built right into the control. It uses vector maps for smooth zooming and has a modern uncluttered design. You just need to add a stylesheet and script reference to the Azure Maps control: –

<link rel="stylesheet" href="https://atlas.microsoft.com/sdk/css/atlas.min.css?api-version=1.0" type="text/css" />
https://atlas.microsoft.com/sdk/js/atlas.min.js?api-version=1.0

Then, within the body of your HTML, create an element and give it a unique id (e.g., “map”).

<div id="map">
    <script>
        var MapsAccountKey = "<_your account key_>";
        var map = new atlas.Map("map", {
            "subscription-key": MapsAccountKey,
            center: [47.59093,-122.33263],
            zoom: 12
        });
    </script>
</div>

The parameters passed to the Map constructor are the id within the document (in this case “map”), then your subscription key, a point to center the map on, and a zoom level.

Onwards

Here we’ve only looked at a few of the uses for Azure Maps, there are many more possibilities. Although we’ve discussed moving vehicles you might instead have a collection of fixed installations. Imagine you were monitoring the properties of distributed sensors and you wanted to visualize the status on a map to see if problems are isolated or following a trend. You could make use of the vast database of addresses to validate data entry.

The Azure Maps services have been designed to interoperate with a number of open standards such as GeoJSON and can be integrated with other geographic information systems. The RESTful API means they can easily be consumed from a range of languages across a spectrum of devices. You can read about all the Azure Maps services in more detail in the official documentation.