Use Custom Geo Collections in Geo Charts

Administrators can upload custom geo collections to define geographic regions for geo chart visualizations, such as sales territories, operational regions, or other custom polygon shapes.

Custom collections are uploaded at the organization level and can then be referenced in workspaces through the Logical Data Model (LDM).

Upload a Custom Geo Collection

Custom geo collections are uploaded by administrators in the organization settings.

1. Go to Settings > Appearance & Behaviour > Geo collection.
2. Upload a GeoJSON or ESRI Shapefile containing the geographic shapes you want to use.
3. After the file is validated, the collection is added to the organization’s geo collection library.

Uploaded collections can later be updated or deleted from the same interface.

Supported File Formats

Custom geo collections support the following formats:

• GeoJSON files (.geojson, .json)
• ESRI Shapefile archives (.zip)

When uploading an ESRI shapefile, the .zip archive must contain the required shapefile components (for example .shp, .shx, .dbf).

Collection Requirements

The uploaded file must meet the following requirements:

• The file must contain valid GeoJSON syntax.
• Each feature in the collection must include a unique id value.
• Geographic coordinate precision must not exceed 5–6 decimal places.

The coordinate reference system should follow OGC:CRS84, which is the default defined in the GeoJSON standard (RFC 7946).

If the dataset includes a bbox (bounding box) property, it will be used to determine the viewport used for map filtering. If the property is not provided, the system automatically generates the bounding box from the feature geometry.

The id values defined in the collection are used to map dataset values to the corresponding geographic regions.

Coordinate Reference Systems

GeoJSON collections are expected to use the OGC:CRS84 coordinate reference system as defined in RFC 7946.

For ESRI shapefiles, the platform also accepts EPSG:4326. If another supported coordinate reference system is detected, the system automatically reprojects the data.

Use a Custom Collection in a Workspace

Once uploaded, the custom geo collection becomes available for use in workspaces.

To configure a dataset to use the collection:

1. Open the workspace’s logical data model for editing.
2. Add a Geo area secondary label to the attribute representing geographic regions.
3. Configure the label to reference the uploaded geo collection.
4. Ensure that the dataset values match the id values defined in the GeoJSON file.

After configuration, the dataset can be used in geo area charts that render the custom geographic shapes.

Example GeoJSON Structure

The following example shows a simplified GeoJSON structure for a custom collection:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "region_1",
      "properties": {
        "name": "North Territory"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[...]]]
      }
    }
  ]
}

Limits

The following limits apply to custom geo collections:

These limits ensure reliable rendering and performance of geo visualizations.