React ChartsMaps - Topology


All AG Charts Map Series use the GeoJSON format for their topology data.

GeoJSON is an industry-standard specification for representing geographic shapes, lines, and points.

AG Charts does not provide any topology files. It is up to the user to source and license these files, which are widely available online.

GeoJSON Features

A GeoJSON file contains a list of features. Each feature contains a description of geographic data (geometry) along with associated properties.

Geometry types

There are seven geometry types used, as listed in the table below.

Geometry TypeUsageSeries to Use
Polygon, MultiPolygonGeographic areas - the border of the United Kingdom and all its islands.Map Shape Series or Map Marker Series
LineString, MultiLineStringRoutes and connections - flight paths, roads, or rivers.Map Line Series
Point, MultiPointMarkers and points of interest - city centres, building locations.Map Marker Series
GeometryCollectionA collection of one or more feature types. Uncommon to encounter.Choose the series type for the feature types you wish to render.


The properties of a feature are represented as a JSON object. While there is no standard for which properties are included, they typically contain the name of the feature in the property called name.

"properties": {
    "name": "United Kingdom",
    "code": "GB"

Connecting Data to Topology

When using a Map Series which requires topology, both the topology and the data must be provided in the chart or series options.

series: [
    type: 'map-shape',
    topology: {
        type: 'FeatureCollection',
        features: [
                type: 'Feature',
                geometry: {
                    type: 'Polygon',
                    coordinates: [...],
                properties: {
                    name: 'United Kingdom',
                    code: 'GB'
        // ...
    data: [
        { country: 'United Kingdom', population: 67330000 },
        { country: 'France', population: 67500000 },
        // ...
    idKey: 'country',
    topologyIdKey: 'name' //default value
  • Each item in the data must contain a field that refers to the associated geometry for that data item. In the above example this is the country field.
  • The series definition must contain an idKey which refers to this field.
  • The series definition can contain an optional topologyIdKey to match to the relevant field in the GeoJSON properties. If not provided, this will default to name.
  • In this example, the first data item which has the value of United Kingdom will match to the topology feature with the matching value.

Data items should always have a matching topology feature, and will log a warning to the console if they don't. Topology features that don't correspond to a data item are not rendered, and are ignored without a warning.

Topology for Background Series

The Map Shape Background and Map Line Background series do not use any data. These series will render every relevant feature found in the provided topology.

Useful Resources

  • Map Shaper - can simplify maps to reduce their filesize, convert other formats to GeoJSON, and has a command line to manipulate geographic data.
  • - draw shapes on a map and export GeoJSON.
  • GeoJSON Lint - validates GeoJSON.

The links above are examples only. Their listing is not a recommendation and does not imply endorsement by AG Grid Ltd, nor discrimination against similar brands, products or services not mentioned. The decision of which products or resources to use in combination with AG Charts is entirely the choice of the user and at their own risk.