Map collection

For your convenience, Highcharts Maps offers a free collection of maps, optimized for use with Highcharts Maps. For common maps, it saves you the trouble of finding or drawing suitable SVG or GeoJSON/TopoJSON maps. Instead, you can choose between hundreds of pre-generated maps of countries, regions and other administration levels.

License

The Highcharts Maps Map Collection comes with the license of the source data. For Admin0 (countries) and Admin1 (US states, German Bundesländer, Dutch regions etc), the source data is Natural Earth, which is Public Domain. For Admin2, we have only compiled selected countries, and these maps are created from national files with their own license which is specified on the SVG map and in the other format files as meta data. If your country is missing from the list, please contact us and we'll try to find a suitable shapefile and generate more maps. 

For maps loaded using the default TopoJSON or GeoJSON input into the mapData option, a short version of the copyright will be printed in the chart's credits label.

Using the map collection

Install from our CDN

In the map collection reference, each map name is followed by links to demos and data. Click the TopoJSON link and copy the URL.

  1. Load the map and parse the JSON
const topology = await fetch(
'https://code.highcharts.com/mapdata/custom/world.topo.json'
).then(response => response.json());

You can alternatively link to a specific version or subversion of the map at https://code.highcharts.com/mapdata/1.1/custom/world.topo.json.


  1. Apply it in chart.map to make it the default map for all series:
map: topology

Alternatively, you can apply different maps for different series (view demo):

series: [{
mapData: topology,
...
  1. Join your data with the map. By default Highcharts Maps is set up to map your data against the hc-key property of the map collection, allowing you to define your data like this:
data: [['us-ny', 0], ['us-mi', 5], ['us-tx', 3], ['us-ak', 5]]

For other data joining options, see the series.joinBy and series.keys options.

Install from npm

Our map collection is available on npm as @highcharts/map-collection and can be installed as following:

npm i @highcharts/map-collection

To load a map in Node.js and use it in Highcharts Maps you can do the following:

const Highcharts = require('highcharts/highmaps.js'),
map = require('@highcharts/map-collection/custom/world.topo.json');
Highcharts.mapChart('container', {
chart: {
map
},
// ...
});

Map properties

The following table outlines the properties available in the Highcharts Maps Map Collection maps, and their meaning. The properties are accessible from the point.properties object (example).

PropertyExample valuesDescriptionAvailability
hc-groupadmin1, admin2, specialThe administrative group the area belongs to. Admin0 is countries, admin1 is first level administrative division (USA States, German Bundesländer, Canada Provinces). Admin2 is second level administrative division (USA counties, German Kreise, Norwegian Kommuner). "Special" is used to denote an area where this grouping does not make sense (e.g. congressional districts, historical maps).All maps
hc-middle-lon47.885Data label X position. Defined as longitude on the map.All maps
hc-middle-lat15.932Data label Y position. Defined as a latitude on the map.All maps
hc-middle-x0.65Data label X position used if hc-middle-lon is not defined. Defined as fraction of map bounding box width. 0 is left aligned, 1 is right aligned.All maps
hc-middle-y0.65Data label Y position used if hc-middle-lat is not defined. Defined as fraction of map bounding box height. 0 is top aligned, 1 is bottom alignedAll maps
hc-keyus, us-ma-027, gb-hiUnique hierarchical identifier for the area. Consistent across maps, and reflected in the naming convention of the maps. More detailed description below.All maps
hc-a2KV, PA, BBTwo letter abbreviation of area name. Usually same as postal code/ISO code, but not always. Not guaranteed to be unique within map.All maps
nameFremont, Brandenburg, SaipanName of the areaAll maps
iso-a2US, MC, LVISO 2 letter country codeMost admin0 areas
iso-a3USA, MCO, LVAISO 3 letter country codeMost admin0 areas
continentAsia, North AmericaContinent the area lies withinMost admin0 areas
country-abbrevPan., C.R.Abbreviated country nameMost admin0 areas
regionMidwest, South, Highlands and IslandsThe region the area lies withinMost admin1 areas within country maps
subregionSouthern Europe, HighlandThe subregion the area lies withinMost admin0 and admin1 areas
fips120, GM10, US05, 56031FIPS code for the area. Format may vary between maps as to whether the country code is included.Most admin1 areas within country maps, as well as USA admin2 maps
hascDE.BB, US.ARHASC code for the areaMost admin1 areas within country maps
postal-codeAK, NY, TIPostal code for the area, usually two letters wideMost admin1 areas within country maps
typeState, Emirate, Fylke, LandDescription of the area typeMost admin1 areas within country maps

The hc-key property reflects the naming convention of the maps, and can be used for dynamic drilldown purposes. This is illustrated in the Map drilldown demo. The property follows the following format:

<unique admin0 id>-<unique admin1 id>-<unique admin2 id>-...

Attempts are made to use commonly known codes for each level, to increase readability. As an example, most countries are identified by their two letter ISO-3166 code. Most admin1 areas are identified by their postal codes. For United States, admin2 (county) areas are identified by their FIPS codes.

In addition to the above mentioned properties, all points have an id property that is stored on the point itself, rather than in the properties object. The id property is a unique ID for the point within the map. It follows a hierarchical system identical to that of the hc-key property, but uses capital letters and periods as delimiters.

Some maps may provide additional properties that are not mentioned in the above table. Open the GeoJSON/Javascript source of the map in a text editor to find all available properties.

Using parts of a map

If you can't find the exact map that you want in the collection, it is easy to use only selected parts of a larger area. Say you want a comparative map of Canada, USA and Mexico. Since we don't have that exact combination in the collection (as of now), you can use the map called "North America without Central". This map also contains Greenland as well as Caribbean islands. So we apply a data set only for the three countries we want, and set the allAreas option to false. This option makes sure all null points (the countries that don't have data), are hidden. See demo on jsFiddle.

Combine maps

Another way to approach the same problem, is to combine two or more map sources into the same chart. This is supported since Highcharts v9.3, where client-side projection is available. To achieve this, the unprojected TopoJSON maps must be used. See the demo on jsFiddle. See also the demo for the series.affectsMapView feature, which lets you load one map as a backdrop that doesn't affect the map view.

Modify our maps

Our maps are also a good starting points for your own modified maps. Borders can be moved, areas joined, and labels modified by loading the SVG map in Inkscape, the free SVG editor. Our article on Custom maps explains in detail how to draw your maps from scratch. Modifying existing maps is easier - instead of drawing shapes use the existing ones (SVG files can be downloaded from here) and perform the same operations as described in the article. Alternatively, follow the article on Custom GeoJSON maps to edit the map with a GIS editor for even more control and advanced mapping features.

Disclaimer

We offer the map collection for free to use with Highcharts Maps, for your convenience. We will not be held responsible for errors in the maps, although we will strive to respond to bug reports and keep the maps correct.