Setting up Mapbox to work with Cognos Analytics

IBM® Cognos® Analytics supports the use of custom polygons that come from Mapbox.

Create a free Mapbox account. When you have created your Mapbox account, upload your geoJSON custom polygon file to Mapbox as a tileset. If your geoJSON is less than 5 MB, then you can edit the geoJSON directly as a data set in Mapbox. After you edit the geoJSON files, export them into a tileset. Make sure that each polygon has at least one uniquely identifying property as a string value. For more information about tilesets, see the Mapbox documentation about a tileset.

Custom polygons in formats such as .shp and KML can be converted to geoJSON, by using, for example QGIS.

Retrieving data from Mapbox

When you have your tileset created in Mapbox, make note of the following information from the tileset page:
  • Tileset Id
  • Layer name
  • Property name

You specify these values when you want to use Mapbox data in your map.

Enter the Tileset ID into the field marked Tileset Id.

Best practices

  • For increased performance and to make sure that polygons appear at zoom level 0 (world view), compress geoJSON files to less than 10 MB. A tool that can compress geoJSON files is

    If your geoJSON files are larger than 10 MB, then Mapbox sets the default zoom to not start at worldview 0. If you want to manually change the zoom extents, there are few ways to do so:
    • Tippecanoe APIs, which are available on Linux and Apple MacOs.
    • Download Mapbox studio classic on your Microsoft Windows computer and change the minimum and maximum zoom levels.
    For more information, see
  • To ensure that auto-zoom works in IBM Cognos Analytics - Reporting set the unique polygon identifier as a string value.
  • If you work with custom polygons in small areas, for example at postcode level, turning off auto zoom after the initial data loads. This results in a better experience when you filter because the map does not reset zoom and zoom in multiple times.
  • Keep the Mapbox keys confidential.
Example of custom regions
A map with a region layer that shows the population.
Example of custom points
A map with a points layer that shows the population.