Version

1.1.0.11 (latest)

Language

English

Shapes from files

This layer draws the shapes in a file, such as regions, postal areas or sales territories, and joins each shape to a row of your data. Matched shapes take their color from your data, show your tooltips and can be selected. Use it for choropleth maps when you have the boundaries as a file.

Regions colored from light to dark blue by a measure, with one region selected — Boundaries from a file, colored by a measure

What you need

Add these fields to the visual:

Field well	What to put in it
ID	A unique value for each row.
Feature Reference	The value that identifies the shape in the file, for example a region code.

Add fields to Tooltips for the values shown when you point at a shape.

These fields must be empty on the row, otherwise the row belongs to another layer: Image / WKT / GeoJSON, Longitude (X), Latitude (Y), Destination Longitude, Destination Latitude, Circle Size, Heatmap Weight and Cell (H3/S2/A5/Geohash) Weight. See Combine several layers in one map.

You also need the file itself. You can upload it into the report, or link to it. See Upload or link.

How the join works

Every shape in a file carries properties, for example a code and a name. The layer compares the value in Feature Reference with a property of each shape. Where they are the same, the shape is matched to that row.

A data table with a Feature Reference column is matched to the code property of shapes in a file. Matched shapes are colored, the unmatched shape is gray — Rows are joined to shapes by a shared key

A matched shape takes the row's formatting, tooltips and data label, and can be selected.
A shape with no matching row is unmatched. It is drawn in the unmatched colors, or removed if you turn on Remove Unmatched Shapes.
The comparison is exact. TX does not match tx, and 12 does not match 012. A stray space in either value stops a match.
If several rows have the same Feature Reference value, the first row is used. If several shapes have the same value, they all take that row's formatting.

The property to compare is set in Property to Match to Feature Reference Field. Left at Any, the layer works it out: it uses a property with the same name as your Feature Reference field if there is one, otherwise the first property whose value matches one of your rows. Naming the property is faster and avoids a match on the wrong property. Property names are case sensitive.

Add the layer

Add ID and Feature Reference to the visual.
In the Format pane, open Layer Manager and turn on Open Layer Manager.
Select Add a layer, then Data layer, then the Shapes (from files) tile.
In Where is the file?, choose Upload a file or Link to a file or service.
Upload: set the fill and outline in Style and options, then select Choose a file. The upload window opens. Choose your file, pick the property that matches your data in the Data bind column, and select OK. The Layer Manager comes back when the upload is done.
Link: paste the https:// link to the file and select Check. Choose the Property to match your data, set the style, then select Add to map and Apply changes.

The Shapes (from files) add wizard in the Layer Manager, at the step that asks where the file is — Adding Shapes (from files) in the Layer Manager

Opening the upload window saves any other changes waiting in the Layer Manager first. You can also pick Shapes (from files) in the "What kind of map are you making?" guide on an empty map. See Add a layer.

To color each shape from your data, select the fx button next to Format pane > Data Layers > Shapes (from files) - Fill Formatting > Fill Color.

The Layer Manager and the Format pane change the same settings. In the Format pane, a link is entered in Shapes (from files) - Configuration > File or Service Link, after you set Shapes (from files) - Setup > Source to URL.

Upload or link

	Upload a file	Link to a file
Where the file lives	Inside the report. It travels with the report and needs no network.	On a web server. The file is read when the report loads its data, so changes to the file appear in the map.
Formats	GeoJSON, TopoJSON, KML, shapefile, IMDF, PMTiles	See Linking to a file
Simplification	You choose how much to simplify as you upload.	The file is drawn as it is.
Needs	Nothing else.	An `https://` link, and a server that allows Power BI to read it.

Format pane > Data Layers > Shapes (from files) - Setup > Source chooses between Uploaded File and URL. It is one setting for all the layer's files.

Files you can upload

Format	File	Notes
GeoJSON	`.geojson`, `.json`	A FeatureCollection.
TopoJSON	`.json`	The first object in the file is read.
KML	`.kml`
Shapefile	`.zip`	The zip must contain the `.shp`, `.dbf` and `.prj` files.
IMDF (indoor maps)	`.zip`	See Indoor maps.
PMTiles	`.pmtiles`	A vector tile archive. See PMTiles archives.

KMZ and CSV files cannot be uploaded to this layer.

Coordinate systems. A shapefile is converted to longitude and latitude using its .prj file. A GeoJSON or TopoJSON file that names its coordinate system in a crs member is converted too. A file with no crs member is taken to be longitude and latitude (WGS84) already. KML is always WGS84.

Size limits

GeoJSON, TopoJSON, KML and shapefiles: the file can be saved when it is 100 MB or less as uncompressed JSON after simplification. Above that, OK is unavailable and the window shows "File too large to save in the Power BI report. Simplify further or consider using vector tiles or a catalog layer."
PMTiles: the archive can be at most 25 MB.

Large files slow the report down well before these limits. The upload window suggests a level of simplification that brings the file to 30 MB or less, and a smaller file is better still. For very large boundary sets use Vector tiles or an Icon Map Catalog layer.

The upload window

After you drop or choose a file, the window shows a preview that you can zoom and pan, and these controls:

Simplification - from Full detail to Most simplified. Simplifying removes points from the outlines to make the file smaller. Borders shared by two shapes stay shared. Select the Suggested badge to apply the suggested amount.
Decimal precision - the number of decimal places kept in each coordinate. Fewer places make a smaller file.
Feature properties - every property in the file with an example value. Clear the check box of properties you do not need, and they are left out of the stored file. In the Data bind column, pick the property that holds the values in your Feature Reference field, or leave (Auto detect) selected.
Original and After show the size before and after your choices.

Select OK to store the file in the report. To replace a file, upload another into the same place. Remove existing file in the upload window clears it.

Linking to a file

The link must point to a file on a server that allows Power BI to read it (CORS). If the file names a coordinate system in a crs member, it is converted to longitude and latitude. The link accepts conditional formatting, so a measure can supply it.

A link can be a GeoJSON, TopoJSON, KML or KMZ file, a CSV file with latitude and longitude columns, or a WFS service. In the Format pane it goes in File or Service Link.

If the server does not allow Power BI to read the file, Check in the Layer Manager says so and offers Read it through the Icon Map CORS proxy (only for servers you trust). The proxy is never offered or used when Airgapped Environment is on or your license rules it out. Otherwise, download the file and upload it instead.

Color the shapes

From your data with conditional formatting

Select the fx button next to Fill Color. You can use a gradient, rules or a field value, as in any Power BI visual. See Conditional formatting. The outline color, transparency and width take fx in the same way.

Fill styles, points and 3D

Fill Style can be Solid, Hatched (diagonal stripes, with Hatch Width) or Pattern (a pattern from the library opened with Show Pattern Library, or an image URL in Pattern / Image URL).
Point features in the file are drawn as circles. Circle Size sets the radius in pixels.
Line features are drawn with the outline color, width and transparency.
Polygon Extrusion Height raises matched polygons into 3D blocks, in meters, up to 1,000,000. It accepts conditional formatting, so the height can come from a measure. Tilt the map to see the height.

Unmatched shapes

Shapes with no matching row are drawn with the settings in Shapes (from files) - Unmatched Formatting, gray by default. They cannot be selected. With Override formatting for unmatched turned off, an unmatched shape that carries its own fill color in the file keeps that color. Turn on Remove Unmatched Shapes to hide them altogether.

Drill down between files

A shapes layer can hold up to five files. Display multiple layers as in Shapes (from files) - Setup decides how they are used:

Drill-Down - one file is on the map at a time, and Power BI's drill buttons move between them.
Multiple Layers - all the files are drawn together.

The hierarchy in the ID field well, Country then Region then District, with each level using its own file — Each drill level uses its own file

To set up drill-down:

Put a hierarchy in the ID field well, for example Country, then Region, then District.
In Shapes (from files) - Setup, leave Display multiple layers as on Drill-Down and set Number of Drill-down Levels to the number of levels.
Choose a level in Apply settings to:. The groups below then show that level's settings. Upload or link its file, and set its property to match and its formatting.
Repeat for each level.

When a report user drills down, the map switches to the file for that level. Level 1 is used at the top of the hierarchy, level 2 after drilling once, and so on. Each level has its own file, property to match, formatting and tooltip settings.

For Feature Reference, either add one field that holds the right key at every level, or add one field for each level in the same order as the hierarchy. With several fields, the first is used at level 1, the second at level 2, and so on.

With links, a level that has no link of its own uses the link of level 1.

A map drilled from regions into the districts of one region — After drilling down, the level 2 file is drawn

Several files at once

Set Display multiple layers as to Multiple Layers and set Number of Layers. Each layer has a Feature Reference Field setting that picks which of your Feature Reference fields it is joined to, and its own Z-Index for the drawing order. A row is drawn when it has a value in the Feature Reference field of at least one layer.

In the Layer Manager, adding a second Shapes (from files) layer to a map with one file switches the layer to Multiple Layers. A map already set up for drill-down keeps drill-down, and the new file becomes the next level.

PMTiles archives

A PMTiles archive holds shapes as vector tiles, already simplified for each zoom level. Uploading one lets you store much more detailed boundaries in a report than a GeoJSON file of the same size.

The archive can be at most 25 MB and must hold vector features, not images.
In the upload window, choose the Layer to use. An archive can hold several layers, and one is drawn for each uploaded archive. Then choose the Property to match on, or leave Any property.
There is no simplification or precision control, because the archive is already simplified.
When matching, spaces around the values are ignored.
The map zooms to the matched shapes, not to the whole archive.

For archives larger than 25 MB, host the archive and use the Vector tiles layer.

Indoor maps (IMDF)

An IMDF archive is a zip that describes the inside of a building: units, walls, openings, fixtures, levels and amenities. It is imported at full precision, with no simplification. The shapes keep the file's own colors.

Import IMDF (Indoor Map) files in 3D, in the upload window, is on by default. It raises the walls and stacks the floors. Turn it off for a flat floor plan.
When the file has more than one level, a level picker appears on the map so report users can choose a floor. In 3D the picker also has a button that shows every level at once.

Selection, tooltips and labels

Click a matched shape to select its row and filter the rest of the report page. Hold Ctrl or Shift to add to the selection. The shapes you did not select fade to 80% transparency by default, set by Unselected Items Transparency in Format pane > Selection > Formatting. See How Icon Map Slicer filters.
Pointing at a matched shape shows the fields in Tooltips. Add Property to Tooltip adds the matched property. Add All Properties to Tooltip adds every property of the shape.
Add Tooltips to Unmatched Shapes shows the file's properties on unmatched shapes. Turn on one of the two settings above as well, so there is something to show.
Matched shapes can carry a data label. See Data labels.
The map zooms to the matched shapes whose rows have Include in Auto Zoom set to Yes.

Settings

All settings are in Format pane > Data Layers. With more than one level or layer, the group titles include the level or layer number, and the groups show the one chosen in Apply settings to:. For example, Shapes (from files) - Level 2 Configuration or Shapes (from files) - Layer 2 Fill Formatting. Settings marked fx accept conditional formatting.