Hands On

The Secret Lives of APIs — Phase III: Map Image & Statistics Graphs

By Richard Süselbeck | 31 January 2020

One of the things I like to do is highlight neat API features you may not yet know about. For example, did you know that the HERE Map Image API can generate the logos of public transport companies? (Click here to find out how!)

In this blog post, we'll be taking yet another 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 personalized maps into your customers’ emails or visualizing a response in an Alexa skill card!

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 how to display statistics graphs like circles and bar charts using the Map Image API. Let’s have a look at an example map.

secrets3-circles

This map shows the annual passenger volume at the largest airports in Germany, Portugal, Finland and Romania, visualized using circle graphs. In addition to these graphs, there are also some text labels on the map. The objects are displayed using the respective national colors. The map is created using the following API call:


https://image.maps.ls.hereapi.com/mia/1.6/stat
&?apiKey={{apiKey}}
&w=1200
&h=700
&t=1
&f=0
&ot=0
&o0=50.04925,8.57255;70;red;black
&o1=38.77012,-9.12868;31;maroon;green
&o2=60.31852,24.96671;22;blue;white
&o3=44.57036,26.07558;15;navy;red
&tx0=50.04925,8.57255;FRA 70M;yellow
&tx1=38.77012,-9.12868;LIS 31M;green
&tx2=60.31852,24.96671;HEL 22M;white
&tx3=44.57036,26.07558;OTP 15M;yellow

Let’s look at the various parameters in detail.

  • apiKey: This key is part of your application credentials. If you don’t have a set of credentials yet, go ahead and sign up for our Freemium account here on the portal.
  • h/w: As you would probably guess, these are the dimensions (height/weight) of the image in pixels.
  • f: This represents the image format. In this case, we’ve chosen PNG, though other formats like JPG (1) or SVG (5) are also available.
  • t: This allows you to choose the map scheme. In this case, we’ve chosen a satellite map. Check the documentation for more options and remember that you can use the style parameter for even more customization options.

Of course, none of these parameters are new to you if you’ve ever used to Map Image API before. It’s the rest of them that generate the charts and are therefore of special interest for us.

  • ot: This flag allows you to select whether you want to display circle or bar charts. The default (0) is circle.
  • o0, 01, …: Each of these parameters defines a circle or chart object on the map. There are up to four fields you can set here (and we've set them all). These are:
  1. coordinate: Latitude and longitude of the object. In our example these are the locations of the four airports. This is required.
  2. value: The statistical value that the chart object represents. Can be integer or float. In our example we’ve set the passenger volume in millions. This is required.
  3. fill color: The fill color for the chart object. Optional.
  4. outline color: The outline color the chart object. Check the documentation for details on color formats. (If you’re heraldically inclined you may wish to replace my crude color approximations with more accurate AARRGGBB colors. If you care about aesthetics, you may wish to change the colors entirely.) Also optional. Omit this if you're really into default blue charts.

We’ve also added some text labels on the map using the tx0, tx1, … parameters to increase readability. Note that since these aren’t directly tied to the chart objects, we’ll refer you to this example for more details.

Before we finish, let’s have a quick look at an example with bar charts.

 

secrets3-bars

 

This map shows the same data, but as bar charts. We’ve omitted the text labels here to keep the corresponding API call short:


https://image.maps.ls.hereapi.com/mia/1.6/stat
&?apiKey={{apiKey}}
&o0=50.04925,8.57255;70;red;black
&o1=38.77012,-9.12868;31;maroon;green
&o2=60.31852,24.96671;22;blue;white
&o3=44.57036,26.07558;15;navy;red
&w=1200
&h=70
&t=1
&f=0
&ot=1
&olp=1
&shd=1

First, note that we’ve set ot to 1, which means we are generating bar charts. Next, let’s look at the additional parameters we’ve used in this call.

· olp: This parameter lets you define the location point for the chart object. For circles it made sense that its location (the airport) was in the center (0), but for bar charts it makes more for this to be at the bottom, so we’ve set this to 1.

· shd: Did you notice the drop shadows behind the bar charts? This parameter turns them on or off. This also works for circles.

Until next time, when we will reveal the secret life of the Map Image API with heatmaps!