Mapping in D3

Mon, Nov 07, 2016

To make a map in D3, we must first start with a file that has cartographic information. We can then convert this for use in D3 or other software tools. Some of the most common formats of cartographic data files:

  • ESRI Shapefile — This comes as a .zip file. When you extract it, it will contains multiple files required for calculating the cartographic coordinates, projection, and other metadata. These files are mostly used with a GIS software program, like ArcGIS or it’s free open source alternative, QGIS. This is the most common data format of maps in the GIS world, and generally you will start with this type of file. We will need to covert it to a format more friendly to JavaScript and web software.
  • KML/KMZ or XML — These are formats that use XML (a generic HTML) to store the data. The KML format (and its identical, but compressed version KMZ) is mostly used by Google Earth and Google Maps for storing cartographic data.
  • GeoJSON — This is a JSON format that is a specific standard for storing cartographic features. The GeoJSON website outlines the specification requirements for displaying shapes, lines, and other features.
  • TopoJSON — Similar to the above GeoJSON, but it’s much more compact and efficient. GeoJSON files can often become very large and very process intensive. Designed by Mike Bostock, TopoJSON was aimed for efficiency without losing much quality. It’s designed to be used for any type of shape topology, not just cartographic purposes.


Before we begin, it’s also important to understand how map projections work. Projections is the cartographic science of taking a 3D shape, like a sphere, and representing it as a 2D plane surface.

Map projection

D3 offers several choices for how to display map projections.

Process Overview

The first steps in the process is to convert our cartographic data as a topojson. This is the format most ideal with D3 and will give us the best results. The process will vary depending on what you start with. In most cases, using the tools shown in this page will work with different starting files.

The goal is to convert the file to an EPSG:4326 coordinate system, or verify that it is already set to this. This will use standard latitude and longitude coordinates for all the points in your shape.

Step 1: Starting with a Shapefile

In this example, we will start with a shapefile of election precincts in Contra Costa County, California. Most shapefiles are available for download on the websites of local government agencies. This one was provided by the elections office of Contra Costa County.

Download Election Precincts for Contra Costa County (.zip)

Optional: Viewing the file in

We can view the file in MapShaper. This process is just informational, so we can see what it looks like. Clicking the “i” icon and hovering over the various features of the map helps us understand the type of data associated with each feature.

Viewing a shapre file in mapshaper

Note: Mapshaper has the ability to export files as GeoJSON and TopoJSON. Sometimes this would be OK to perform at this time. But in our example, we won’t use MapShaper to do this right now, because our shapefile is in a different coordinate system other than EPSG:4326. We need to first convert it before exporting as TopoJSON!

Step 2: Checking the Embedded Coordinate System

Shapefiles have a coordinate system embedded in them. You can think of this like an Cartesian X and Y grid, but where the values have different meaning depending on the type of map and where you got your shapefile.

D3 likes EPSG:4326, because it uses a common latitude/longitude coordinate system. Some shapefiles might already be setup with EPSG:4326, so this step can be optional.

To verify the coordinate system of your shape file, upload the .prj file to The .prj file is inside your shapefile .zip. You’ll need to unzip the shapefile temporarily so we can document which coordinate system it’s using. Make sure you keep the files intact and don’t throw away your .zip file just yet, we’ll still need it!

upload your .prj file

Prj results

We can see from the results, our shape file is embedded with EPSG:2227 coordinates. We need to convert it from EPSG:2227 to EPSG:4326!

Step 3: Converting to EPSG:4326

Next, we’ll visit the Ogre to Ogre (ogr2ogr) web client to convert our file to the correct EPSG:4326 coordinate system.

Ogr2ogr is a free command line program that can be installed though a package called GDAL, or through Homebrew.

However, there is an easier way using a free online web client and it doesn’t require installing anything. The web client should work for most applications. The drawback is that there are limited options for conversion, and there is a file size limit. Should either of these be an issue, then you’ll need to install ogr2ogr manually and run the following command from the Terminal program (You’ll need to do this from the folder where your shapefile is located.):

ogr2ogr -f GeoJSON output_file.geojson -t_srs EPSG:4326 your_shapefile.shp

For everyone else using the web client version, just visit: You’ll need to upload the entire shapefile .zip file.

Ogr2Ogr convert

With some browsers like Chrome, it may output the GeoJSON file as text in your window. Simply press Command (Ctrl on PC) + S to save the file with a .json file extension. The name of the file will be used later, so make sure the file name has no spaces and is well understood.

Step 4: Converting to TopoJSON

Next, we’ll upload our GeoJSON file to Mapshaper, and convert it to TopoJSON. Visit the Mapshaper website, and upload your GeoJSON file that you saved from ogr2ogr (not the original .zip shapefile!).

Export to TopoJSON with mapshaper

Advanced Users Note: If you already know the metadata you want to associate with each feature, you can add id-field= to the command line options during export and it will become the “id” property of each feature. In this current Contra Costa County Precinct, for example, we can put id-field=SPCTNM so that the SPCTNM field, which is the precinct name, will be associated with each feature’s id. Without doing this, all metadata will still be preserved.

Step 5: Building a D3 Map

Let’s start with a very basic starter template:

<!DOCTYPE html>
    <meta charset="utf-8">
    <title>D3 Map Example</title>

<script src=""></script>
<script src=""></script>


Notice we’re loading in two D3 libraries; the main library, and one topojson sub-library. In the <script> tag, we’ll setup our basic SVG, and setup a path function which will draw our map.

var svg ="body")
    .attr("width", 960)
    .attr("height", 600);

var projection = d3.geoMercator()
    //center of your map
    .center([-121.979141, 37.940119])
    .scale(60000);//zoom factor

var path = d3.geoPath()

d3.json("ccc_precinct_topo.json", function(error, mapData){
    if (error) throw error;


        .data(topojson.feature(mapData, mapData.objects.ccc_voters_geo).features)
        .attr("d", path)
        .attr("stroke", "#000000")
        .attr("fill", "#ffffff");


The above code assumes that you named your TopoJSON file ccc_precinct_topo.json. Also, we need to figure out what the features object is in your data. If you followed this tutorial, Mapshaper would have made the object property name the same as the file name of your GeoJSON file (the one you exported from ogr2ogr). You can also find this out by looking at your console data, which we exported using console.log(mapData).

Looking at console to find object property for features

Note that in this example our property name is ccc_voters_geo (yours may be different). We need to use this in our data() function:

.data(topojson.feature(mapData, mapData.objects.ccc_voters_geo).features)

Change your mapData.object.[name of property] to match your console.

You should see a map appear:

Map so far

Step 6: Loading Other Data to Color the Map Features

Next, let’s load a .csv (spreadsheet data) so that we can color-code these precincts. We’ll use the latest election results from the 2016 primary elections.

2016 Primary Election Results (Excel)

Let’s make a map to find out who voted for Hillary Clinton vs Donald Trump. Open the election results in Excel, then we’ll create a new Spreadsheet document, and copy over just the columns we want to display on our map.