Creating custom maps for JavaScript amMap

You can create your own custom maps and use them with amMap – a tool for creating interactive JavaScript maps for web sites. AmMap uses SVG maps. It can load SVG file or you can include JavaScript file with SVG data converted to JSON. This option is better as loading SVG might be problematic, depending on user browser and sometimes on your server.

SVG structure

AmMap will not work with any SVG map, it should meet some structure requirements. To understand SVG structure, open any of the maps available in ammap/maps/svg/ folder with some text editor. As you see, the structure which amMap understands is this:

<svg>
   <g>
      <path/>
   </g>
</svg>

You can have any number of "paths" – areas or countries, you can call them as you wish. All of them should be in one group – between <g> and </g> nodes. This is the main rule of SVG suitable for amMap. Deeper levels of groups will be ignored, if you won't group paths, they will also be ignored, all other elements except paths will be ignored. Each path should have at least "id" attribute and "d" attribute. "d" attribute contains coordinates of your areas. Optionally it can have "title" attribute. "class" attribute is only used when viewing this SVG file directly on browser.

Most likely you also noticed <defs> node with some info in it. <defs> has <style> with some colors set. These colors are only used when viewing SVG file in browser, amMap doesn't care about them. However it cares about <amcharts:ammap> node with projection and boundary latitudes/longitudes. AmMap will work even without <defs> node, but you won't be able to use real life latitudes/longitudes without it. We will come back to this later.

What if you have SVG file with some other structure? Well, it won't work with amMap. You should modify your SVG so that it would meet amMap structure.

Creating SVG from GIS data

Note, the following tutorials might not work with all GIS data. You might need to do some manual work.

In most cases you won't have SVG map which you can modify, but you might have raw GIS data. There are plenty of resources with free GIS data online, Natural Earth Data is one of the best. Let's download small scale World map with county borders and unzip the package. You'll find some files there with extensions like .shp, .shx etc. We need to convert them to SVG format.

Option 1 – use Indie mapper online service

This option doesn't require any expensive software, however you will miss some of the possibilities.

Navigate to the mapper app and click on "Browse for KML/SHP/GPX" button and browse to the folder where you unzipped GIS data, select .shp file from there. Then click on "Browse for DBF" file and select the .dbf file from the same folder and click "Load". Once the map is loaded, you can go to "projection" and set projection to the one you wish. If you wish to use real life longitudes/latitudes with your map, you should choose "Mercator". Next, click "export" button, select "layered SVG", select "include data attributes in SVG" option, type some name and click "Generate file" button and "Export to your Computer" a bit later. Now you have SVG file – open it with your browser, you should see the map. Open the file with text editor – the structure is quite close to what we need, it only has some unnecessary information. We need the second <g> node with all data in it (you can try to delete the other nodes and open file in browser again to be sure you left the countries only). Delete all atributes of <g> except "transform". Then copy everything between <g> and </g> (including). Now you can scroll down to the using amMap parser section or study the second option.

Option 2 – use Avenza map publisher and Adobe Illustrator

This method it is quite expensive, as requires both Adobe illustrator and Avenza plugin. However you can try both of them for free. This will also require some manual work.

Install Adobe illustrator and then Avenza map publisher for illustrator. Launch illustrator, click File->Import Map Data –> Advanced. In the window opened, click "Add", then "Browse" near "Dataset", locate your .shp file, click "OK". Then select "Create new" radio button, click "editor" and click on Destination Coordinate System link. Locate WGS84 / World Mercator system (you can use any other system if you don't care about real life latitudes/longitudes). Click OK for 3 times and you should see the map now.

The dark side: We couldn't find a way to export id and title of an object to SVG (let us know if you'll find it). So the only way to keep id/title is to go to layers and manually name each layer. You should name them like this: US#USA or BR#Brasil – our map parser will understand this format.

Click file->Save As and save the map as SVG. Open the saved file in your browser – you should see a map. Now open it with some text editor – you'll see some empty <g> nodes and one should have a lot of <polygon> and <path> elements. This is the one we need. Copy all this node (including <g> and </g> to the clipboard and proceed to the next part of the tutorial.

Option 3 - use the Kartograph Python program

Kartograph.py is a powerful SVG map rendering program that enables you to add advanced visual map features such as CSS styles in vector maps. It also creates a better SVG coordinate space than Indie Mapper. It renders vector maps from shapefiles and PostGIS.

Kartograph.py does require a few more steps to set up but it is would be worth the effort for those who want better customization of their maps. To set up Kartograph.py, follow these instructions:

Windows users can follow the instructions here. If you're a Windows user, you may want to use the Anaconda Python environment to make the installation process easier.

Anaconda Python and Kartograph set-up Instructions for Windows Users:

For example, a Windows user could install the 32 bit Python 2.7 version of Anaconda by downloading the install file from here, and then run the Anaconda installation. After this installation has completed, the user would need go to download these Python .whl files for the following Python packages:

  • Shapely-1.5.13-cp27-none-win32.whl
  • pyproj-1.9.5-cp27-none-win32.whl
  • GDAL-1.11.4-cp27-none-win32.whl

Open your Anaconda program and navigate to the folder that you downloaded the above .whl files. For each of these three .whl files, run the pip install command in Anaconda. For example, enter pip install Shapely-1.5.13-cp27-none-win32.whl etc.

Finally, in your Anaconda program, you also need to install tinycss with the command:

conda install -c https://conda.anaconda.org/hargup tinycss

Once Anaconda has all the above Python packages installed, download Kartograph.py. Still in the Anaconda command line, change to directory where you downloaded the Kartograph.py files and run the installation script:

python setup.py install  Your Kartograph installation for Windows is now complete.

Using Kartograph

Now that you've installed Kartograph.py, you can create a map. Lets create a map of the island of Dominica using its shapefile map (download). You will need to set up a json file that instructs Kartograph.py in how to create the vector map. The .json file parameters will have something like the following:

{
  "proj": {
    "id": "mercator",
    "lon0": -61.33
  },
  "export": {
  "width": 800
  },
    "layers": {
    "mylayer": {
      "src": "Dominica.shp",
      "attributes": ["name", “gn_a1_code” ]
    }
  }
}

You can save the above json code as Dominica.json or download the ready file here. Then, in your Python command line, you would type: kartograph Dominica.json -o Dominica.svg. You will see the SVG file generated in your directory. Use a text editor to open our new Dominica.svg file and do a “Find and Replace All” function: Find the fields that say “data-name=” and replace with “name=”. Also find the fields that say “data-gn-a1-code= “ and replace with “id=”. Then copy all the code within the <g> and </g< tags and paste into the amMap parser to generate the amMap.

For more examples of filtering and manipulating map attributes with the json files, see this page.

Using amMap map parser to prepare SVG for amMap

We have prepared a map parser - tool which parses data generated both by Indie mapper or Adobe illustrator. It also reduced file size a lot. It is always in a "beta" stage, so sorry for some bugs which might appear. Paste everything you copied to the left window, enter map name, variable name latitudes/longitudes of the map borders) and click "parse" button at the bottom. If you did everything right (cleaning <g> from unnecessary elements is crucial) then a amMap ready SVG code and SVG compiled to JSON should appear in the output windows. Copy (by clicking copySVG button) the generated SVG and try to view it in a browser. If not all the map is visible, don't worry – amMap will handle this. Copy JSON code (by clicking copy JSON button) to clipboard, paste it to an empty file and try with amMap.

Finding top, bottom latitudes and right, left longitudes

If you don't have illustrator and Map Publisher, go to this service, click on the map point which is most top/bottom/right/left of your map and copy latitude or longitude. This won't be very accurate, so we recommend adding some points to your map (using amMap) and then do the fine tuning by adjusting these values.

It's a bit easier with illustrator – click on the "map info" icon of the Map publisher toolbar and move the mouse to the extremes of your map. The latitude/longitude will be displayed in a separate window. Use them when parsing your map with amMap parser.