Why to convert?

In order to improve performance, especially on mobile platforms, jVectorMap uses special format for maps. This format was developed to avoid reprojection and conversion of map data on each page load and at the same time to preserve ability to render geo-coded data on vector maps.


In order to run the converter you need python version 2.7 or later and the following python packages:

General usage

Converter synopsis is python input_file.json, where input_file.json is a configuration file in JSON format containing a set commands. In case no file is specified converter will expect to get input from STDIN.

All the maps on this site were produced by, you can find the configuration file for each map under section "Processor config" on map's page. So if you want to make some slight modifications to some map form the site just copy and paste existing config, change it and consume to converter.

Here is an example of basic converter configuration file:

  "name": "read_data",
  "file_name": "new-york-boroughs/nybb.shp"
  "name": "write_data",
  "format": "jvectormap",
  "params": {
    "code_field": "BoroCode",
    "name_field": "BoroName",
    "name": "us-ny-newyork"

This simple config tells converter to read geometries from ShapeFile and then write them to jVectorMap format without any modifications. You can add some additional commands between read_data and write_data to modify geometries and/or their related values. For example here is configuration which produces continents map:

  "name": "read_data",
  "file_name": "ne_110m_admin_0_countries_lakes/ne_110m_admin_0_countries_lakes.shp",
  "filter": "continent != \"Antarctica\" AND continent != \"Seven seas (open ocean)\"",
  "longitude0": 11.5
  "name": "join_data",
  "data": [
      ["Africa", "AF"],
      ["Asia", "AS"],
      ["Europe", "EU"],
      ["North America", "NA"],
      ["South America", "SA"],
      ["Oceania", "OC"]
  "fields": [{
      "name": "continent",
      "type": 4,
      "width": 100
      "name": "cont_code",
      "type": 4,
      "width": 4
  "on": "continent"
  "name": "union",
  "by": "cont_code"
  "name": "write_data",
  "format": "jvectormap",
  "params": {
    "code_field": "cont_code",
    "name_field": "continent",
    "name": "continents"

Command join_data is used to set codes for each continents, after that countries are merged by supplied codes using union command and then converter writes them to file in jVectorMap-compatible format.

Available commands

  • read_data - read geometries from GIS data file
    • file_name - the name of the file to read
    • longitude0 - central meridian coordinate
    • projection - the map projection to use, currently implemented projections are merc (Mercator), mill (Miller Cylindrical), aea (Albers Equal Area), lcc (Lambert Conformal Conic)
  • write_data - writes geometries to file
    • file_name - the name of the file to write
    • format - format of data to write, jvectormap for jVectorMap compatible format, no value for OGR format
    • params - hash with parameters to supply to writer, the following parameters are used in case of jvectormap format:
      • code_field - name of field to use as a region code
      • name_field - name of field to use as a region name
      • name - map base name
  • union - merges geometries with the same value for one field
    • by - the name of the field to merge geometries by
  • join_data - adds or rewrites properties for geoemtry based on equal values in another field, works similar to JOIN operation from SQL
    • data - this could raw data to join or file name of CSv file with data to load
    • fields - array describing fields, which data contains
    • on - field to match to join data
  • remove - removes geometries and their properties based on logical expression
    • where - expression to evaluate for each geometry
  • remove_fields - removes fields and associated properties
    • fields - array with field names to remove
  • remove_other_fields - removes all fields and associated properties except the ones provided
    • fields - array with field names to preserve
  • buffer - removes (erosion) or adds (dilation) zone around every geoemtry
    • distance
    • resolution
  • simplify_adjancent_polygons - simplifies polygons taking topology into account (shared borders remain shared after operation)
    • tolerance - simplification tolerance
  • intersect_rect - cuts out everything beyond boubdaries of supplied rectangle
    • rect - array with four values, defining left-top and right-bottom corners of rectange
  • remove_small_polygons - removes polygons which area is less than supplied value
    • minimal_area

Data sources