Troubleshooting

Integrate the Mapbox Visual with Microsoft Power BI

Supported Power BI environments and tools

The Mapbox Visual for Microsoft Power BI is on version 1.4.0. This version works with the following Power BI environments and tools:

PBI Report ServerPBI Mobile (iOS/Android)PBI EmbeddedPBI Publish to WebPBI DesktopChromeFirefoxSafariEdgeIE11
YesYesYesYesYesYesYesYesYesNo

To use the Mapbox Visual in Microsoft Power BI, you need to link your Mapbox access token in Power BI:

  1. To get started with the Mapbox Visual in Microsoft Power BI, you need a Mapbox account and a Mapbox access token. You can find your Mapbox access tokens on your Account page.
  2. In Power BI, under the Mapbox Custom Visual Format panel, open the Viz Settings dropdown.
  3. Paste your Mapbox access token in the Access Token field.
A screenshot showing where to add your Mapbox access token to the Power BI Viz Settings panel

Use a custom Mapbox style in Power BI

The Mapbox Visual for Power BI gives you access to several default Mapbox styles. You can also use a custom Mapbox that you have created in Mapbox Studio:

  1. In Mapbox Studio, find the style that you want to use.
  2. Click the Menu button.
  3. Click the icon next to the Style URL to copy it to your clipboard. You will need this URL to link to your custom map style in Power BI.A screenshot showing the Make public option and the style URL in a Mapbox style menu options
  4. Go to Power BI. Under the Mapbox Custom Visual Format panel, open the Viz Settings dropdown.
  5. In the Map Style field, select the Custom option.
  6. In the Style URL field, paste the style URL that you copied earlier.
Screenshot showing that the Map Style should be set to Custom and where to paste the Mapbox style URL in Power BI

Format your location data to use in Power BI choropleth visualizations

The Mapbox Visual for Power BI provides default support for creating choropleth visualizations at different administrative levels:

  • Global countries
  • US states
  • US postal codes.

When you add your own data to Power BI, the data must contain fields that match these administrative levels names and data types to create the data join. Data dropped into the Location field in the Mapbox Visual must match a row in the Name matches file exactly to be included visually on your map.

The following data are supported in the Mapbox Visual for Power BI:

Administrative levelData typeCapitalizationExamplesNotesExceptions
Global countriestextCapitalize the first letter of each word; all other letters must be lowercase.South Africa• Use United Kingdom rather than the individual country names England, Scotland, Wales, or Northern Ireland.
• Use a country's name rather than its abbreviation (for example, United Arab Emirates, not UAE), except for USA, as noted in this table's Exceptions column.
Use USA rather than United States or United States of America.
US statestextCapitalize the first letter of each word; all other letters must be lowercase.New Jersey, New Hampshire
US postal codes ZCTA5-digit text stringNot applicable94110When you import data as a CSV file, Power BI will automatically cut the leading "0" off any zip codes beginning with "0". To fix this, change the zip code field type to "Text" before the data is imported. Changing it to text after the data is imported will not fix the issue.

Style dimensional values with the Data Colors feature

If you format your data so that the values in categorical (dimension) field are text, you can style these dimensional values using the Data Colors feature. The Power BI interface hides this feature until you have met the following data and format conditions.

To access the Data Colors feature:

  1. Format your data and import it into Power BI. The values in the dimensional field you want to use must be formatted as text.
  2. Begin creating your Power BI report as usual, and add the Mapbox Visual.
  3. Drag your dimensional field from the Fields panel into the Color shelf.
  4. The Data Colors dropdown menu will appear in the Format panel. Select your desired colors for each text value.

Screenshot showing the Data Colors option in Power BI

You can also use the Data Colors field to style your choropleth visualizations in Power BI:

  1. Format your data and import it into Power BI. The values in the dimensional field you want to use must be formatted as text.
  2. Begin creating your Power BI report as usual, and add the Mapbox Visual.
  3. Make sure that the data you drop into the Location field in the Mapbox Visual exactly matches the data in a default Mapbox Visual dataset (see the Format your location data to use in Power BI section).
  4. Drag your dimensional field from the Fields panel into the Color shelf.
  5. Go back to the Format tab. Switch the Circle option off and turn the Choropleth option on.
  6. The Data Colors dropdown menu will appear. Select your desired colors for each text value.

Screenshot showing the Data Colors option in Power BI when the Choropleth option is selected

Resolve blank map issues in Power BI

If a map that you created with the Mapbox Visual for Power BI does not display, this can likely be traced to one of the following issues:

  1. No GPU. If your map does not display and you are using Power BI Desktop, this likely means that the machine does not have a graphics processing unit (GPU). The Mapbox custom visual for Power BI uses Mapbox GL, which requires a GPU to do client-side rendering,
  • This is a common case when Power BI Desktop is running on a virtual machine. Mapbox GL needs access to the GPU, and virtual machines don't generally have access to the GPU without hardware acceleration enabled. Check to see if you have hardware acceleration enabled on the virtual machine — if not, you will need to enable it.
  1. Cache needs to be cleared. If your map does not display in Power BI Web or Power BI Desktop, either the browser cache or the Power BI Desktop cache may need to be cleared. This can happen due to occasional problems with the Power BI marketplace. To clear the Power BI Desktop cache, delete the contents of the following folders:
  • C:\Users\%username%\AppData\Local\Microsoft\Power BI Desktop
  • C:\Users\%username%\Microsoft\Power BI Desktop Store App
  1. No access to Mapbox API endpoints. If your map does not display in Power BI Web or Power BI Desktop, the machine running Power BI Web or Power BI Desktop may not have access to the Mapbox API endpoints. While no customer data is ever sent to Mapbox, the Mapbox API endpoints must be accessible for rendering Mapbox tiles and styles:
  • https://*.tiles.mapbox.com
  • https://api.mapbox.com
Was this page helpful?