This getting started guide provides guidance on how to install and use the OS Maps for Power BI Visual. Topics covered in the guide include:

• Installation

• Adding an OS basemap

Core concepts

The visual allows you to add up to three layers to the map at once, which can be styled and symbolised separately. There is a marker points layer, a features layer, and a reference layer.

The marker points layer can contain point-based data from your Power BI data model, which can be supplied either as coordinates, postcodes, or UPRNs.

The features layer can contain point, line, or polygon data which can be supplied in one of three ways: directly from your data model as WKT or GeoJSON; geocoded from GSS codes in your data model; or matched from a column in your data to features in a spatial dataset that you can upload into the visual.

Finally the reference layer can contain reference data such as administrative boundaries which are geocoded from GSS codes but are not matched to any specific data from your data model.

Creating and styling map layers

The pages below include detailed guides on creating and styling a point map within the visual:

Follow the steps below to add an OS basemap:

Installing OS Maps for Power BI Visual is straightforward and requires only a few steps. You should have received a link to Dropbox that contains a .pbiviz file with the name of your organisation on it. The .pbiviz file contains the visual that you'll import into Power BI.

Installing OS Maps for Power BI Visual

Once you have added features to the Features Layer, you can control how they are displayed. You can control the colour of features according to values of a field from your Power BI data, or all together, as well as adjusting the opacity of features and size of any points present.

Feature display is controlled by selecting the "Features Layer" dropdown under the Symbology Settings pane of the Format Visual controls:

The controls that appear under this pane will vary depending what other data you have added to the visual. If you have not added any data to the Features Layer: Colour field, you will not see the "Min feature fill colour" and "Feature % clip" controls.

Varying the colour of features

The colour of features in the Features Layer is controlled in the same way as points in the Marker Points layer, so the instructions for the Marker Points Layer on the apply equally to the Features Layer.

This allows you to create several different types of map:

• By mapping polygon features and adding a numeric field (or field summary) to the Features Layer: Colour field you will create a choropleth map.

• By mapping polygon features and adding another type of field, you will create a categorical (or chorochromatic) map. Categorical data in the Features Layer will be coloured according to the same process as in the Marker Points Layer.

• Point and/or line features can also be symbolised with colours varying according to a numeric or categorical data field.

Controlling the appearance of unmatched features

If you have chosen to to populate the Features Layer, you may have features in your uploaded data which do not match any value provided in the data model through the field added to the Features Layer: Linking identifier field well.

If so, you can choose to include these unmatched features on the map. They will be styled using a single symbol, which you can configure using the Unmatched uploaded features dropdown pane of the Symbology Settings:

This allows a couple of advanced mapping features.

Firstly you could combine this with a slicer to create a map that allows interactive highlighting of a particular subset of features, whilst leaving all the other features visible:

Secondly, you could populate the features layer by using one of the other two means (via GSS codes or via geometry from the data model), and then upload a separate dataset which will then be entirely unmatched (because you are not adding data to the Linking Identifier field). This allows you to effectively display an entirely separate dataset for contextual information:

The reference layer feature provides a way to consistently display administrative polygons/boundaries (e.g. LSOAs, wards, etc.) regardless of how point data is filtered on the page.

The reference layer feature can be found under the Visualisations pane > Format Visual > Reference Layer Settings

For a reference layer to be generated, the relevant GSS codes need to be input into the ‘GSS Codes for Reference Layer’ text box.

GSS codes can be copied and pasted directly from a spreadsheet into the text box, and it will automatically work.

Once the codes have been input, the visual should update after a few seconds with the relevant polygons displayed on the map as a reference layer that is not linked to any other data used in the visual.

You can then style the reference layer features using the appropriate dropdown under the Symbology Settings pane:

As described on the , the OS Maps for Power BI visual supports two main data-driven map layers: a Marker Points layer and a Features Layer. (Additionally, there is a separate reference layer which is not linked to the Power BI data).

However in order to display data in both of these layers simultaneously, you need to carefully structure your data in a certain way. This page explains what is needed, and why.

Understanding the limitations of visuals

As with all custom Power BI visuals, the OS Maps for Power BI visual does not have any access to your Power BI data model. It only ever "sees" the fields (or summaries) that are added to the field wells on the Build Visual pane. Every time the visual is refreshed, Power BI calculates and passes the latest representation of these fields into the visual to be displayed.

Loading spatial data into the visual using the Upload Manager provides an alternative means to add your own polygons or other geometries onto the map, and have them symbolised according to values from your Power BI data model.

Follow the steps below to add points to the marker points layer of the map. Note that the three ways of adding points (via coordinates, postcodes, or UPRNs) are mutually exclusive; you can only use one at once.

Adding points on a map using Longitude / Latitude or Eastings / Northings

If your data has a list of Longitude / Latitude or Eastings / Northings, then you’re able to plot these on a map by simply dragging and dropping the relevant columns in your data into the Points: X and Points: Y fields of the visual.

Importing data to the data model

If you follow the steps described in you will be mapping geometries that are actually part of your Power BI data model. They will be provided to the visual by Power BI every time the visuals in the report are updated, in line with whatever slicers and filters are currently active.

Depending on how your data model is constructed, the geometries may be coming from some central repository within your organisation and so be kept up to date automatically along with the other data in your report.

The visual has been designed so that clicking on a point or polygon on the map displays a pop-up with additional useful information about that location instead of filtering data in other visuals on the page.

Instead of clicking to select features, the lasso tool allows you to filter the data on other visuals based on a selection taken from the map.

Once you have added points, you can control how they are displayed. For the marker points layer, you can control both the size and the colour of points according to values of a field from your Power BI data, or by changing all points together.

Point display is controlled by selecting the "Markers (points-only) Layer" dropdown under the Symbology Settings pane of the Format Visual controls:

The controls that appear under this pane will vary depending what other data you have added to the visual - you will not necessarily see all the controls visible in the image above.

Changing the size or colour of all points together

If you have not added any data to the point colour or point size fields on the Build Visual pane, then the symbology settings pane will appear like this. You can change the colour, opacity, size, and border thickness of all point markers. Note that the colours appearing in the colour picker are taken from the current Power BI report theme.

Varying the size of points

It’s quite common that you might want to vary the size (radius) of the points on a map to represent an increase in occurrence or density (for example, larger points represent a greater number of crimes at a location).

To do this, having plotted points on a map, drag a data column containing numeric data into the Points: Size field of the visual. Then, if there are multiple points at each location, you can click on the downward arrow of that field and select an appropriate summary. Now the size of your points will be based off the value of the single data point at that location, or a summary of all the values at that location. (Note that if there are multiple points at one location and no summary is applied, a warning will be shown in the notifications pane).

At this point the symbology pane will update to show controls allowing you to control the range of sizes of the points on the map, instead of a single size control. Additionally the map legend will update to show the size of points as they appear on the map.

The "Points size % clip" slider allows you to reduce the effect of outliers on the appearance of points. The values above and below these percentiles will be excluded from the scaling calculation.

See an example below showing a combination of categorical data (crime type) and point size variation (count of crime).

Varying the colour of points

You can also vary the colour of points on the map according to a variable from your Power BI data. Add the appropriate field to the Points: Colour field of the visual to do this. This can be a numeric field or a non-numeric field.

If you add a numeric field, the points will be coloured by ramping / interpolating colours between two endpoints that you can choose on the Symbology Settings pane. If you add any other field, this will be treated as "categorical" data and each unique value will be given a distinct colour. This would be appropriate for data that's divided into groups, such as age, gender, occupation, etc.

Adding clickable point pop-ups

Additional information about a point can be displayed as a pop-up when a point on the map is clicked.

To add a pop-up to a point on the map, drag and drop data into the Points: Pop-ups field in the Visualization pane. Information included in the pop-up field will be shown when a user clicks on a point.

You can add more than one field to the Points: Pop-ups field well and they will be shown in a table in the pop-ups. You can re-order the fields in the field well to control the order in which they display in the pop-ups. You can configure the formatting of fields using the standard Power BI field formatting tools (under Format visual / General / Data format) e.g. to display numbers as currency.

Handling overlapping points on a map using pop-ups

It’s quite common that points on a map might have identical locations, making the data more difficult to understand. For example, when considering crime data, a shoplifting crime and a violent crime may have been recorded to the same x, y coordinates or postcodes; however, only one point can be shown at each location.

If this is the case with your data and you then add a field to symbolise by colour or size, this may be hard to understand on the map. In this situation, a warning will be generated in the notifications pane, telling you that the data contains duplicate point locations, so that you can decide how to handle this.

For numerical data, it may be appropriate to apply a summary to the colour / size field to show, for example, the total number of people affected at a given location. For other forms of data, especially categorical, this will be less appropriate. In this case, you can add a suitable column that distinguishes points to the Points: Pop-ups field. The pop-up at these locations will then be paginated, allowing viewers to see all the values occurring at that location.

Below is an example of a pop-up where data representing crime type is being used to enable pagination of overlapping points; the pop-up shows there are five points representing different crime types in the same location:

Follow one of the steps below to add polygons or other features to the features layer of the map. Note that the three ways of adding features (via GSS codes, geometry from your data, or by uploading a data file) are mutually exclusive; only one method can be used at a time.

Using ONS geographies

Creating a choropleth (or fill) map using Office for National Statistics (ONS) geographies — such as Lower layer Super Output Areas (LSOAs) and wards — in the OS Maps for Power BI Visual is straightforward and does not require a separate geometry file.

To make the following steps work, your data will need a column that includes ONS Government Statistical Service (GSS) codes.

Examples of LSOA codes are shown in the table below:

To display these geographies as polygons on a map, simply drag and drop the column of data that has these codes into the Features Layer: GSS identifiers geocoding field of the visual.

Using geometries from the Power BI data model

If you have a column in your data that contains geometries in either WKT or GeoJSON format, you can add these to the Features Layer of the map by dragging that column to the "Features Layer: WKT or GeoJSON Geometries" field of the Build Visual pane.

More detailed information on how to import GeoJSON or other data into your Power BI data model can be found on the .

Note that you are not limited to using polygon geometries; points and lines also work.

Uploading spatial data into the visual

You can also upload your own spatial data directly into the visual itself, and then link it to your Power BI data via a common attribute to allow data-driven styling of the features. You can upload data from a GeoJSON file, a TopoJSON file, or a shapefile. Note that you are not limited to using polygon geometries; points and lines also work.

To use this feature, first ensure that you have added some data to the visual on the Build Visual pane. You can add the Power BI data you want to join to your uploaded data, and / or any other columns of data.

Next go to Format Visual > Upload Geospatial Data and toggle on Show upload manager.

A dialog will appear in the visual allowing you to upload data from a file on your computer. Follow the steps in this Upload Manager dialog to upload you data to the visual. More information on this stage of the process can be found on the . Return to this page when you have followed the steps to upload the data.

Once you have used the Upload Manager to load data into your visual, the settings pane beneath the Upload Manager toggle will update to show the filename of the data you loaded, and the dropdown will show the names of the unique columns in the dataset:

You can now select which column you wish to join to the Power BI data model.

Then, if you have not already done so, add the corresponding column from your Power BI data to the Features Layer: Linking identifier to match in uploaded geometries field well. You should now see the features from your dataset that match a value in the Power BI data showing on the map.

You can also display features from the uploaded data which do not match the Power BI data, by simply selecting the appropriate toggle:

These unmatched features are symbolised separately with a single symbol (because they do not have Power BI data to drive their styling). More information is on the .

There are two valid data formats that the visual accepts to display custom geometry in the Features Layer via the Features Layer: WKT or GeoJSON Geometries field well. These geometries need to be properly formatted within your data in order to be displayed on the map.

The instructions on this page describe how to get WKT or GeoJSON data into the Power BI data model in a form that you can add to the map via the Features Layer: WKT or GeoJSON Geometries field well.

How to use WKT data to add custom geometry to a map

Because WKT is simply a text-based geometry format, it's quite common that it might be present as a column in an existing table such as a database table or query, or a CSV file.

In this case, you can simply add that table to your Power BI data model by selecting Get Data / Text/CSV and following the steps to load the CSV file into your data model, and establish appropriate relationships between it and your other queries. You can then add the WKT column straight into the visual.

How to use GeoJSON data to add custom geometry to a map

GeoJSON is another text-based format, which can be used to represent geometries (as with WKT, above), or entire features or feature collections (a feature comprises both geometry and attributes).

It's possible to have GeoJSON geometries or features present as a column in an existing table such as a CSV file. In this case, the process for adding the features to the visual is identical to the one for adding WKT as described above.

Load a GeoJSON file to a Power BI query

It's more likely that you may have a standalone GeoJSON file. The following steps describe how you can import a GeoJSON file into Power BI, to turn it into a table that you can add into the visual by following the steps .

These instructions may be easier to follow by navigating to the ‘Add Some Data Tab’ on the landing page then looking for the ‘GeoJSON (from Power BI data model)’ section. The landing page can be accessed via the ‘Question Mark’ button in the bottom left. You can copy and paste the necessary code from there.

Converting your data

You might have geometry in shapefile, geopackage, or another format. You can use GIS software such as QGIS to turn those formats into WKT that the visual will accept.

Start by loading your geometry into QGIS by dragging it into the QGIS window. Then, under Layers, right-click and select Export, then Save Feature as. Save your file as a CSV, then under ‘Geometry’ you want to select AS_ WKT.

Exporting your file as a CSV will create a file with every polygon listed as a separate entry alongside any additional metadata associated with those polygons from the original file. The WKT column in that CSV is what you’d drag into the Features Layer: GeoJSON or WKT Geometry in the OS Visual to display the geometry.

Simplifying your data

If you are having problems with the 32kb limitation described previously, you can also use QGIS to simplify your geometry and remove unnecessary precision, which may help to get around the issue.

Start by loading the data into QGIS as described above.

Next you can experiment with simplifying the data to remove unnecessary coordinates. The Simplify tool can be found under Vector / Geometry Tools / Simplify in the current version of QGIS. An appropriate "tolerance" depends on the size of your features and how far you need to be able to zoom in the map. If you are not using Premium zoom levels, then a tolerance of 1 or 2 metres would certainly not result in any visible degradation of the features. At the higher Premium zoom levels, a smaller value may be needed. This may or may not make a difference to the size of your geometries, depending on how much detail was in them to start with.

Next you can also reduce the precision of the coordinates so that they are stored in the WKT using fewer digits, thereby taking less space. This is a two step process:

• Firstly export the data to GeoJSON, using an appropriate value for coordinate precision. If the data are in BNG coordinates (metres) there is no benefit in storing numbers to multiple decimal places, so a value of 1 is fine. For data in latitude/longitude coordinates (degrees), a value of 6 would represent so is generally appropriate.

• Next add the exported GeoJSON back into your QGIS map, and then re-export this to CSV with WKT geometries, following the process described . You should now find that the geometry coordinates in the file have been rounded, and occupy less space.

If, after following all these steps, you are still unable to add the data to the visual due to the 32KB limitation, we recommend that you load the data using the approach on the instead.