All docschevron-rightHelpchevron-rightarrow-leftTutorialschevron-rightCreate data visualizations with the Mapbox Visual for Power BI

Create data visualizations with the Mapbox Visual for Power BI

No code

Familiarity with Microsoft Power BI.

Create customizable heatmaps, point cluster maps, and graduated circle maps with the Mapbox Visual for Power BI using Microsoft Power BI Desktop and Online. The Mapbox Visual can be imported and accessed as a visualization plugin inside Power BI. This guide will walk through getting started with the Mapbox Visual and how to create a Mapbox-powered visualization in Microsoft Power BI. You will need a Mapbox account and a Microsoft Power BI account to complete this tutorial.

an interactive data visualization on a map

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 will need a Mapbox access token to add the Mapbox Visual in Power BI. Sign up for a free account on Mapbox.
  • Power BI account. Sign into your Power BI account or create a new one.
  • Mapbox Visual for Microsoft 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.
  • Data. This guide uses a sample CSV file with US healthcare spending derived from
arrow-downDownload CSV

Add data to Power BI

Start by adding data to a Power BI workspace.


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.

Add a new dataset

  1. Sign into your Power BI account.
  2. Click Get Data to import or connect to a data source.
  3. To import the healthcare data you downloaded earlier, choose to Import a File.
  4. Choose Local file and upload the CSV file.

You can use the Mapbox Visual for Microsoft Power BI with any dataset that contains geographic longitude and latitude data values.

add a new data file to your Power BI account

Create a new report

In your Power BI workspace, navigate to the Datasets tab and create a new report by clicking the bar graph icon next to your new dataset. The report window will open and you will be able to edit your new report.

create a new report in your Power BI workspace

Add the Mapbox Visual to your Report

You'll add the Mapbox Visual using the Visualizations pane:

  1. In the Visualizations pane, click the Import a custom visual option, represented by a three-dot icon.
  2. Select Import from marketplace.
  3. Enter "Mapbox" in the search menu and press enter.
  4. Click the Add button next to the Mapbox visual option to add it to your Power BI report. It will appear as a blue Mapbox logo on the Visualizations toolbar.
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.

Create a visualization

Click on the Mapbox icon in the Visualizations pane to add a new visualization to your report. While customizing your visualization, you'll work in both the Fields and Format panels within the Visualizations pane:

  • The Fields panel is where you will specify which data fields to associate with different types of Mapbox layers (for example map styles, heatmaps, circle maps, and cluster aggregation).
  • The Format panel is where you will specify the visualization style for each layer, such as color and radius.

Initialize a visualization

In the Fields panel, drag the latitude and longitude fields from your data onto the Latitude and Longitude shelves, and make sure that the Do not summarize option is checked for both fields. You should see the Mapbox visualization container populate with instructions on how to create your first visualization.

Connect your Mapbox account using your access token:

  1. Click on the link, Click here to get a free Mapbox access token, 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.
  2. If you don’t have a Mapbox account, sign up with your email address.
  3. Copy your Mapbox Access token from your account page.
  4. Back in Power BI, go to the Format panel and find the Viz Settings option. Paste your access token in the Access token field.

animated GIF illustrating the process outlined above

You will see your first map visualization!

the resulting data visualization: a map with uniform circles at every point from the dataset

Change the map style

With the Mapbox Visual for Power BI, you can change the map style used in your visualizations. You can use any Mapbox default style or create a custom map style with Mapbox Studio. To update the map style:

  1. In the Format panel, select Viz Settings > Map Style.
  2. Select from any default map style. This example uses the Mapbox Satellite style.
Custom map styles

You can use any custom map style from your Mapbox Studio account by selecting Custom style. This is useful for adding custom polygons, drone imagery, or finely-tuning the context and design of your Mapbox visualization to help answer your business question.

When you select Custom style, you will be prompted to add a style URL. To learn how to find your custom style URL, read about more about style URLs.

To learn more about creating custom map styles in Mapbox Studio, explore the Mapbox Studio manual or the Create a custom map style tutorial. Have questions on how to implement these features? Reach out to our support team.

Now you'll see your data on top of a satellite map.

the same data visualization as above, but with a satellite map behind the circle layer

Create a cluster layer

Next, you'll adjust the visualization to illustrate where the average covered costs are lowest in the US using a cluster layer.

In the Fields panel, add the Avg Covered Charges field from your data to the Cluster shelf.

In the Format panel:

  1. Turn the Cluster layer On and the Circle layer Off.
  2. Under Cluster, select maximum from the Aggregation type drop down list.

animated GIF illustrating the process outlined above to add a cluster layer

Style the cluster visualization

In the cluster Format panel:

  1. Change the Min Color to FEC0BF and the Max Color to FF0027.
  2. Change the Cluster Radius to 30.
  3. Set the Blur to 0.
  4. Set the Stroke Width to 3.
  5. Set the Max Zoom to 6.

screenshot of the Power BI UI with the properties as specified above

Update layers based on zoom level

Sometimes you may want to visualize data differently at different zoom levels. With the Mapbox Visual for Power BI, you can use multiple layers in a single visualization and specify at which zoom levels each layer should be displayed. Here, you'll show a cluster layer at low zoom levels (zoomed further out) and a circle layer at high zoom levels (zoomed further in).

Add data properties to shelves

In the Fields panel:

  1. Add the Average covered charges data field to both the Color and Size shelves.
  2. Add Provider Id to the Tooltip shelf.

screenshot of the Power BI UI with the properties as specified above

Style the circle layer

Then, in the Format panel re-enable the circle layer by toggling the Circle layer On, and update the style properties:

  1. Set the circle Radius to 1 and the Zoom scale factor to 10.
  2. Set the circle Min Color to FEC0BF, Med Color to FD817E, and Max Color to FF0027.
  3. Set the circle Stroke Color to white.
  4. Set the circle Min Zoom to 6. This will hide the circle layer while the cluster visualization is being displayed.

screenshot of the Power BI UI with the properties as specified above

Final product

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

an interactive data visualization on a map

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 sales to learn what else is possible — from adding custom shapes to visualize territories, adding detailed indoor maps, or visualizing billions of data points.