Map

JSMapping features and usage.

Mapping Overview

The JSMapping component is designed to be simple to use for all users; no mapping technology or mapping file format experience is required! JSMapping ships with specially designed and optimized maps for all world countries, included at no additional charge, including state and province level maps. For a comprehensive list of supported maps, please see:

The API lets users focus on data rather than map files and layers. Intuitive map codes such as 'us.ca' meaning California are used to specify map features to associate them with standard data points or series that are the same as those used for any other chart types. The files that contain these maps are automatically loaded in the background. The chart.mapping config options offer a number of helpful features such as base layers that allow defining a mapping context that surround the specific data point maps without the need of creating data series and styling them. For example, if a chart of 'us.ca' is used, the baseLayers can be set to 'us' and will show the surrounding states with a grayed out hue and will not affect the chart in any other way.

With the advanced functionality of JSMapping, many complex internal map data optimizations automatically take place behind the scenes to ensure the smallest files for your usage case are automatically selected (which minimizes download times and makes your site more responsive). In addition to file selection, JSMapping also automatically optimizes map resolution. The end result: maps that look and work better than you would expect with fewer lines of code and less work.

First Map

Loading a map in a chart is simple and can be accomplished by setting the series.map property with a map code.

JSC.chart("chartDiv", {
  type: "map",
  series: [{ map: "us" }]
});

For a list of map codes and maps see this Maps & MapCodes Tutorial.

Map Layers

All built in maps are available for use with map charts and referenced by mapCodes. It is not necessary to be aware of the actual map files used internally. Custom map files are also supported, in both geoJSON and topoJSON formats.

Series and Points from map layers

The series.map property can specify map codes that represent multiple map features and point.map property can specify map codes with single map features. When using the series.map property, data points are created for each map feature. For example, series[0].map='us' will generate a point for each U.S. state.

In order to style a specific point of this series, a point with a map property set to 'us.il' can be specified and this point object and its settings will be used.

JSC.chart("chartDiv", {
  type: "map",
  series: [{ map: "us", points: [{ map: "us.il", color: "blue" }] }]
});

If series.map property is set to a single feature such as 'us.il' a series with a single point is created. Similarly, If a point with map property set to 'us' is created, the point will contain only the U.S. Country as a single map feature.

Series from map queries

Maps don't have to be specified using these map feature codes. They can also be specified using property filters. For example, the following indicates that the series should be based on map features in the americas map where the continent property is 'North America'.

JSC.chart("chartDiv", {
  type: "map",
  series: [
    {
      map: "americas.continent:North America"
    }
  ]
});

This will create a series of points where each point is a North American country outline.

Maps with context

Map layers that are loaded for context can be specified through the mapping.base.layers property.

JSC.chart("chartDiv", {
  type: "map",
  mapping_base_layers: "americas",
  series: [{ map: "us" }]
});

Base Layers

Base layers can be specified through a list of country codes. This creates internal series with specialized behavior. These series do not influence the view bounds, and are not included in the legend. The purpose of these layers is to create context for maps and shows a continuation of landmasses. It can also be used to load custom map files which can then be used to build a series of points that refer to specific features of that custom map data. For example a map file with all us state capitals can be loaded as a base layer, then a series of just a few points that refer to specific capitals through the point.map property and include weather info. This will create a map that zooms in on only these few points.

When using built in maps, baseLayers do not have to be used in order to reference them in series and point map properties. Loading these maps is automatic.

Styling and settings for these base layers can be set through the mapping.base.series property.

Interactivity

Features

Map charts have zooming enabled by default. This adds a zoom toolbar that can be clicked to zoom in and out.

Zooming can be limited by setting the zoomLimit property. This example limits the zoom to 500% of the initial zoom level.

chartConfig.mapping_zoomLimit = 5;

To disable zooming, set the axisToZoom property to 'none'

chartConfig.axisToZoom = "none";

This will automatically disable the zooming toolbar as well. To disable only the zooming toolbar use:

chartConfig.toolbar_items_zoom_visible = false;

The zooming toolbar can not be modified, it can only be replaced with a custom toolbar. Except the position property can be applied to it.

chartConfig.toolbar_items_zoom_position = "inside bottom left";

When the chart is zoomed in, the resetZoom toolbar item appears. This can be disabled with:

chartConfig.toolbar_items_resetZoom_visible = false;

The default position of the resetZoom button may overlap other uiItems. Therefore, using a setting like this can help correct it:

chartConfig.toolbar_items_resetZoom_position = "inside top left";

Zoom and Pan

An intuitive API is provided for use with zooming operations through the chart.zoom() method.

Zoom depth

Zoom in a chart to 100% can be accomplished using the following code

chart.zoom(1);

Pan by

The current view can be panned by using an array of x and y values in map coordinates to pan the view by

chart.zoom([1, 1]);

Center and zoom

A map can be centered on a specific coordinate at a specific zoom level by using an array of three items; x, y, and zoom level like so:

chart.zoom([-91, 51, 1]);

Zoom to bbox

A four item array can be used to specify a bbox to zoom in on.

chart.zoom([-91, 51, 10, 15])

Get Current view bbox

Calling chart.zoom() without any arguments returns the current view bbox and can be used to calculate the amount of the view to pan or restore a map view.

var bbox = chart.zoom();

Zoom features into view

By passing a map code to the zoom method, the chart will zoom in on that feature.

chart.zoom("us");

Zoom features based on propertyFilters

By passing a property filter to the zoom method, the chart will zoom in on all matching map features.

chart.zoom("us.region:Midwest");

Events

Click Events

Map click events can be bound to the chart and will have access to clicked lat/long coordinates.

Map Properties

Map data properties are loaded as point attributes and are accessible in point related strings through tokens.

Built-in Map Properties and Tokens

A number of standard attribute properties are provided with the native JSCharting maps. These attribute tokens can be used with all maps that include such data. They can be used in label as tokens or in propertyFilters.

• '%name'
  The name of the map feature.
• '%mapCode'
  The map code of a map feature.
• '%country'
  Name of the country a map feature relates to.
• '%state'
  Name of the state or province if this map feature is one.
• '%province'
  Name of the state or province if this map feature is one.
• '%countryCode'
  ISO A2 country code of the map feature or its parent
• '%stateCode '
  The state or province postal code such as 'IL' for Illinois.
• '%provinceCode '
  The state or province postal code such as 'IL' for Illinois.
• '%worldRegion'
  World region such as americas or europe this map feature belongs to.
• '%countryRegion'
  The region of a country this state or province is part of.
• '%region'
  The world or country region depending on the map feature type.
• '%mapType'
  The map feature type such as Province or Country.

Country Specific properties

• '%continent'
  The continent the country resides in.
• '%iso_a3'
  ISO alpha-2 code.
• '%iso_n3'
  ISO numeric-3 code.

State/Province Specific properties

• '%fips'
  Fips code where applicable