Setting up Mapbox to work with IBM Cognos Analytics

IBM® Cognos® Analytics supports the use of custom polygons in partnership with Mapbox.

Create a free Mapbox account with 5 GB of space. When you have created your Mapbox account, upload your geoJSON custom polygon file to Mapbox as a tileset. A tileset is a compiled set of geoJSON that is optimized to render fast on a browser. For more information, see https://www.mapbox.com/pricing/.

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.

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

Retrieving the necessary data from Mapbox

When you have your tileset that is created in Mapbox, copy the following three keys from the tileset page:
  • MapID
  • Layer name
  • Unique identifier

You need these keys when you want to use Mapbox data in you map visualization.

For more information, see Using custom point or region information from Mapbox in a map visualization in a dashboard and Using custom point or region information from Mapbox in a map visualization in a report.

For more information, see Using custom point or region information from Mapbox in a map visualization in a report in the IBM Cognos Analytics Dashboards and Stories user guide and Using custom point or region information from Mapbox in a map visualization in a report.

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 http://mapshaper.org/.

    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 https://www.mapbox.com/help/adjust-tileset-zoom-extent/.
  • 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 visualization with a region layer that shows the population.
Example of custom points
A map visualization with a points layer that shows the population.