Reference layers overview
Reference layers give your data context: boundaries from a file, imagery from a tile server, a layer from ArcGIS or a WMS service, live weather or traffic. They are drawn as they are published and do not come from your data model.
Reference layers and data layers
A map in Icon Map Pro is a basemap, plus data layers, plus reference layers.
| Data layers | Reference layers | |
|---|---|---|
| Where the content comes from | The rows of your report, through the field wells | A file, a link or a service that you point the map at |
| What a row does | One row draws one thing | Rows are not needed. A reference layer draws with no fields at all |
| Click and select | Selects the row and cross-filters the report | Not selectable. Hovering can show a tooltip |
| Styling from data | Conditional formatting (fx) on most settings | Fixed styling, or styling by a property inside the file or service |
A reference layer is not joined to your data, but your data can still control it. Several settings take conditional formatting (fx), so a measure or a slicer can decide what is drawn:
- Visible on file, raster, WMS and ArcGIS layers shows or hides the layer.
- Filter Value on a file layer keeps only the features whose property matches your data. See Files and feeds.
- SQL WHERE Clause on an ArcGIS layer and CQL Filter (optional) on a WMS layer filter the service.
- The link itself can come from a measure on most layer types.
If you want shapes that are colored by your data and that cross-filter the report when clicked, use a data layer instead: Shapes from files, ArcGIS layers bound to data, Vector tiles or Icon Map Catalog layers.
Types of reference layer
| Type | Name in the Format pane | What it draws | How many |
|---|---|---|---|
| Files and feeds | GeoJSON / KML / CSV / WFS | Points, lines and polygons from a link or an uploaded file: GeoJSON, TopoJSON, KML, KMZ, CSV, shapefile, a WFS service or a PMTiles archive | 5 |
| Raster tiles and WMTS | Raster / WMTS Layer | Imagery or a tiled map from a tile template, a WMTS service or a Cloud Optimized GeoTIFF | 5 |
| WMS | WMS Layer | Map images from a Web Map Service | 5 |
| ArcGIS | ArcGIS Layer | A feature layer, a map, image or vector tile service, or a whole web map | 5 |
| Icon Map Catalog | Catalog card | Ready-made boundaries and places | 20, shared with catalog layers bound to data |
| Weather | Weather | Live weather from OpenWeatherMap | 1 |
| Traffic | Traffic | Live traffic flow or incidents from Azure Maps | 1 |
| Daylight | Daylight Terminator | Shading over the part of the world that is in darkness | 1 |
| Map labels | Map Labels | Place names drawn above your data | 1 |
File layers can also carry their own text labels. See Labels on reference layers.
Add a reference layer
The quickest way is the Layer Manager.
- In the Format pane, open the Layer Manager card and switch on Open Layer Manager.
- Select Add a layer, then Reference layer.
- Pick a tile, for example Files & feeds, Tiles & imagery, WMS or ArcGIS. Each tile shows how many of that type are in use.
- Follow the steps. For a link, select Check to have the link read and described before the layer is added.
- Select Add to map, then Apply changes.
The full walkthrough is in Add a layer.
Every reference layer can also be set up in the Format pane, and some settings are only there: conditional formatting (fx), filters, WMS authentication and Z-Index numbers. Open Format pane > Reference Layers > Layer Selection and switch on the type you want. A configuration group for that type then appears below.
More than one layer of a type
Files, ArcGIS, WMS and raster layers each have five slots. The Format pane shows the settings of one slot at a time.
- Files and ArcGIS layers: set Number of Layers (1 to 5), then choose the layer to edit in Apply settings to.
- WMS and raster layers: the first layer has its own group. Set Number of Additional Layers (0 to 4), then choose the additional layer to edit in Apply settings to.
Drawing order
Every layer on the map, reference or data, has a Z-Index. A layer with a higher Z-Index is drawn nearer the viewer. Reference layers and data layers share one scale, so a reference layer can sit under your data, between two data layers, or on top of everything.
| Layer | Default Z-Index |
|---|---|
| Daylight terminator | 450 |
| Map labels | 440 |
| Labels of a file layer | 370 |
| File layers | 365 |
| Weather | 360 |
| Raster layer 1 | 354 |
| Traffic | 350 |
| ArcGIS layers | 345 |
| Additional raster and WMS layers | 344 |
| WMS layer 1 | 255 |
For comparison, circles default to 405, images to 410 and data labels to 950. The defaults put imagery and boundaries under your data and place names above it.
To change the order, edit the Z-Index of a layer in its configuration group in the Format pane. Values run from 0 to 1000.
In the Layer Manager you do not need the numbers. The list shows every layer that is switched on, top first. Drag a row, or use Move up and Move down, and the Z-Index values are rewritten for you. See Edit, reorder and remove layers.
Zoom range and visibility
File, raster, WMS and ArcGIS layers each have a minimum and maximum zoom. Outside that range the layer is not drawn. Use this to show detailed boundaries only when the reader has zoomed in.
The same layer types have a Visible setting that takes conditional formatting (fx). Return "Yes" or "No" from a measure to show a layer only for a slicer choice or a bookmark.
Legend
File layers, WMS layers and ArcGIS layers can each have an entry in the legend. WMS entries use the legend image that the WMS server publishes, and ArcGIS entries use the layer's ArcGIS symbology. Switch entries on and name them under Format pane > Legend > Legend labels. See Legend.
Tips and limits
- Reference features cannot be selected and do not cross-filter the report.
- Links must start with
https://. - A layer that is read from a link is read by the browser of the person viewing the report. The server must allow requests from Power BI (CORS). See below for servers that do not.
- Uploaded files are stored in the report, so they work wherever the report does.
Servers that block Power BI
Some servers do not allow a Power BI visual to read them. The Icon Map proxy can fetch the layer on the map's behalf. It needs an Icon Map license key and proxied requests may consume additional usage credits.
File, raster and ArcGIS layers have a Use proxy when required switch. Each server is tried directly first, and only a server that blocks Power BI is read through the proxy. WMS layers have a Use CORS Proxy switch.
For what the proxy sends and how to switch it off for a whole report, see API keys, authentication and the proxy.