jVectorMap – Creating Custom JavaScript Maps

jVectorMapBased on the jQuery framework, jVectorMap provides a convenient top-level map plugin for websites.  Although the plugin doesn’t have the full flexibility of Google Maps, it does provide a way to link countries or states to user interface actions.  With a wide suite of available maps, the ready-built package can suffice for most purposes.  On more advanced websites, however, it is sometimes necessary to create custom maps for additional geographic regions.

There are two primary steps in custom map development – the first is obtaining source data for the map, and the second is converting that data into the format used by jVectorMap.  The map source data can be downloaded from Natural Earth Data, a website that takes public domain mapping information and organizes it in a central repository.  The “ne_10m_admin_1_states_provinces” map collection provides a full map of the world, together with state and province-level divisions within countries.  The map data is provided in the Shapefile format, which can be read by the open source QGIS software.  Before converting the Shapefile into the jVectorMap format, it is recommended to review the file contents in QGIS and create a plan for the file conversion.

The Shapefile from Natural Earth Data has two main components – the actual map coordinates, and the province-level features.  Features have information such as province name, location, Wikipedia URL, and country name.  Over 50 different features are provided in the Shapefile format.  In order to browse the available features, a program called “ogrinfo” from GDAL can be used to parse and query the Shapefile’s internal database:

ogrinfo.exe -al ne_10m_admin_1_states_provinces.shp -fields=YES -geom=NO

With the Shapefile data reviewed, the next step is to use a converter program to extract the target data into a jVectorMap format.  This is done through a converter tool provided in the jVectorMap source package.  Getting this tool to work can be a challenge due to versioning dependencies – the easiest method is to download OSGeo4W, perform the Express Desktop installation, installing a variety of pre-requisites and the gdal-python library.  Then, using the OSGeo4W shell and specifically referencing OSGeo4W’s python executable, the program should run properly.  Due to errors in the current converter.py program, it may also be necessary to add the following code to the top of the file:

import shapely.wkb

Next, the converter can be run to parse the map file and extract country data:

c:\OSGeo4W64\bin\python.exe converter.py --country_code_index 14 --country_name_index 37 --longitude0 10.71 --where "iso_3166_2 = 'PL-'" --width 1000 --name "pl" --language "en" ne_10m_admin_1_states_provinces.shp pl.js

In this example, the program extracts the full map of Poland into the pl.js file.  It may be necessary to perform additional Regular Expression post-processing to bring the file into a format similar to the rest of the jVectorMap files:

Find: "(\w\w)\.([\w]*)": \{
Replace: "\1-\2": {

By combining a suite of open source software, from QGIS, to GDAL, to OSGeo4W, it is possible to generate vector maps from public domain Natural Earth Data.  These vector maps, in turn, can be used to create interactive user interface components on the web, ideal for applications from education, to sales and marketing.

Written by Andrew Palczewski

About the Author
Andrew Palczewski is CEO of apHarmony, a Chicago software development company. He holds a Master's degree in Computer Engineering from the University of Illinois at Urbana-Champaign and has over ten years' experience in managing development of software projects.

RSS Twitter LinkedIn Facebook Email

Leave a Reply

Your email address will not be published. Required fields are marked *