Raster tiles, WMTS and WMS
Raster layers draw pictures of a map over the basemap: aerial imagery, a scanned plan, a flood model, a published map service. Use a raster layer for a tile template, a WMTS service or a Cloud Optimized GeoTIFF, and a WMS layer for a Web Map Service. You can have up to five of each.
Which one to use
| You have | Use | Looks like |
|---|---|---|
| A tile template | Raster layer | https://tile.example.com/{z}/{x}/{y}.png |
| A WMTS service | Raster layer | The service's GetCapabilities link |
| A GeoTIFF file on a web server | Raster layer, with Cloud Optimized GeoTIFF (COG) on | A link ending .tif or .tiff |
| A WMS service | WMS layer | https://example.com/geoserver/wms |
All links must start with https://.
Add a raster layer
- In the Format pane, open the Layer Manager card and switch on Open Layer Manager.
- Select Add a layer, then Reference layer, then the Tiles & imagery tile.
- Paste a tile template, a WMTS GetCapabilities link or a GeoTIFF link, and select Check.
- Read the result. A tile template is tested by loading one tile. A WMTS link shows the layer that will be drawn. A GeoTIFF link is recognized from its file extension.
- Set the transparency under Style and options, select Add to map, then Apply changes.
For some tile servers the check cannot read the test tile even though the map can draw the layer. The wizard says so and lets you add the layer anyway.
To do the same in the Format pane:
- Open Reference Layers > Layer Selection and switch on Raster / WMTS Layer.
- In Raster / WMTS - Configuration, paste the link into Tile Template or WMTS Link.
- For a GeoTIFF link, switch on Cloud Optimized GeoTIFF (COG).
WMTS services
Paste the GetCapabilities link of the service. The map reads the capabilities and draws the service's tiles in the Web Mercator tile scheme (GoogleMapsCompatible, EPSG:3857). A note under the link names the layer being drawn.
A WMTS layer that is not published in Web Mercator cannot be drawn. The map tells you when that is the case.
Servers that block Power BI
If the check reports "This server does not allow Power BI to read it", tick Read it through the Icon Map CORS proxy (only for servers you trust). In the Format pane this is the Use proxy when required switch, which appears once the map has found that the server blocks Power BI. The server is always tried directly first. See API keys, authentication and the proxy.
More raster layers
Set Number of Additional Layers (0 to 4). An Additional Raster Layer group appears with the same settings. Choose which additional layer it shows in Apply settings to.
Raster settings
Format pane > Reference Layers > Raster / WMTS - Configuration
| Setting | What it does | Default |
|---|---|---|
| Tile Template or WMTS Link | A {z}/{x}/{y} tile template, or a WMTS service link. Takes conditional formatting (fx) |
Empty |
| Use proxy when required | Reads the tiles through the Icon Map proxy when their server blocks Power BI. Shown once a block has been found | Off |
| Setting | What it does | Default |
|---|---|---|
| Tile Size | The size of the server's tiles in pixels, 256 to 4096 | 256 |
| Cloud Optimized GeoTIFF (COG) | Switch on when the link is a GeoTIFF file | Off |
| Transparency | 0 is solid, 100 is invisible | 20 for the first layer, 0 for additional layers |
| Min Zoom | The layer is hidden when the map is zoomed out past this level | 0 |
| Max Zoom | The layer is hidden when the map is zoomed in past this level | 22 for the first layer, 24 for additional layers |
| Visible | Shows or hides the layer. Takes conditional formatting (fx) | Yes |
| Z-Index | Drawing order, 0 to 1000. Higher is nearer the viewer | 354 for the first layer, 344 for additional layers |
| Number of Additional Layers | How many more raster layers the map has, 0 to 4 | 0 |
Add a WMS layer
A WMS server draws map images on request. The server must use an https:// address and must be able to serve the layer in Web Mercator (EPSG:3857).
- In the Layer Manager, select Add a layer, then Reference layer, then the WMS tile.
- Paste the WMS service address and select Check. The wizard reads the service and reports how many layers it offers.
- Under Details, pick the Layer to draw. The list can include the service's group layer as well as its individual layers.
- Select Add to map, then Apply changes.
Authentication, filters, styles, custom parameters and the proxy are set in the Format pane. If the service needs any of them, set it up in the Format pane as described below.
To add a WMS layer in the Format pane:
- In the Format pane, open Reference Layers > Layer Selection and switch on WMS Layer.
- In WMS - Configuration, paste the service address into WMS Server URL. Either the plain address or its GetCapabilities link works.
- If the service needs a sign-in, set Authentication Type and fill in its fields. See WMS authentication.
- Pick the layer in Layer. The list is read from the service.
- Pick the image Format. Use a format that supports transparency, such as image/png, unless the layer is meant to cover the basemap.
While Manual configuration is off, the map asks the WMS server for its list of layers as you edit the report. Once the layer is working, switch Manual configuration on. The layer and format you picked are kept as text and the extra requests stop.
If the layer list cannot be read
If the pane shows "Unable to read layers from WMS server.", the map could not read the service's capabilities. Check the address and the authentication first. Then:
- If the server does not allow Power BI to read it (CORS), switch on Use CORS Proxy. The requests then go through the Icon Map proxy, which needs an Icon Map license key and may consume additional usage credits. The proxy is not used when Airgapped Environment is on. See API keys, authentication and the proxy.
- If the server draws maps but does not publish its capabilities, switch on Manual configuration and type the Layer name and Format (for example
image/png) yourself.
Filter a WMS layer
- CQL Filter (optional) sends a CQL filter with each request, for servers that support it, such as GeoServer. It takes conditional formatting (fx), so a measure can filter the layer to the current selection.
- Custom Parameter Name (optional) and Custom Parameter Value (optional) add one parameter of your choice to each request. The value takes conditional formatting (fx).
- For an ArcGIS service, set Authentication Type to ArcGIS. Query Filter (optional for image sources) and LayerDefs Filter (optional) then replace the CQL filter.
More WMS layers
Set Number of Additional Layers (0 to 4). A WMS Additional Layer group appears. Choose which additional layer it shows in Apply settings to.
Additional layers are always set up by hand: type the Layer name and the Format as text. To find the names, set the service up as the first WMS layer and read them from its Layer list.
WMS authentication
Set Authentication Type on each WMS layer.
| Authentication Type | Use it for | Fields |
|---|---|---|
| None | Public services | |
| ArcGIS | WMS services hosted in ArcGIS. Your ArcGIS credential is added to each request. Set it up first: see Connect to ArcGIS | Query Filter (optional for image sources), LayerDefs Filter (optional) |
| Basic (Username and Password) | Servers that use basic authentication | Username, Password |
| Token / API Key in URL | Servers that take a key as a parameter of the address | Authentication Property Name (eg apikey or token), Authentication Property Value |
| Token / API Key in Header | Servers that take a key as a request header | Authentication Property Name (eg apikey or token), Authentication Property Value |
| OAuth 2.0 | Servers that issue a token for a client ID and secret | OAuth2 URL, OAuth2 Client ID, OAuth2 Client Secret, OAuth2 Scope (optional), Additional Header Name (eg apikey or token), Additional Header Value |
For a key in the URL, take the key out of the address. If the service's example address is https://example.com/wms?request=GetCapabilities&apikey=abc123, enter the address without &apikey=abc123 in WMS Server URL, apikey as the property name and abc123 as the property value.
Passwords and client secrets are stored encrypted in the report and are shown as dots once entered.
OAuth 2.0 fetches the token through the Icon Map proxy, so it needs an Icon Map license key.
A credential saved in a report is used for everyone who opens the report. Use an account or key that only has access to what the report should show.
WMS settings
Format pane > Reference Layers > WMS - Configuration
| Setting | What it does | Default |
|---|---|---|
| WMS Server URL | The address of the WMS service. Takes conditional formatting (fx) when Manual configuration is on | Empty |
| Use CORS Proxy | Sends the layer's requests through the Icon Map proxy, for servers that do not allow Power BI to read them | Off |
| Authentication Type | How the map signs in to the server. See the table above | None |
| CQL Filter (optional) | A CQL filter sent with each request. Takes conditional formatting (fx). Not shown for ArcGIS authentication | Empty |
| Custom Parameter Name (optional), Custom Parameter Value (optional) | One extra request parameter. The value takes conditional formatting (fx) | Empty |
| Manual configuration | On: you type the layer, format and style. Off: the layer and format are picked from lists read from the server | Off |
| Layer | The layer to draw. In manual mode it takes conditional formatting (fx) | Empty |
| Format | The image format: image/png, image/jpeg, image/svg+xml or image/vnd.jpeg-png, where the server offers them | image/png |
| Style (optional) | A named style that the server offers for the layer. Takes conditional formatting (fx). On the first layer it is shown when Manual configuration is on | Empty |
| Transparency | 0 is solid, 100 is invisible | 10 for the first layer, 0 for additional layers |
| Minimum Zoom | The layer is hidden when the map is zoomed out past this level | 0 |
| Maximum Zoom | The layer is hidden when the map is zoomed in past this level | 24 |
| Z-Index | Drawing order, 0 to 1000. Higher is nearer the viewer | 255 for the first layer, 344 for additional layers |
| Visible | Shows or hides the layer. Takes conditional formatting (fx) | Yes |
| Number of Additional Layers | How many more WMS layers the map has, 0 to 4 | 0 |
WMS legends
New in 1.1.0.11
Each WMS layer can show the legend image that its server publishes. Switch the legend on in the Legend card, then use WMS layer {n} in legend and WMS layer {n} title under Legend labels to include and name each layer. A legend image is shown for layers with Authentication Type set to None or Token / API Key in URL. See Legend.
In the Layer Manager
Select a raster or WMS layer in the Layer Manager to edit its main settings.
| Layer | Settings |
|---|---|
| Tiles and imagery | Tile template or WMTS link, Cloud Optimized GeoTIFF, Tile size, Visible, Transparency, Visible at zoom |
| WMS | WMS service address, Layer, Image format, Visible, Transparency, Visible at zoom |
Replace the link or file swaps the source and keeps the layer's place and style. For a WMS layer it is also the way to pick a different layer from the service's list.
Tips and limits
- WMS layers are requested in Web Mercator (EPSG:3857). A server that cannot serve that projection cannot be drawn.
- The WMS version is taken from a
version=parameter in the address you paste. Without one, version 1.1.1 is used. - Parameters in a pasted WMS address that are not part of the standard request, such as a map or workspace name, are kept and sent with every request.
- Raster and WMS layers are pictures. They have no tooltips and cannot be selected.
Related
- Reference layers overview
- ArcGIS layers
- Other basemap providers - use a tile server or WMS service as the basemap instead
- API keys, authentication and the proxy