How to Add a Map to Dashboard

You can add a map to your dashboard, so that you can display regional data in a graphical form.

All you have to do is to create a Highmaps map widget and use it in your dashboard. The widget is defined by a calculation logic using the api.buildHighmap method. The data can come either from PriceAnalyzer or other storages or can be created on the fly.

Refer to the Highmaps API reference to explore the full variety of settings. At the very least you need to provide a value, series[n].joinBy value and series[n].data.

The joinBy array tells Highmaps how to match the map definition with the data. Typically for international maps, the country name is the 'name' field, which matches the 'country' field of the data in our the example above. There are also 'iso-a2' and 'iso-a3' fields, which feature the 2- and 3-character ISO standards, and many more. Exploring the JavaScript definitions on the Highmaps - Map Collection page should help understanding how this works.

The following example is based on Color axis and data labels with a 1 to 1 translation from JavaScript (as found in "View Options" on the linked page) to Groovy:

You can also use latitude/longitude coordinates in Highmaps: 


If you cannot find an example of an existing logic that uses a chart type that you require, it should be fairly easy to adapt one of the Highmaps Demos.

  1. Select your chart and click on the "View Options" button and you will see the JS source code, including a Highcharts.mapChart('container', {...}) call. This {...} content is the definition map. 
  2. You will have to convert it from JS to Groovy.
    1. This always implies replacing the curly brackets by square brackets ({} -> []).
    2. You may also sometimes encounter code like Highcharts.color(colors[5]).brighten(0.2).get() which you should replace by your own hard coded colors, or formatter: function () {...} which you would have to replace by simpler pattern formatter format: '{}: {point.y:.1f}%'.

(warning) Currently, not all maps of the extensive Highmaps collection are supported (bundled) – see the list below. If you are missing a map, let us know (open a support ticket) and we will do our best to add it in the next patch release.

World and Continents

  • /custom/africa
  • /custom/asia
  • /custom/europe
  • /custom/european-union
  • /custom/oceania
  • /custom/central-america
  • /custom/north-america
  • /custom/north-america-no-central
  • /custom/south-america 2
  • /custom/usa-and-canada
  • /custom/world
  • /custom/world-continents
  • /custom/world-eckert3
  • /custom/world-palestine
  • /custom/world-robinson


Since Godfather (8.0) all the countries listed under the Countries heading on the Map Collection page are supported with the exception of countries that have more than one map – in this case only the primary map is supported (e.g, 'Burundi' is supported but 'Burundi, admin2' is not). Note that maps marked with a red star require that the original source of the map data is credited. By default the credits are enabled and it is important that you do not disable them in the code when using such map.

Support of country maps in previous releases:

Chinacountries/cn/cn-all1 3
countries/cn/custom/cn-all-sar1 3
countries/cn/custom/cn-all-sar-taiwan1 3
Hungarycountries/hu/hu-all1 3
Japancountries/jp/jp-all1 3


New Zealandcountries/nz/nz-all1
Polandcountries/pl/pl-all1 3
South Koreacountries/kr/kr-all1

1since El Presidente PR4 (3.6.4)

2since Collins PR2 (5.2)

3minor character encoding issues remain