Map Series

Overview

Map series are used to display different types of geographic data on a MapChart. amCharts 5 provides several series types for different use cases.

MapPolygonSeries

Creates a map series for displaying polygons (countries, states, regions).

Creating a MapPolygonSeries

import * as am5map from "@amcharts/amcharts5/map";
import am5geodata_worldLow from "@amcharts/amcharts5-geodata/worldLow";

const polygonSeries = chart.series.push(
  am5map.MapPolygonSeries.new(root, {
    geoJSON: am5geodata_worldLow,
    fill: am5.color(0x095256),
    stroke: am5.color(0xffffff)
  })
);

Settings

geoJSON

GeoJSON.GeoJSON

Map data in GeoJSON format.

polygonSeries.set("geoJSON", am5geodata_worldLow);

reverseGeodata

boolean

default:"false"

If set to true, the order of coordinates in GeoJSON will be flipped.Some GeoJSON software produces coordinates in reverse order, so if your custom map appears garbled, try this setting.

include

string[]

An array of map object IDs from geodata to include in the map.If set, only those objects listed in include will be shown.

polygonSeries.set("include", ["US", "CA", "MX"]);

exclude

string[]

An array of map object IDs from geodata to omit when showing the map.

polygonSeries.set("exclude", ["AQ"]); // Exclude Antarctica

valueField

string

A field in series data that holds the map object’s numeric value.It can be used in tooltips, heat rules, etc.

polygonSeries.set("valueField", "value");

geodataNames

{ [index: string]: string }

Names of geodata items to replace from loaded geodata.Can be used to override built-in English names for countries.

import am5geodata_lang_ES from '@amcharts/amcharts5-geodata/lang/es';
polygonSeries.set("geodataNames", am5geodata_lang_ES);

See Map translations for more info.

affectsBounds

boolean

default:"true"

If true, this series will affect the calculated bounds shown in the MapChart.Set to false to ignore a series while calculating the bounds (useful for background series).

Properties

mapPolygons

ListTemplate<MapPolygon>

A ListTemplate of all polygons in the series.Use mapPolygons.template to configure polygon appearance.

polygonSeries.mapPolygons.template.setAll({
  tooltipText: "{name}",
  fill: am5.color(0x095256),
  strokeWidth: 1
});

Methods

zoomToDataItem(dataItem, rotate?)

Animation<any> | undefined

Centers and zooms in on the specific polygon.

Show Parameters

dataItem

DataItem<IMapPolygonSeriesDataItem>

required

Target data item

rotate

boolean

If true, the map will rotate so this polygon is centered (useful with geoOrthographic projection)

See Zooming to clicked object for more info.

polygonSeries.mapPolygons.template.events.on("click", (ev) => {
  polygonSeries.zoomToDataItem(ev.target.dataItem);
});

zoomToDataItems(dataItems, rotate?)

Animation<any> | undefined

Zooms the map so that all polygons in the array are visible.

Show Parameters

dataItems

Array<DataItem<IMapPolygonSeriesDataItem>>

required

An array of data items to zoom to

rotate

boolean

Rotate the map so it is centered on the selected items

const items = [dataItem1, dataItem2, dataItem3];
polygonSeries.zoomToDataItems(items);

getPolygonByPoint(point)

MapPolygon | undefined

Returns a MapPolygon that is under specific X/Y point.

Show Parameters

point

IPoint

required

Screen coordinates

const polygon = polygonSeries.getPolygonByPoint({ x: 100, y: 200 });

getPolygonByGeoPoint(point)

MapPolygon | undefined

Returns a MapPolygon that contains the specified geographical point.

Show Parameters

point

IGeoPoint

required

Geographical coordinates

const polygon = polygonSeries.getPolygonByGeoPoint(
  { longitude: -73.9352, latitude: 40.7306 }
);

Data Item Fields

geometry

GeoJSON.Polygon | GeoJSON.MultiPolygon

GeoJSON geometry of the polygon.

mapPolygon

MapPolygon

Related MapPolygon object.

MapPointSeries

Creates a map series for displaying markers on the map.

Creating a MapPointSeries

const pointSeries = chart.series.push(
  am5map.MapPointSeries.new(root, {
    latitudeField: "latitude",
    longitudeField: "longitude"
  })
);

pointSeries.bullets.push(() => {
  return am5.Bullet.new(root, {
    sprite: am5.Circle.new(root, {
      radius: 5,
      fill: am5.color(0xff0000)
    })
  });
});

pointSeries.data.setAll([
  { latitude: 40.7306, longitude: -73.9352, title: "New York" },
  { latitude: 51.5074, longitude: -0.1278, title: "London" }
]);

Settings

latitudeField

string

A field in data that holds the point’s latitude.

pointSeries.set("latitudeField", "lat");

longitudeField

string

A field in data that holds the point’s longitude.

pointSeries.set("longitudeField", "lon");

polygonIdField

string

A field in data that holds an ID of a related polygon.If set, the point will be positioned in the visual center of the target polygon.

pointSeries.set("polygonIdField", "countryId");

clipFront

boolean

If set to true, will hide all points that are in the visible range of the map.

clipBack

boolean

default:"true"

If set to true, will hide all points that are in the invisible range of the map.For example, on the side of the globe facing away from the viewer when used with Orthographic projection.Note: not all projections have an invisible side.

autoScale

boolean

default:"false"

If set to true, bullets will resize when zooming the MapChart.

Methods

zoomToDataItem(dataItem, zoomLevel, rotate?)

Animation<any> | undefined

Centers the map to a specific series data item and zooms to the specified level.

Show Parameters

dataItem

DataItem<IMapPointSeriesDataItem>

required

Map point

zoomLevel

number

required

Target zoom level

rotate

boolean

If true, the map will rotate so this point is centered (useful with geoOrthographic projection)

pointSeries.zoomToDataItem(dataItem, 4, true);

zoomToDataItems(dataItems, rotate?)

Animation<any> | undefined

Zooms the map so that all points in the array are visible.

Show Parameters

dataItems

Array<DataItem<IMapPointSeriesDataItem>>

required

An array of data items to zoom to

rotate

boolean

Rotate the map so it is centered on the selected items

pointSeries.zoomToDataItems([dataItem1, dataItem2]);

Data Item Fields

geometry

GeoJSON.Point | GeoJSON.MultiPoint

GeoJSON geometry of the point.

longitude

number

Longitude of the point.

latitude

number

Latitude of the point.

positionOnLine

number

Relative position (0-1) on a MapLine to place the point on.

autoRotate

boolean

Automatically rotate the point bullet to face the direction of the line it is attached to.

autoRotateAngle

number

The angle will be added to the automatically-calculated angle. Can be used to reverse the direction.

lineDataItem

DataItem<IMapLineSeriesDataItem>

A data item from a MapLineSeries the point is attached to.

lineId

string

An ID of a MapLine the point is attached to.

polygonDataItem

DataItem<IMapPolygonSeriesDataItem>

A data item from a MapPolygonSeries to use for positioning of the point.

polygonId

string

An ID of the MapPolygon to use for centering the point.

fixed

boolean

default:"false"

If set to true, the point will be drawn according to its x and y coordinates, not its latitude and longitude.Fixed points will not move together with the map, and cannot be used to connect points on a MapLineSeries.

MapLineSeries

Creates a map series for displaying lines on the map.

Creating a MapLineSeries

const lineSeries = chart.series.push(
  am5map.MapLineSeries.new(root, {
    stroke: am5.color(0xff0000),
    strokeWidth: 2
  })
);

lineSeries.mapLines.template.setAll({
  stroke: am5.color(0x000000),
  strokeWidth: 2
});

Settings

clipBack

boolean

If set to true, will hide line segments that are in the invisible range of the map.For example, on the side of the globe facing away from the viewer when used with Orthographic projection.Note: not all projections have an invisible side.

lineType

'curved' | 'straight'

default:"curved"

A line type.

"curved" (default) - connects points using shortest distance, which will result in curved lines based on map projection
"straight" - connects points using visually straight lines, and will not cross the -180/180 longitude

lineSeries.set("lineType", "straight");

Properties

mapLines

ListTemplate<MapLine>

A ListTemplate of all lines in the series.Use mapLines.template to configure line appearance.

lineSeries.mapLines.template.setAll({
  stroke: am5.color(0x000000),
  strokeWidth: 2,
  strokeDasharray: [2, 2]
});

Data Item Fields

geometry

GeoJSON.LineString | GeoJSON.MultiLineString

GeoJSON geometry of the line.

mapLine

MapLine

Related MapLine object.

pointsToConnect

Array<DataItem<IMapPointSeriesDataItem>>

An array of data items from MapPointSeries to use as line end-points.Note: fixed points cannot be used here.

lineSeries.data.push({
  pointsToConnect: [point1DataItem, point2DataItem]
});

lineType

'curved' | 'straight'

default:"curved"

A line type for this specific data item.

GraticuleSeries

A MapChart series to draw a map grid (lines of latitude and longitude).

Creating a GraticuleSeries

const graticuleSeries = chart.series.push(
  am5map.GraticuleSeries.new(root, {
    step: 10
  })
);

graticuleSeries.mapLines.template.setAll({
  stroke: am5.color(0x000000),
  strokeOpacity: 0.1
});

Settings

step

number

default:"10"

Place a grid line every Xth latitude/longitude.

graticuleSeries.set("step", 15);

clipExtent

boolean

If set to true, the graticule will be clipped to the visible map bounds.

See Graticule series for more info.

ClusteredPointSeries

Extends MapPointSeries to automatically group nearby points into clusters.

Creating a ClusteredPointSeries

const clusteredSeries = chart.series.push(
  am5map.ClusteredPointSeries.new(root, {
    minDistance: 30,
    latitudeField: "latitude",
    longitudeField: "longitude"
  })
);

clusteredSeries.set("clusteredBullet", (root, series, dataItem) => {
  const container = am5.Container.new(root, {});
  
  const circle = container.children.push(
    am5.Circle.new(root, {
      radius: 20,
      fill: am5.color(0xff0000),
      centerX: am5.p50,
      centerY: am5.p50
    })
  );
  
  const label = container.children.push(
    am5.Label.new(root, {
      text: "{count}",
      fill: am5.color(0xffffff),
      centerX: am5.p50,
      centerY: am5.p50
    })
  );
  
  return am5.Bullet.new(root, { sprite: container });
});

Settings

minDistance

number

default:"20"

Bullets that are closer than X pixels apart will be automatically grouped.See Minimal distance for more info.

groupIdField

string

default:"groupID"

Series data can contain a field with an ID of a virtual group the bullet belongs to.For example, we might want bullets to group only with other bullets from the same continent.groupIdField specifies which field in source data holds group IDs.See Group segregation for more info.

clusteredBullet

(root, series, dataItem) => Bullet | undefined

Set this to a Bullet instance which will be used to show groups.See Group bullet for more info.

singleBullet

(root, series, dataItem) => Bullet | undefined

Set this to a Bullet instance which will be used to show single (non-clustered) points.

stopClusterZoom

number

If set, clustering will stop when zoom level reaches this value.See Stop clustering for more info.

scatterDistance

number

Distance in pixels between scattered bullets when cluster is opened.See Cluster scatter for more info.

scatterRadius

number

Radius in pixels for scattering bullets when cluster is opened.

Common Series Settings

All map series inherit from the base MapSeries class and share these common settings:

geoJSON

GeoJSON.GeoJSON

Map data in GeoJSON format.

include

string[]

An array of map object IDs from geodata to include in the map.

exclude

string[]

An array of map object IDs from geodata to omit when showing the map.

valueField

string

A field in series data that will hold the map object’s numeric value.

geodataNames

{ [index: string]: string }

Names of geodata items to replace from loaded geodata.

affectsBounds

boolean

default:"true"

Whether this series affects the calculated bounds shown in the MapChart.

Events

geodataprocessed

{}

Invoked when geodata is finished loading and processed.

polygonSeries.events.on("geodataprocessed", () => {
  console.log("Geodata loaded");
});

Core

Shapes

Controls

XY Charts

Map Charts

Stock Charts

Hierarchy Charts

Utilities

Overview

MapPolygonSeries

Creating a MapPolygonSeries

Settings

Properties

Methods

Data Item Fields

MapPointSeries

Creating a MapPointSeries

Settings

Methods

Data Item Fields

MapLineSeries

Creating a MapLineSeries

Settings

Properties

Data Item Fields

GraticuleSeries

Creating a GraticuleSeries

Settings

ClusteredPointSeries

Creating a ClusteredPointSeries

Settings

Common Series Settings

Events

Build docs developers (and LLMs) love

Core

Shapes

Controls

XY Charts

Map Charts

Stock Charts

Hierarchy Charts

Utilities

​Overview

​MapPolygonSeries

​Creating a MapPolygonSeries

​Settings

​Properties

​Methods

​Data Item Fields

​MapPointSeries

​Creating a MapPointSeries

​Settings

​Methods

​Data Item Fields

​MapLineSeries

​Creating a MapLineSeries

​Settings

​Properties

​Data Item Fields

​GraticuleSeries

​Creating a GraticuleSeries

​Settings

​ClusteredPointSeries

​Creating a ClusteredPointSeries

​Settings

​Common Series Settings

​Events

Build docs developers (and LLMs) love

Overview

MapPolygonSeries

Creating a MapPolygonSeries

Settings

Properties

Methods

Data Item Fields

MapPointSeries

Creating a MapPointSeries

Settings

Methods

Data Item Fields

MapLineSeries

Creating a MapLineSeries

Settings

Properties

Data Item Fields

GraticuleSeries

Creating a GraticuleSeries

Settings

ClusteredPointSeries

Creating a ClusteredPointSeries

Settings

Common Series Settings

Events