Use Custom Icons in Geo Charts

You can use custom icons in geo chart pushpin layers to make locations easier to distinguish. Custom icons can be applied in two ways: as one icon for all points in a layer, or dynamically from a data column.

Follow these steps:

1. Prepare Sprites
2. Register Sprite Set
3. Add Icon Labels
4. Configure Pushpins

Prepare Sprites

Custom icons must be packaged as a MapLibre sprite set and hosted by your organization.

A sprite set combines multiple icons into two files:

• A sprite atlas (.png), which contains all the icons packed into a single image.
• A sprite index (.json), which maps each icon name to its position and dimensions in the atlas.

GoodData reads these generated files; it does not read the individual source icon files.

To create and host a sprite set:

1. Prepare the source icons.

   Create one SVG source file for each icon. Give each file the name that you want to use as the icon identifier, such as hospital, school, or restaurant.

   These identifiers must later match the values in the GEO_ICON label.

2. Generate the sprite atlas and index.

   Use a MapLibre-compatible sprite generator to process the directory of SVG source icons. Common command-line options include:

   • spreet, which accepts SVG and SVGZ input.
   • spritezero-cli, a command-line wrapper around the @mapbox/spritezero library, which accepts SVG input.

   The generator packs the icons into one PNG atlas and creates the corresponding JSON index. Do not create or maintain the icon coordinates manually.

3. Verify the generated files.

   A generated index might contain entries similar to the following:

   {
     "hospital": {
       "x": 0,
       "y": 0,
       "width": 32,
       "height": 32,
       "pixelRatio": 1
     },
     "school": {
       "x": 32,
       "y": 0,
       "width": 32,
       "height": 32,
       "pixelRatio": 1
     },
     "restaurant": {
       "x": 64,
       "y": 0,
       "width": 32,
       "height": 32,
       "pixelRatio": 1
     }
   }

   This example is illustrative. The generator determines the actual coordinates and dimensions.

   The JSON keys—hospital, school, and restaurant in this example—are the icon names that can be used in a GEO_ICON label. See Add Icon Labels.

4. Host the generated files.

   Host the files under the same base URL using these names:

   • {base_url}.json
   • {base_url}.png

   For example, for the base URL https://cdn.example.com/sprites/poi, GoodData requests:

   • https://cdn.example.com/sprites/poi.json
   • https://cdn.example.com/sprites/poi.png

   The files must be reachable from the browser running GoodData and must be served with CORS headers that allow requests from your GoodData domain. Missing or incorrect CORS headers are a common cause of validation failures.

   You can optionally provide high-resolution variants:

   • {base_url}@2x.json
   • {base_url}@2x.png

GoodData uses the standard MapLibre sprite format. For details about the index properties and optional sprite metadata, see the MapLibre sprite specification.

Register Sprite Set

An administrator must register the sprite base URL in Settings > Appearance & Behaviour > Geospatial Icons.

GoodData validates that:

• the .json file is reachable and contains a valid sprite index
• the .png file is reachable

After validation succeeds, the sprite set becomes available for geo charts in the organization. If validation fails, the previous configuration is kept.

Add Icon Labels

To use data-driven icons, add a secondary label with value type GEO_ICON to a location attribute that already contains GEO_LATITUDE and GEO_LONGITUDE labels.

The GEO_ICON label should contain icon names that match keys in the sprite index, for example hospital, school, or restaurant.

Each attribute can have only one GEO_ICON label. If a value is empty or does not match any icon in the active sprite set, the point is shown with the default pushpin.

Configure Pushpins

In Analytical Designer, open the pushpin layer and choose one of these shape types:

• One icon: Select one icon to use for all points in the layer.
• Icon by value: Use icon names from the GEO_ICON label to render icons per point.

The Icon by value option is available only when the selected location attribute includes a GEO_ICON label.

Limitations

When a custom pushpin icon is enabled, these options are not available for the layer:

• metric by color bucket
• metric by size bucket
• segment by bucket
• clustering
• color configuration

A metric can still be used in tooltips, but it does not control icon color or size.