How to draw custom topojson maps for d3.js in 3 steps

Orkhan Huseynli
4 min readApr 29, 2022


From Google’s mymaps to topojson file used in D3.js

It’s been a year since I wanted to design an interactive historical map for fun. When I finally started doing it a week ago, as usual, many problems started to surface. Most importantly, there was no a clear guidance on how to draw a custom map and turn it into topojson. Fortunately I am scratching one right now in this article. So if you are beginning your journey in Data Visualisation (or DataViz) or just enjoying drawing and exploring maps, then continue reading this article.

The problem

Historical maps usually don’t fit into current administrative or border divisions, therefore if someone wants to create an interactive map of, for example, medieval times, then he/she must draw it from scratch.

The easy way for an ordinary person like me would be to draw them as polygons in google maps. But then one must figure out how to export those polygons as topojson file (if you don’t know what is topojson and how it is used for map vizuals then read the following introductory article “Let’s make a Map”) by Mike Bostock. ), so it can be used in d3.js, a library that is widely used for interactive map visuals. In addition, when one draws a map using polygons, he/she will most likely have conflicts with polygon borders (like overlaps).

In the end, I was looking for free tools to draw & convert my polygons into topojson without any substantial learning cost. After a day of research, I come up with the following steps to reach the goal.

NOTE: I am not a cartographer, neither I am a specialist in DataViz. I’ve been playing with d3 library from time to time & recently has done a ton of work with it due to my recent projects. Therefore, instructions I give might be not the best ones. On the other hand, you can provide better approaches in the comments section. I will be happy to learn from you.


Step 1: Draw your map using polygons in

Try to do your best when drawing the borders. If something overlaps, it is fine! We will fix it in the Step 3 thanks to tools available online for free (big thanks to their authors!).

Step 2: Export the layer in KML format

  • Select the layer which you want to export
  • Click on layer settings -> Export data -> KML/KMZ -> KML
Figure 1: Exporting map data from Google’s mymaps

Step 3: use mapshaper to correct borders & convert to TopoJSON

mapshaper is an online tool where you can upload your KML file, edit it & export in a number of formats, including TopoJSON , which is a must for convenient d3 map visualisation.

Though the platform provides many other perks too, I needed only 2 things from it:

  1. Correct overlaps with borders: Open the console (i.e. click top-right button with the same name)
  2. Go to console on the left pane & type
mapshaper -clean

This command will fix all geometry issues, such as polygon overlaps and gaps.

3. Export the file as topojson: Click export on top-right of the screen & select topojson format.

Figure 2: Fixing geometry issues in mapshaper
Figure 3: Exporting map data as TopoJSON file

As your TopoJSON file is ready, you can use it in d3.js for map visualisations in your code. To see details of the implementation, open the original observablehq project & look at the code (it is a simple example designed for this medium post).

I hope this guide helps all those who have just started their journey in Data Visualisation or just want to draw & create historical (or mythical) maps for fun like I do.

If you are interested in Data Visualisation, then you may want to read my article on how Game Development & DataViz could be a good combination for story telling.



Orkhan Huseynli

Software Engineer, History fan