All docschevron-rightHelpchevron-rightarrow-leftTutorialschevron-rightMake a choropleth map with the Mapbox Visual for Power BI

Make a choropleth map with the Mapbox Visual for Power BI

No code

Familiarity with Microsoft Power BI.

In this tutorial, you will use the Mapbox Visual in Microsoft Power BI, data with information about US wildfires by state, and a custom tileset with information about US wildfires by county to create a choropleth visualization. This choropleth will display the number of acres burned at both the state and county levels, allowing you to drill into the data at the appropriate level. You will need a Mapbox account and a Microsoft Power BI account to complete this tutorial.

This guide walks through using the Mapbox Visual in Power BI Online. The process in Power BI Desktop is similar, but the interface is different.

A screenshot of a choropleth visualization in Power BI

Pricing for Mapbox Power BI

The Mapbox Visual for Power BI is billed by Map Loads. The costs for the data visualization in this tutorial fall within the Map load's monthly free tier. See the Third-party tools pricing documentation for more details on how we charge for this service.

Getting started

Here are a few resources you'll need before you get started:

  • Mapbox account. You need a Mapbox account and a Mapbox access token, which you can find on the Account page.
  • Microsoft Power BI account. Sign into your Power BI account or create a new one.
  • Mapbox Visual for Power BI. You can either add the Mapbox Visual using the Power BI Marketplace, or you can download the latest Mapbox Visual from the open-source GitHub repository. Both of these options are explained in detail in the tutorial.
  • Geospatial data. You will upload this GeoJSON file, which contains county-level detail about wildfires in the United States, to Mapbox Studio as a tileset.
arrow-downDownload GeoJSON
  • Dataset for Power BI. You will upload this sample dataset, a CSV file that contains historical information about wildfires in the United States, to Power BI.
arrow-downDownload CSV

Upload your tileset to Mapbox

Before you can reference the geospatial data from the downloaded GeoJSON file in a Power BI report, you need to upload it to Mapbox as a tileset.


To upload geospatial data to Mapbox as a tileset, the data must be in one of the following formats:

  • MBTile
  • KML
  • GPX
  • GeoJSON
  • Shapefile (zipped)
  • CSV

For information on upload file size limits for these formats, refer to the Uploads troubleshooting page.

  1. Navigate to the Tilesets page in Mapbox Studio.
  2. Click on the New tileset button.Screenshot showing the New tileset button in Mapbox Studio
  3. In the New tileset window, you can either click the Select a file button and choose the file, or you can drag and drop the file directly into the window.
  4. When you are prompted to do so, click Confirm.Screenshot showing the Confirm button in the New tileset window in Mapbox Studio
  5. After the file uploads, you will see a confirmation success message. Click on the link in the confirmation message to open the new tileset’s Tileset explorer.
  6. In the Tileset explorer, click on Share & use to find the tileset ID, which you will need to reference in Power BI. The Tileset explorer also includes the layer's name and the layer’s properties, which you will need as well.

You will use these pieces of information in the Add a custom tileset section of this tutorial. For now, though, you will open Power BI.

Add data to Power BI

You will start by adding the wildfire data you downloaded to a new Power BI workspace.

  1. In Power BI, click Get Data, which allows you to import data or connect to a data source.
  2. Under the Files option, click Get.
  3. Choose Local File and upload the wildfire data CSV file.

A screenshot showing how to upload a CSV to Power BI

Notes on using a custom dataset in Power BI

Your dataset should be a CSV file with at least 2 columns. One column must be a unique identifier, which will be used to match a unique property from your tileset. The second column must be the value you want to connect to the unique identifier. (For the dataset in this example, the unique property is the state_name, which you will match to the pre-defined Power BI state tileset. The value you connect to the unique identifier will be the number of acres burned.)

Create a new report

  1. Click on My Workspace and select the Datasets tab.
  2. Click the Create a report option (the bar graph icon) next to the new dataset. This will open the report window.

A GIF showing how to create a new report in Power BI

Add the Mapbox Visual to the report

You can use the Mapbox Visual for Microsoft Power BI with any dataset that contains geographic data values. To add the Mapbox Visual to your report:

  1. In the Visualizations pane, click the Import a custom visual option, represented by a three-dot icon.
  2. Select Import from marketplace.
Screenshot showing how to import a visual from marketplace in Power BI
  1. Enter "Mapbox" in the search menu and press enter.
  2. Click the Add button next to the Mapbox Visual option to add it to your Power BI report. After the Mapbox Visual is imported, it will appear as a blue Mapbox logo on the Visualizations pane.
Screenshot showing the Mapbox Visual icon in the Visualizations pane in Power BI
Alternative workflow: Manual upload

Alternatively, you can download the latest Mapbox Visual for Power BI from Mapbox's open-source GitHub repository:

  1. Click the Import a custom visual icon (three dots) and select Import from file.
  2. Upload the latest Mapbox Visual.
  3. A new blue Mapbox logo will appear in the Visualizations pane.

Build the choropleth visualization

Include an access token

  1. Click on the Mapbox icon in the Visualizations pane to add a new visualization to your report.
  2. In the Fields tab, drag the state_name field from your data onto the Location shelf. You should see the Mapbox visualization container populate with instructions on how to create your first visualization.
Screenshot showing the state_name field in the Location shelf
  1. Connect your Mapbox account using your access token:
    • Click the Click here to get a free Mapbox access token link in the visualization container. Accept the external link request if prompted. You will be forwarded to either the Mapbox sign up page or your Mapbox account page.
    • Copy your Mapbox Access token from your account page.
  2. Back in Power BI, go to the Format tab and open the Viz Settings option. Paste your access token in the Access token field.
GIF showing how to add Mapbox access token in Power BI

Create the choropleth

  1. In the Viz Settings pane, change the Map Style option to Dark.
  2. Drag the ACRES field from the data options onto the Color shelf.
  3. Go back to the Format tab. Switch the Circle option off and turn the Choropleth option on.

You will see a choropleth that visualizes the number of acres burned per state.

Screenshot showing the choropleth visualization in Power BI

Add a custom tileset

To drill down more deeply into data about wildfires in the United States, you will reference the custom tileset with information about wildfires at the county level that you created in the first step of this tutorial.

To add this data to Power BI, you will plug its identifying features into the appropriate fields in Power BI. The information that you'll need from the tileset are the tileset ID, the layer name, and the unique identifier property name.

Screenshot showing the elements necessary to add a tileset to Power BI: the tileset ID, the layer name, and the property name

  1. In the Format tab, click on Choropleth to open the choropleth layer settings.
  2. Use the Number of levels dropdown menu to change the number of levels to 2. (Having two levels will allow you to drill down from the state-level data in Level 1 into the county-level data that you are adding now.)
  3. In the Level dropdown, select Level 2.
  4. Click on the Data Level 2 dropdown.
  5. Select the Custom Tileset option.
Screenshot showing how to add a custom tileset to a choropleth in Power BI
  1. In the Vector Tile URL Level 2 field, paste the tileset ID. The tileset ID in this field must always be preceded by mapbox://.
  2. In the Source Layer Name Level 2 field, paste the layer's name.
  3. In the Vector Property Level 2 field, enter the unique identifier property name: id.
  4. Click on the Fields tab again. Drag the county_id field from the data options onto the Location shelf.
Using a custom tileset in Power BI

The boundaries in a custom tileset should contain one unique identifying property key that matches the dataset you are using in Power BI. Common examples are: FIPS code, zip code, ISO code, or any unique name string.

Final product

Use the buttons on the upper left side of the visualization to drill up to the state level or down to the county level. Hover over a state or county to see the number of acres burned in that specific boundary.

Screenshot showing a county-level choropleth visualization in Power BI

You have created a choropleth visualization in Microsoft Power BI using the Mapbox Visual for Power BI.

Next steps

For additional support with the Mapbox Visual, you can open an issue in the open source repository or contact our support team.

Want to do more with Mapbox and Power BI? Contact Mapbox sales to learn what else is possible, from adding custom shapes to visualize territories, adding detailed indoor maps, or visualizing billions of data points.