Hands On

The Secret Lives of APIs — Chapter 1: Map Image & Routing

By Richard Süselbeck | 26 November 2019

Try HERE Maps

Create a free API key to build location-aware apps and services.

Get Started

One of the things I like to do is to highlight neat features in our APIs that you may not yet know about. For example, did you know that our Geocoder API can tell you which side of the road people drive on for any given location? (Click here to find out how!)

In this post, I'm going to look at the Map Image API. This API lives in the shadows of its bigger brothers, the interactive maps found in our Mobile and Web SDKs. However, it's both a powerful and lightweight API, which can be really useful in contexts where interactive maps don't make sense or simply cannot be used. Think of putting maps into emails or displaying locations on an Echo Show!

Like many of our APIs, the Map Image API also hides a few neat features you may not be aware of, so I've decided to write a series of short blog posts to bring these hidden features to light. Today we're going to look at the routing feature in the Map Image API.

Yep, the Map Image API can do routing! You may have already been aware that you can draw routes on the map when using the Map Image API. However, the Map Image API can actually be used to calculate these routes as well!

Let's have a look at how this works.

In order to calculate a route and display it on your map image, you need to use the waypoint parameters and provide a latitude and longitude for each parameter. In fact, beside your credentials, that's all you need to provide! The API will automatically size and zoom your image to fit the route and provide default values for everything you need, including the line style. Have a look at this example.


As you can see, we've added two waypoint parameters for the route. We've also added some optional parameters to make the result look nicer. Let's look at all of these in more detail:

  • waypoint0, waypoint1 are the start and end point for the routing calculation. Note that you can use more than two waypoints, so feel free to add a waypoint3, and so forth.
  • w and h set the width and height of the image in pixels. The map view will be automatically adjusted to ensure the full route is visible, even if you set only one of these parameters.
  • lc sets the color of the line showing the route. You can check the data types section of the documentation to see the various color formats you can use.
  • lw sets the width the line showing the route. We've set it a little wider than the default value of 4.
  • Note that you need to replace app_id and app_code with your own set of valid credentials. You can sign up for a free account to get these if you haven't done so yet.

And finally, here's our map image with the calculated route displayed.


Check out the full list of parameters for the routing resource in the documentation and stay tuned for more API secrets!