A Crash Course in Map-Making

for the National Day of Civic Hacking

June 6, 2015

Follow along at http://maptime.io/pittsburgh/presentations/ndoch2015/

courtesy of @MaptimePGH

What is Maptime?

PLEASE interrupt if you have questions!

For today, think about a map as a combination of four components:


Geography + Base Map

Geography + Base Map + Data

Geography + Base Map + Data + Platform


  1. Geography
  2. Base Map
  3. Data
  4. Platform

This list is:

  • the way you conceptually organize a mapping product
  • your map-making workflow
  • your technology stack

Part 1: Geography


from Greek geographia,
literally "earth description"




maptime: the wild world of geodesy [coordinate systems and projections]

Maps describe Earth.

Maps are a visualization of data in geographic space.

data -> visualization

places on Earth are represented as places on usually flat surfaces, like print-outs or computer screens

doing this requires a:

  1. a system for describing locations
  2. a method for projecting a location on Earth to a location on a flat map

A coordinate system describes locations.

Locations are identified using latitude / longitude (lat/lon) decimal degrees.

maps location: represented with: units:
LATITUDE north-south horizontal lines, different circumferences -90 to +90 decimal degrees
LONGITUDE east-west vertical lines, same circumferences 0 to 180 decimal degrees

Lat/Lon is used to represent location on both the Earth as a globe (a sphere-like 3-D object) and Earth as a map (a planar, 2-D object)

To go from a globe, which looks like this...

...to a map like this...

...we need a map projection

a method in the form of a mathematical equation for stretching and warping the lat/long grid of the globe to fit a planar map

There are lots of ways to project the globe

But there is no way to project the globe without distorting it.

Distortion is typically worst at the edges of the map, affecting relative scale.

To avoid distortion, many projections are purpose-built:
they are specific to an area, or are designed for functionality (e.g., measuring distances from a certain point).

Pennsylvania State Plane (South)

EPSG (European Petroleum Survey Group) code 2272

A few projections provide a decent balance between

on a global scale.

Web Mercator

EPSG code: 3857

East-West distance is constant. North-south distance is distorted close to the poles.

Why you need to know this:

Web Mercator is the projection commonly used for web maps and typical web map-making software/tools/libraries.

Local data in southwestern Pennsylvania is typically stored in PA State Plane (South) / EPSG 2272. It uses feet, not decimal degrees, and must be re-projected to use in a web map.

Part 2: Base map


Your map needs contextual data:
roads, rivers, points of interest, etc.
Fear not. Someone else has already pulled all of this this together for you in
Open Street Map

What is Open Street Map?


It is the "Wikipedia of maps": a publicy editable global base map that you can use in your mapping project.

OSM is is licensed under the Open Database License (ODbL)

If you haven't already, sign up now!


Be A Mapper: How to contribute to OpenStreetMap
Beginners Guide to OSM
maptime: OpenStreetMap 101

some specific tasks
To learn how to add any kind of thing to the map:
wiki.osm.org / wiki / Map_Features
Am I doing it the right way?
wiki.osm.org / wiki / Good_practice

Two ways to view/edit OSM:

web (basic): iD

desktop (advanced): JOSM

What can I do with OSM? Suggestions:

"I'm not interested in contributing to OSM right now, but I need a basemap."

Why you need to know this:

Base maps provide context. Using the right base map can make your data POP.

The benefit of using a base map like OSM is that if you find a discrepancy, it is within your power to fix - and everyone wins.

Part 3: Data


the stuff you are interested
in putting on a map


maptime: introduction to geographic data formats

geocode addressed data en-masse with Google Fusion Tables.

Data that has geographic attributes is Geodata. It represents things that have a location.

This can include defined physical or abstract features like

Data can be either be Raster or Vector.

Raster data stores its geographic information in pixels.

Vector data stores geometry, attributes, and location information as points, lines, or polygons



Vecotr file formats

Vector geodata comes in a lot of formats. The most common are:

A spreadsheet saved as CSV file is a common way to store data. If it contains coordinates or addresses, it can be converted to a geodata.

Here is a CSV table of vacant properties for use today.

Geodata sources for today

Head to the OpenPGH NDOCH GitHub page or the City of Pittsburgh GIS page to download some vector data to work with today.

PASDA hosts Allegheny County data.

Most of these files are shapefile formant. To use on the web, you'll need to reproject them to Web Mercator and then convert them to either GeoJSON or KML.

For converting and reprojecting, you'll need to use desktop Geographic Information Systems (GIS) software like QGIS (free) or ArcGIS (not free, but is the industry standard).

Use QGIS to convert and reproject shapefiles and othe vector data

First, a Very short introduction to QGIS. More detailed QGIS resources include QGIS 101 and a this comprehensive QGIS walk-through.

Then read about Working with Projections in QGIS and saving data to another format in QGIS.

A few other Geodata resources

geojson.io supports creation, editing and conversion of geodata in common formats. It also has an API.

Learn how to Import data to Google Maps (My Maps)

"I have some data with addresses in a table, but I don't have coordinates."

You're in luck. You can take that spreadsheet of things you want to map and turn it into geodata through a process called Geocoding.


Geocoding is the conversion of a human-readable location name (usually addresses) into a numeric location such as a latitude and longitude.

Read an overview of Online Geocoding here.

Learn how to geocode addressed data en-masse with Google Fusion Tables.

Part 4: Platform


use a web map to display and share your data


How Web Maps Work

Anatomy of a Web Map

First: there are some great off-the-shelf tools for building web maps out there.



ArcGIS Online

Google Maps

Consider using one of those if you're a beginner.

If you're comfortable with html, css, and javascript, then you can try your hand at something custom using some of the tools we've highlighted today.

Build your own PieroGIS

See the project here

See a clean version of the map you can hack from (sans sidebar)

A more advanced example made for Pittsburgh Craft Beer Week

Tech We'll Use

Black n' Gold Basemap with MapStack

The base element of this project is the basemap. To keep it simple, we are going to use MapStack. The image filters and effects offer a wide variety of customization.

When you're happy with what you've created, copy the tile url of the live map by right clicking the map and follow your browser dialog to copy the link.

Paste the url text from your MapStack map ino a text editor - we need to make some tweaks to get it ready for use in our map.

The url should look something like:


(Note that depending on how custom you made your map, it may be very long)

We need to tweak this to make it generic and useful for Leaflet. The portions highlighted in red need to change.

Change the variables in url like this:


The bracketed pieces of the url example above -- {s},{z},{x}, and {y} -- are placeholders that allow for the correct tiles to be loaded by Leaflet into our web map.

Where are all the Pierogies?

We've collected some pierogie geodata as GeoJSON.

The .geojson file contains some of the pierogie sources from the region. You can load up this file in GeoJSON.io to add more data in an easy-to-read tabular format, or edit the GeoJSON text directly.

Generate the map with Leaflet

Leaflet is a JavasScript library that does the work of pulling our data and basemap together within HTML.

Using the documentation from the starter tutorial on Leafletjs.com, we are going to start with the most basic components needed for a map:

  1. Add Leaflet starter code
  2. Create the Map element
  3. Add our tile layer URL from MapStack

The result will be a web map that displays your MapStack basemap in the browser, with the ability to pan and zoom around.

Add Leaflet starter code

See the leaflet tutorial.

References to Leaflet javascript and css must be included in the HTML header.

A div tag in the body must refer to the "map" element

css must specify the size of the "map" element

Create the Map element

Within the script tags:

var map = L.map('map').setView([40.4452, -79.9866], 10);

Note that SetView sets the longitude, latitude, and zoom

Add our tile layer URL from MapStack

Within the script tags:

L.tileLayer( 'http://{s}.sm.mapstack.stamen.com/toner/{z}/{x}/{y}.png', {attribution:'credit where credit is due', maxZoom: 18, minZoom: 8,} ).addTo(map);

Note that we use the generic Map Stack url here.

Display the data

Use Leaflet to add our .geojson file.
L.geoJson(pierogie_geojson, {
	pointToLayer: function(feature, latlng) {
		var marker = L.marker(latlng, {icon: pierogie_icon});
		return marker;}


Leaflet displays GeoJSON data, but does not load an externally-stored GeoJSON file. You have a few options to load it, including using JQuery.

But one simple way is to save the geojson object as a var in an external .js file.

var marker = L.marker(latlng, {icon: pierogie_icon});

We can use almost any image file for a marker, and we've got one suitable for pierogies.


Use Leaflet to dynamically generate a pop-up for each pierogie from the point's attributes:

  1. 'bind' a pop-up to the marker
  2. create the text and attribute references (using GeoJSON keys)
  3. optionally style the text using HTML/CSS


Now you've built a web map from scratch using some freely available tools.

See the working example

additional resources

maptimePGH: geo 101

maptime HQ resources page


OpenPGH, Pittsburgh's Code for America Brigade


Maptime HQ and the other Maptime chapters for providing some great source material

Presentation by @GassChristianB

Presentation made with Stack.

Stack is made by and is available
on GitHub under the BSD license.