Blog Help & Support Contact About Login

 Show Nav

Javascript Maps

ZingChart features an expanding assortment of map modules which can be used to render different interactive geographical maps. ZingChart includes a large variety of predefined maps such as world maps, countries, country subregions, etc. In addition to being able to use the predefined ZingChart maps, you can pass ZingChart GeoJSON or TopoJSON data to create arbitrary map shapes. Once you have defined the appropriate map shapes, you can leverage ZingChart’s JSON attributes and JavaScript API to customize your maps and add helpful interactivity.

Available Maps: Lets get a little more familiar by clicking through some of the map types in the following Demo.

Note: You can find the comprehensive list of all available maps here.

Hello World Tutorial

Rendering a geographical map in ZingChart requires a few additional steps in comparison with core ZingChart chart types. There is a live demo with comments below.

1) Load the ZingChart library

You can choose to access the library in a variety of ways. All options will provide access to the same software package. It’s up to you to determine what’s best for you. ZingChart is available from our CDN (our easiest option, especially for first-time users). You can also download the library, fork demos to CodePen, or use the Bower, npm, or NuGet package management systems.

<script src='https://cdn.zingchart.com'></script>

2) Load the ZingChart Modules Directory

Map modules are not automatically loaded by ZingChart. They must be explicitly loaded using the zingchart.loadModules() method. Before attempting to load the maps modules, ensure that the zingchart.MODULESDIR variable is correctly configured to point to the modules directory included with ZingChart.

<script src='https://cdn.zingchart.com'></script>
<script>zingchart.MODULESDIR = "path/to/modules/";</script>

3) Make the call to zingchart.loadModules()

Pass zingchart.loadModules() with a comma-separated string of map module names.

zingchart.loadModules('maps, maps-world-continents');

4) Create shapes array

In ZingChart, maps are configured as shape objects. Create a "shapes" array in your chart configuration:

{
    "shapes":[ ]
}

Now place an object within the array, with the type "zingchart.maps":

{
  "shapes":[
    {
      "type":"zingchart.maps"
    }
  ]
}

Note: Maps are simply predefined shapes. Your JSON configuration will rely heavily on the shapes:[] array and options:{} object. Since ZingChart Maps are simply shapes at the lowest level, anything you can do to a ZingChart Shape you can do to our maps (i.e., JSON attributes, api shape_click events, etc.)

Finally, within the shape object, create an options object and set the name attribute within that to the name of the map that you have loaded previously:

{
  "shapes":[
    {
      "type":"zingchart.maps",
      "options":{
        "name":"world.continents"
      }
    }
  ]
}

Demo Click the HTML and Javascript tags to see comments.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Basic Map Customization

Lets go over some of the basic map styling attributes.

Map Styling

ZingChart does provide features to customize and style your maps. This is most commonly done inside of the options:{} object. Inside of options:{}, you can include a style:{} object to make global changes to all map shapes and labels. If you want to create a style to a specific map shape you can include an items:{} object inside of style, and then create an object for each shape you want to modify and add styles specific to that shape.

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Example

{
  shapes:[
    {
      type:'zingchart.maps',
      options:{
        name:'world.countries',
        style:{ //stlye all countries 
          backgroundColor: '#cccccc',
          label:{ 
            visible: false
          },
          items:{ //include specific shape regions with unique styles
            USA:{
              backgroundColor:'#0D47A1',
              label:{
                visible: true,
                fontColor: '#ffffff'
              }
            },
            BRA:{
              backgroundColor: '#4CAF50',
              label:{
                visible: true,
                fontColor: '#ffffff'
              }
            },
            IND:{
              backgroundColor: '#FF6F00',
              label:{
                visible: true,
                fontColor: '#ffffff'
              }
            }
            
          }
        }
      }
    }
  ]
}
Note: Again, keep in mind that ZingCharts Javascript maps are simply collections of shapes. If you want to style a map shape you can use the same JSON properties as you find in the rest of the ZingChart library. The Shapes JSON attributes page is a great place to start.

Hover-States

ZingChart does provide the ability to modify the style of each map shape based on a user hovering over a specific shape. This can be modified in the global style:{} object to affect all shapes. Additionally, you can configure a specific style for individual shapes by including the hoverState:{} configuration in each shape specific object.

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Example

{
  shapes:[
    {
      type:'zingchart.maps',
      options:{
        name:'world.countries',
        style:{ 
          backgroundColor:'#cccccc',
          hoverState:{ //affects all shapes
            backgroundColor:'#555555'
          },
          label:{ 
            visible: false
          },
          items:{ 
            USA:{
              backgroundColor:'#0D47A1',
              label:{
                visible: true,
                fontColor: '#ffffff'
              },
              hoverState:{ //affect just the USA shape
                backgroundColor: '#1565C0',
                borderColor: "#555555",
                borderWidth: 2
              }
            },
            BRA:{
              backgroundColor: '#4CAF50',
              label:{
                visible: true,
                fontColor: '#ffffff'
              },
              hoverState:{ //affect just Brazil shape
                backgroundColor: '#66BB6A',
                borderColor: "#555555",
                borderWidth: 2
              }
            },
            IND:{
              backgroundColor: '#FF6F00',
              label:{
                visible: true,
                fontColor: '#ffffff'
              },
              hoverState:{ //affect just the India shape
                backgroundColor:'#FF8F00',
                borderColor: "#555555",
                borderWidth: 2
              }
            }
          }
        }
      }
    }
  ]
}

Customized Tooltips

It is common for developers to modify the tooltip associated with any given map shape. ZingChart gives developers the ability to modify both the styling and the text of the tooltips. You can define a tooltip style and text globally across all tooltips. You can also include shape specific style and text.

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Example

{
  shapes:[
    {
      type:'zingchart.maps',
      options:{
        name:'world.countries',
        style:{ 
          backgroundColor:'#cccccc',
          hoverState:{ //affects all shapes
            backgroundColor:'#555555'
          },
          label:{ 
            visible: false
          },
          tooltip:{ //configuration for global tooltip 
            borderColor: '#555555',
            borderWidth: 2,
            fontColor: "#ffffff",
            backgroundColor:'#555555'
          },
          items:{ 
            USA:{
              backgroundColor:'#0D47A1',
              label:{
                visible: true,
                fontColor: '#ffffff'
              },
              hoverState:{ 
                backgroundColor: '#1976D2',
                borderColor: "#555555",
                borderWidth: 2
              },
              tooltip:{ //tooltip styling and text specific to shape
                text:"United States<br>50 States in Region",
                backgroundColor: '#1976D2'
              }
            },
            BRA:{
              backgroundColor: '#4CAF50',
              label:{
                visible: true,
                fontColor: '#ffffff'
              },
              hoverState:{
                backgroundColor: '#66BB6A',
                borderColor: "#555555",
                borderWidth: 2
              },
              tooltip:{ //tooltip styling and text specific to shape
                text: "Brazil<br>26 States in Region",
                backgroundColor: '#66BB6A'
              }
            },
            IND:{
              backgroundColor: '#FF6F00',
              label:{
                visible: true,
                fontColor: '#ffffff'
              },
              hoverState:{
                backgroundColor:'#FF8F00',
                borderColor: "#555555",
                borderWidth: 2
              },
              tooltip:{ //tooltip styling and text specific to shape
                text: "India<br>29 States and 7 Union<br>Territories in Region",
                backgroundColor: '#FF8F00'
              }
            }
          }
        }
      }
    }
  ]
}

Getting Started with the API

Since our maps are just shapes, if you want to leverage our API for events you can use the shape_click and shape_mouseover events. This is useful when you want to extend maps customization further.

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Note: It is common to not know what keys are available within the items:{} object. You can skip ahead to our API method getInfo() or getItems. These methods will return the information needed to access and style individual map shapes.

Drilldown

A demo illustrating how to implement drilldown functionality with our maps. Via our API you can register shape_click and in that event render a new chart. If you have more questions feel free to chat us!

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Maps Options

The options:{} object is where we define all of our map attributes.

bbox

Sets the bounding box for a map object with a 4 length array of longitude, latitude coordinates. Useful for overlaying multiple maps. This is how you would layer subregions.

Usage

"bbox": [ <Min. Longitude>, <Min. Latitude>, <Max Longitude>, <Max Longitude> ]

Example

// Bounding box for Los Angeles County:
"bbox": [ -118.9449036, 32.7983762, -117.6456041, 34.8231929 ]

Simple Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

Complex geoJSON Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

groups

Defines a group or multiple groups of items (only for world-countries) to be displayed.

Usage

"groups": [ <Group Name 1> , <Group Name 2>]

Example

"groups":[ "NORTHAMERICA" ]

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

ignore

Defines a list of items that will be excluded in the map.

Usage

"ignore": [ <Item Name 1> , <Item Name 2>]

Example

"ignore":["TL","MH","KA","TN"]

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

items

Defines a list of items that will be included in the map.

Usage

"items": [ <Item Name 1> , <Item Name 2>]

Example

"items":["TL","MH","KA","TN"]

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

offset-x

Defines the horizontal offset for a map object.

Usage

"offset-x": <Horizontal Offset Value>

Example

"offset-x": -50

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

offset-y

Defines the vertical offset for a map object.

Usage

"offset-y": <Vertical Offset Value>

Example

"offset-y": 10

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

scale

Defines whether or not the map scales to fit the width and height while forcing the normal aspect of the map. The default value is true.

Usage

"scale": true | false

Example

"scale": false

Demo

zoom

Sets the level of zoom for a map object.

Usage

"zoom": <Zoom Value>

Example

"zoom": 5

Demo


Maps API

zingchart.maps.getInfo(String mapId)

Returns various information about the map: placement information, map's latitude and longitude bounding box, content filters (items, ignore and group lists).

Parameter Type Info
mapId String Required. Map's id specified in the JSON (if API is called after map was rendered) or the map name (see list above) if the API is being called before map rendering.

Example

zingchart.maps.getInfo('world-countries');

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

zingchart.maps.getItems(String mapId)

Returns a list of items available in the current map.

Parameter Type Info
mapId String Required. Map's id specified in the JSON (if API is called after map was rendered) or the map name (see list above) if the API is being called before map rendering.

Example

zingchart.maps.getItems('can');

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

zingchart.maps.getItemInfo(String mapId, String itemId)

Returns that specific objects info (tooltip,label,coords, cpoint)

Parameter Type Info
mapId String Required. Map's id specified in the JSON (if API is called after map was rendered) or the map name (see list above) if the API is being called before map rendering.
itemId String Required. Map's id specified in the JSON (if API is called after map was rendered) or the map name (see list above) if the API is being called before map rendering.

Example

zingchart.maps.getItemInfo('chn', 'ZJ');

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

zingchart.maps.getXY(String mapId, Array coordinates [, String itemId])

Returns that specific xy position based on latitude and longitude. By far the most useful API method because it allows you to add geographical shapes and labels to the chart.

Parameter Type Info
mapId String Required. Map's id specified in the JSON (if API is called after map was rendered) or the map name (see list above) if the API is being called before map rendering.
coordinates Array Required. Array containing a set of longitude, latitude coordinates. Longitude west and latitude south values need to be negative values. Longitude east and latitude north values need to be positive values.
itemId String Optional. Sets the reference map item that is being used when translating from [lon, lat] to [x, y]. Needs to be specified in case of translated map items (for example, Hawaii or Alaska in USA map).

Example

// Longtitude, latitude for San Diego on 800x600 map of USA.
zingchart.maps.getXY('myMap', [-117.1625, 32.7150]);

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

zingchart.maps.getLonLat(String mapId, Array point)

Returns calculated longitude and latitude for a specific [x, y] point on a map.

Parameter Type Info
mapId String Required. Map's id specified in the JSON (if API is called after map was rendered) or the map name (see list above) if the API is being called before map rendering.
point Array Required. Array of x and y coordinates relative to the chart's top-left corner.

Example

zingchart.maps.getLonLat('myMap', [146.97727272727272,157.88779385938727]);

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart

zingchart.maps.loadGeoJson(<Object> options)

Creates a ZingChart map from a GeoJSON file. Supports Point, LineString, MultiLineString, Polygon, & MultiPolygon geometry objects, as well as FeatureCollection objects.

Option Type Info
id String Required. An ID for the map object that will be generated from the GeoJSON object.
url String Required. The URL of the GeoJSON object document.
style Object Optional. Styling attributes.
mappings Object Optional. Allows you to configure which properties to use for the "name" and "id" properties of each item in the map. For example, a feature from an original GeoJSON file's FeatureCollection may have the following properties object:
"properties" : {
  "nombre": "Baja California",
  "code": "MX-BCN"
}
In this case, the "mappings" options within the call to loadGeoJSON() would be configured like so:
"mappings": {
  "name": "nombre",
  "id": "code"
}
callback Function Optional, but recommended! The function to be executed once the GeoJSON is loaded. Typically used to call the render method for the map that will be using the newly loaded GeoJSON.

Available from ZingChart v2.1.0 on.

The GeoJSON module allows you to easily create your own ZingChart maps from objects using files that utilize the GeoJSON specification.

Usage

  1. Include the core maps module and the maps-geojson module in your page:

    <script src="http://cdn.zingchart.com/zingchart.min.js"></script>
    <script src="http://cdn.zingchart.com/modules/zingchart-maps.min.js"></script>
    <script src="http://cdn.zingchart.com/modules/zingchart-maps-geojson.min.js"></script>

    OR

    <script src="http://cdn.zingchart.com/zingchart.min.js"></script>
    <script>
    zingchart.MODULESDIR = 'http://cdn.zingchart.com/modules/';
    zingchart.loadModules('maps, maps-geojson',function(){
      zingchart.maps.loadGeoJSON({...}); // loadGeoJSON in callback of loadModules
    );
    </script>

    You can also replace the CDN paths with paths to your local copies of ZingChart.

  2. Set up the call to the loadGeoJSON() method.

    zingchart.maps.loadGeoJSON({
      "id": "Custom_India_Map",
      "url": "//demos.zingchart.com/view/ABV7SXVB/india.json",
      "mappings": {
        "id": "NAME_1",
        "name": "NAME_1"
      },
      "style":{
        "poly":{
            "label":{
              "visible":true
            }
        }
      },
      callback: function(){
        zingchart.render({
          "id":'myChart',
          "width":'100%',
          "height":'100%',
          "data":{
            "shapes": [
              {
                "type": "zingchart.maps",
                "options":{
                  "name": "Custom_India_Map",
                  "style":{...

Demo

Loading...
Result
HTML
JavaScript
CSS
A beautiful chart


Available Maps

Below is a complete list of all currently available maps.

Map ([JSON name] [module]) Map ([JSON name] [module])
Afghanistan ([afg] [maps-afg]) Kenya ([ken] [maps-ken])
Albania ([alb] [maps-alb]) Kuwait ([kwt] [maps-kwt])
Andorra ([and] [maps-and]) Lao ([lao] [maps-lao])
Angola ([ago] [maps-ago]) Latvia ([lva] [maps-lva])
Armenia ([arm] [maps-arm]) Liberia ([lbr] [maps-lbr])
Argentina([arg] [maps-arg]) Liechtenstein ([lie] [maps-lie])
Australia ([aus] [maps-aus]) Lithuania ([ltu] [maps-ltu])
Austria ([aut] [maps-aut]) Luxembourg ([lux] [maps-lux])
Azerbaijan ([aze] [maps-aze]) Macedonia ([mkd] [maps-mkd])
Belarus ([blr] [maps-blr]) Mexico ([mex] [maps-mex])
Belgium ([bel] [maps-bel]) Moldova ([mda] [maps-mda])
Benin ([ben] [maps-ben]) Montenegro ([mne] [maps-mne])
Bhutan ([btn] [maps-btn]) Mozambique ([moz] [maps-moz])
Bolivia ([bol] [maps-bol]) Namibia ([nam] [maps-nam])
Bosnia and Herzegovina ([bih] [maps-bih]) Netherlands ([nld] [maps-nld])
Botswana ([bwa] [maps-bwa]) New Caledonia ([ncl] [maps-ncl])
Brazil ([bra] [maps-bra]) New Zealand ([nzl] [maps-nzl])
Brunei Darussalam ([brn] [maps-brn]) Nigeria ([nga] [maps-nga])
Bulgaria ([bgr] [maps-bgr]) Norway ([nor] [maps-nor])
Burkina Faso ([bfa] [maps-bfa]) Oman ([omn] [maps-omn])
Burundi ([bdi] [maps-bdi]) Pakistan ([pak] [maps-pak])
Cameroon ([cmr] [maps-cmr]) Panama ([pan] [maps-pan])
Canada ([can] [maps-can]) Papua New Guinea ([png] [maps-png])
Central African Republic ([caf] [maps-caf]) Peru ([per] [maps-per])
Chile ([chl] [maps-chl]) Philippines ([phl] [maps-phl])
China ([chn] [maps-chn]) Poland ([pol] [maps-pol])
Colombia ([col] [maps-col]) Portugal ([prt] [maps-prt])
Congo ([cog] [maps-cog]) Qatar ([qat] [maps-qat])
Costa Rica ([cri] [maps-cri]) Romania ([rou] [maps-rou])
Cộte d’Ivoire ([civ] [maps-civ]) Russia ([rus] [maps-rus])
Croatia ([hrv] [maps-hrv]) Rwanda ([rwa] [maps-rwa])
Cuba ([cub] [maps-cub]) Senegal ([sen] [maps-sen])
Cyprus ([cyp] [maps-cyp]) Serbia ([srb] [maps-srb])
Czech Republic ([cze] [maps-cze]) Slovenia ([svn] [maps-svn])
Denmark ([dnk] [maps-dnk]) South Africa ([zaf] [maps-zaf)
Ecuador ([ecu] [maps-ecu]) South Korea ([kor] [maps-kor])
Egypt ([egy] [maps-egy]) Spain ([esp] [maps-esp])
Spain with regions ([espL2] [maps-espL2]) Estonia([est] [maps-est])
Finland ([fin] [maps-fin]) Suriname ([sur] [maps-sur])
France ([fra] [maps-fra]) France with regions ([fraL2] [maps-fraL2])
French Guyana ([guf] [maps-guf]) Sweden ([swe] [maps-swe])
Gabon ([gab] [maps-gab]) Switzerland ([che] [maps-che])
Gambia ([gmb] [maps-gmb]) Taiwan ([twn] [maps-twn])
Germany ([deu] [maps-deu]) Tajikistan ([tjk] [maps-tjk])
Ghana ([gha] [maps-gha]) Thailand ([tha] [maps-tha])
Great Britain ([gbr] [maps-gbr]) Great Britain with Regions ([gbrL2] [maps-gbrL2])
Greece ([grc] [maps-grc]) The Democratic Republic of the Congo ([cod] [maps-cod])
Guatemala ([gtm] [maps-gtm]) Tunisia ([tun] [maps-tun])
Guinea-Bissau ([gnb] [maps-gnb]) Turkey ([tur] [maps-tur])
Guyana ([guy] [maps-guy]) Uganda ([uga] [maps-uga])
Hungary ([hun] [maps-hun]) Ukraine ([ukr] [maps-ukr])
Iceland ([isl] [maps-isl]) United Arab Emirates ([are] [maps-are])
India ([ind] [maps-ind]) United States ([usa] [maps-usa])
Iran ([irn] [maps-irn]) Uruguay ([ury] [maps-ury])
Ireland ([irl] [maps-irl]) Uzbekistan ([uzb] [maps-uzb])
Israel ([isr] [maps-isr]) Venezuela ([ven] [maps-ven])
Italy ([ita] [maps-ita]) Vietnam ([vnm] [maps-vnm])
Japan ([jpn] [maps-jpn]) Yemen ([yem] [maps-yem])
Kazakhstan ([kaz] [maps-kaz]) Zambia ([zmb] [maps-zmb])
Zimbabwe ([zwe] [maps-zwe])
World Continents ([world.continents] [maps-world-continents])
World Countries ([world.countries] [maps-world-countries])

Groups: NORTHAMERICA, SOUTHAMERICA, ASIA, EUROPE, AFRICA, AUSTRALIA