Icon Map


As new functionality is introduced into the visual, on occasions I will create a blog post to how to use the capability in more detail, or explain some of the potential uses.

Adding custom Mapbox layers from Mapbox Studio (23rd August 2021)

Another quick blog to answer a common support question - if you've created a custom map layer using Mapbox Studio - how do you use it with Icon Map?

Once you've created you map, using the Share Option from the Mapbox Studio toolbar...

Mapbox title bar

In the box that appears, select "Third Party" from the list of options in the "Developer resources" section, then select CARTO from the dropdown. You can then click the copy button for the Integration URL that is generated. This already contains your Mapbox token.

Mapbox options

Now in Icon Map, select Custom URI from the background layer dropdown and paste your integration URL into the Custom Background URI box. Set the min and max zoom levels (usually 1 - 22 for Mapbox), and your new map background should appear. Don't forget to add a custom attribution in the "Controls" settings if required by your background layer.

Power BI settings

Displaying tracks over time as line strings (16th August 2021)

I get quite a few requests for help where people are wanting to draw lines on the map representing a path that a vehicle or factory robot has travelled. Often this data arrives as a single coordinate pair on each row - one for each item at a point in time.

Unlike for example the Route Map custom visual, Icon Map however needs an origin and destination set of coordinates to be on the same row of data. This is to allow the flexibilty of mixing other object types on other rows of data. Therefore, to display these tracks in Icon Map the data will need some manipulation. Whilst it's usually straight forward enough to retrieve the previous set of coordinates, I thought I would show how to create the entire path as a Well Known Text LINESTRING object using DAX. If we create this as a measure, it means that we can dynamically alter the start and end times based on slicers. Drawing the whole path as a linestring also has the benefit that the line as a whole is selectable, rather than just a point in time.

Check out the example below. The source data is shown on the right. The DAX for the coordinates measure is shown, along with the resulting output, and how it can be displayed on Icon Map. The start and end times can be changed using the slicers at the top. Download the .pbix file to explore the map is configured.

Rendering different object types on the same map (15th August 2021)

It is possible to add objects of different types on the same map using Icon Map. The following types of object can be contained in your data and referenced on the map:

These can all exist on the map at the same time, it just depends on how you configure your data. The Power BI report below shows these different object types (except geoJSON) on the map with the data configuration in the table below. The report can be downloaded here so you can see how it has been configured.

All object types require the Category and Size fields to be defined (although not all will use the value in the size field).


Circles require the Longitude and Latitude fields to be populated. Destination Longitude and Latitude fields must be empty, and the Image / WKT expression based formatting setting must be empty. The size of the circle is specified using the Size field.


Lines require the Longitude and Latitude Fields and the Destination Longitude and Latitude fields to be populated. A circle at the origin will also be drawn using the size field for its radius, unless turned off in the object formatting settings. It is possible to draw an image at the origin and destination of the line using the object expression based formatting settings.


Images require the same configuration as circles, but with the Image / WKT expression based formatting setting configured with a URL. It must either be an HTTPS:// URL or start DATA:// for 64bit encoded data, or SVG images. The image size will be based on the value you specify in the Size field. Images can be rotated by sepcifying a value between 0 and 359 in the Object formatting settings.

Well Known Text

Icon Map supports the following Well Known Text Objects: POINT, MULTIPOINT, TRIANGLE, LINESTRING, MULTILINESTRING, POLYGON and MULTIPOLYGON. It does not currently support GEOMETRYCOLLECTION. To plot a WKT object on the map, the Category and Size fields must be populated, although the value from the size field is not used. The Image / WKT expression based formatting field under Objects must be populated with a valid WKT object definition.


GeoJSON shapes loaded from an external GeoJSON layer can be referenced in your data so that they can be selected, highlighted and formatted. The value in the Category field should relate to a property in the GeoJSON shape feature. The Size field must be populated but it not used. All other fields should be empty. The shape can then be formatted using the formatting settings. GeoJSON objects not referenced by your data can also be formatted using the GeoJSON formatting options.

Object behaviour

The behaviour of these objects can then be individually configured using expression based formatting to determine whether they are selectable, should show a tooltip, have a label.

Using Ordnance Survey maps with Icon Map (21st July 2021)

Icon Map has provided the ability to use your own map tile server for some years. However, this relied on the mapping provider supporting the WGS 84 / Pseudo-Mercator projected coordinate system as this was the only one supported by Icon Map. Today's release (3.1.0) adds support for additional coordinate systems, which opens up possibilities to use background maps not previously supported, such as Ordnance Survey Leisure Maps which use the British National Grid coordinate system.

In order to use Ordnance Survey maps, you'll first need an API key, which means signing up for an account at https://osdatahub.os.uk/. Most UK public sector organisations can use the Public Sector Plan with unlimited access. Once you've signed up, create a new project and add the OS Maps API to it. Select the "Leisure 27700" from the dropdown. You should now have the endpoints populated with the appropriate URLS with the key already included:

OS portal configuration

Now we have an API key, let's start to set up Icon Map in Power BI Desktop. Once you've added Icon Map onto your report, and added your data fields to the field wells, let's look at the background map configuration. In the Background Layers section, select "Custom URI" from the Background Layer dropdown. Copy and paste the "ZXY API Endpoint address" from the OS portal into the Custom Background URI textbox in Icon Map:

Icon Map background URI configuration

We now need to configure the minimum and maximum zoom levels. These are described in the technical specifications in the OS Maps portal: https://osdatahub.os.uk/docs/wmts/technicalSpecification.

OS Maps Tech specifications

With a premium plan, the Leisure maps have zoom levels from 0 to 9 so lets configure that in Icon Map:

Icon Map zoom levels

The background map tiles are now configured, but they still won't show as we haven't yet configured the British National Grid coordinate system that these tiles use. So in the Coordinate Reference System formatting options in Icon Map, select ESPG27700 (British National Grid) from the dropdown.

CRS configuration

We also need to add the appropriate attribution text at the bottom of our map. In the Map Controls formatting options paste "Contains OS data © Crown copyright and database rights 2021" into the Additional Attribution text box:

CRS configuration

Now we can start plotting data on our map. If your coordinates are in longitudes and latitudes, then configure the map as normal and your objects should appear over the OS Leisure Maps base layer:

Configured Icon Map showing circle data

If your data has coordinates in British National Grid format (BNG), then we need to turn on the Reproject Coordinates to WGS84 option in the Coordinate Reference System formatting options. Drag the X and Y coordinates from your data into the Latitude and Longitude fields in Icon Map.

Configured Icon Map showing circle data

At the moment it's not possible to chose which objects require reprojection or not - it's all or none. Let me know if more flexibility would be useful here. Currently reprojection is supported for GeoJSON layers, WKT objects, circles, lines and images.

Using a custom image as map background (12th July 2021)

There are times when you might want to create a map, but not use map tiles as the background. Perhaps it's a shop store plan, a hand drawn image or an aerial photograph. Icon Map now supports these of scenarios with a flat map simple co-ordinate system. Essentially where you'd otherwise use a latitude and longitude, instead you just use the X,Y coordinates that relate to a location on an image. This blog explains how to use the UK's Ordnance Survey's Leisure Maps which are only provided in OSGB 1936 / British National Grid. This will pre-populate the configuration for OS Leisure Maps. If you're using a different OS Map layer, then you will need to add the additional Resolutions for zoom levels 10 to 13. You can find these in the technical specification table shown above.

As an example, I've found this old 16th century plan of Old Amsterdam to use as a map background, on which we're going to highlight some features.

Old plan of Amsterdam

The map is available on wikimedia here: https://en.wikipedia.org/wiki/File:Castelloplan.jpg.

To ensure we use the largest version of it, we're going to use this version here: https://upload.wikimedia.org/wikipedia/commons/0/08/Castelloplan.jpg which is shown to be 3267 pixels wide and 2401 pixels high.

But, as always before we can do anything in Power BI, we need some data, so to get us started I've just created a simple one line spreadsheet for now and loaded it into Power BI.

Basic one line dataset

So now lets download the latest version of Icon Map from the downloads page and add it into Power BI as a custom visual. Now we're ready to go.

First we need to assign the data fields to the visual. Use the following configuration of fields:

field configuration

Add Icon Map onto your report canvas. Then we need to reference our plan of Old Amsterdam. To do this in Icon Map's formatting settings we need to change the Coordinate Reference System settings. Change the CRS to Simple (Y,X) and paste in the URL of the large image into Base Image:

formatting settings

You'll probably not see anything straight away on the map, but try zoom out as far as you can, and you should see something like this:

initial results

The first thing you'll probably notice is that we still have a map of the world showing. Let's get rid of that next. In the formatting options, under Background Layers set Background Layer to None

no background settings

Then we need to configure our map so that the zoom works better, our image isn't stretched and our circles etc appear in the right place on the image. In the Coordinate Reference System settings, we set the X Bounds Extent and Y Bounds Extent to match the width and hight of the image. We can also change the min and max zoom settings. These may need to be a negative number when using a flat map image:

new map settings

Then with these settings applied, our map should now be ready to start adding some data.

map looking better

The blue circle at the bottom left hand corner is our one line of data. We're plotting a circle at 10 pixels up and across from the bottom left hand corner. Let's move our circle to the inland end of the river and add a label. First we need to find the X,Y coordinates. I'm using Paint.Net to work out the coordinates. As I hover over the end of the river, you can see the X,Y coordinates in the status bar at the bottom, representing the location of the cursor. The end of the river shows around X:1930 Y:1128:

finding coordinates with Paint.net

However, don't forget that Paint.Net will show you the coordinates from the top left. We need coordinates from the bottom left, so take the Y coordinate away from the high of the map (2401 - 1128 = 1273). Let's update our Excel sheet with these new coordinates and refresh.

circle now at end of river

Let's add a label field to our data and add it onto the map. Don't forget to refresh your Power BI query.

label field added to data

In the map settings, turn on Labels and click the fx button next to the Text textbox.

label settings

In the dialog box that appears, select our new Label field.

expression based formatting dialog

Now our label should appear over the circle.

label on map

Finally, lets add a line to represent the river. For this we're going to create a linestring in Well Known Text (WKT) format using the points from along the river and add it as a new row of data. Note the X Y coordinate fields need to be blank, but still have a value in size:

linestring data

Lets refresh the query again, to bring it into Power BI. Now in the map formatting options, under Objects, click the fx button against Image / WKT and select the "Image or WKT" field from our data model.

Now our line should appear on the map. But it's a bit thin, so let's use the size field and add it to the Line / Border width field well:

linestring data

Also let's change the colour to a blue by changing the Border Color setting under Formatting:

formatting settings

And now we have our map with a line, circle and label on a zoomable custom map. The .pbix file and source Excel file can be downloaded if you want to see how it has been built.

final result

There are all sorts of possibilities achievable with this. This example was created using the same techniques as above playing images of trains at X Y coordinates, but combined with the Play Axis slicer.