Startup hacks and engineering miracles from your exhausted friends at Faraday

How to reverse geocode in bulk

Bill Morris on

This post is part of our practical cartography series.

We just rebuilt our Argo reverse-geocoding module as a proper command-line tool. Got a pile of coordinates in a table like this?

Pipe them through argo to get the context of an address assigned to each of them:

npm install argo-geo -g  
argo -i myfile.csv -a "blahblahmapzenauthtoken"  

Using Mapzen search, that'll churn through your table at 6 queries per second, appending results to each coordinate pair until it's done:

We built this to process millions of rooftop coordinates that a vendor provided to us without addresses, but you could just as easily use it for any position-only datasets:

  • Bird sightings from the field
  • Cars auto-extracted from imagery
  • GPS tracks from that pub crawl where you forgot the names of the bars
  • Mobile-collected reports of voter intimidation

We named it "Argo" to follow the Greek mythology pattern of Mapzen's geocoding engine "Pelias". Google and Mapbox each offer reverse-geocoding services as well, but those are just that: services. They include TOUs that restrict caching of the results, and man, did we want to cache these. The good folks at Mapzen built their search architecture on some truly amazing open datasets, and they match the spirit of the source by allowing storage and repurposing.

Thanks, Mapzen!

How to crunch lots of geodata in parallel

Bill Morris on

This post is part of our data science and practical cartography series.

GNU parallel + ogr2ogr = happy data scientists

These power tools in combination make it very easy to process lots of geodata at once, in as many parallel operations as your local machine or server can support.

Reprojecting in bulk

Here's an example, assuming you have a folder full of shapefiles you want to reproject into Geographic coordinates. Make a directory for the output, then pipe every shapefile through ogr2ogr in parallel:

mkdir wgs84  
ls *.shp | parallel ogr2ogr -t_srs 'EPSG:4326' wgs84/{} {}  

Running a sequence of commands on many files

In order to build whole data workflows, you can wrap your sequence of commands in a bash function. Here's an example, where we:

  1. Download each state landmarks file from the census FTP
  2. Extract each file
  3. Create a new file for each consisting of only airport landmarks, projected to WGS84
# grab this handy list of all state FIPS codes
wget -c

# define the function
get_airports() {  
  # grab the data from the census server
  wget -c$
  unzip tl_2016_$
  # extract just airports (code K2451) and reproject to WGS84
  ogr2ogr -t_srs "EPSG:4326" -where "MTFCC = 'K2451'" tl_2016_$1_airports.shp tl_2016_$1_pointlm.shp
  echo "done with state $1"
export -f get_airports

# kick off the parallel processing!
cat state_fips_codes.txt | parallel get_airports {}

This crunches through 52 states and territories in 21.8 seconds on a small ec2 server, limited only by network speed.


Install the tools

  • GNU parallel
    • OSX: brew install parallel
    • Ubuntu: apt-get install parallel
  • ogr2ogr
    • OSX: brew install gdal --HEAD
    • Ubuntu: sudo apt-get install gdal-bin

Bonus toolkit: From Derek Watkins, here are a few dozen examples of the awesome geoprocessing you can you with GDAL/OGR.

Happy mapping!

How to preview PostGIS maps on your command line

Bill Morris on

This is part of our practical cartography and PostgreSQL series. Put a map on it!

Sometimes it's a pain to open up QGIS and load a PostGIS-enabled DB. Sometimes I don't feel like writing a custom tileserver and hooking it up to Leaflet or Mapbox GL just so I can see if my map looks right.

Sometimes I use the psql command line and a nifty tool by Morgan Herlocker called "geotype" to view my map data.

npm install -g geotype  

. . . which enables fast and simple maps like this:


Yep. That's New York, alright.


. . . and that sure looks like the population distribution of the District of Columbia.

These maps are nothing to show to customers, but they make QA/QC a lot easier. Here's the syntax, piping psql output directly into geotype:

psql $DB_URL -t -c "SELECT ST_AsGeoJSON(ST_Collect(the_geom)) FROM mytable" | geotype  

(The -t and ST_Collect() coerce the output into the type of data that geotype can read)

Happy mapping!

Getting bite-sized chunks of OpenStreetmap

Bill Morris on

At Faraday, we dig OSM.

OpenStreetmap (OSM) is the foundation of our basemap and a model of the power of open data. It guides customers on our platform to their ideal audiences . . .


. . . and it serves as building blocks for geospatial analysis, both the kind we already do and the kind we want to do more of.

The problem is that it's big. The entire OSM database is portable, but at 50GB it's not very friendly. Sometimes we just want the driveway network of one county, or the building footprints in a zip code. Whole companies have sprung up around this workflow, but we have a few tried-and-true-and-cheap tools that we rely on:

  • Mapzen-hosted metro extracts - If your desired zone is on the list of regularly-updated cities, just grab the shapefiles and go!
  • OSM vector tiles - Use these with toolsets like tilereduce for distributed geoprocessing at tile scale.
  • Overpass API - This tuneable endpoint works great for specific queries in minutely-defined regions (e.g. find all the one-way streets in Park Slope), but it can be a bit opaque. Use the query-overpass node module to spit out GeoJSON with minimal fuss.

Happy mapping!

Faraday Places: our simple gazetteer

Bill Morris on

At the core of the Faraday platform is the concept of an audience. For most of our customers, the first step toward focusing in on the people they want to reach is choosing a geography. That's where Faraday Places comes in.

Faraday search

We draw our collection of geographies largely from data offered by the US Census Bureau. In addition to nationwide coverage, these have the benefit of being the "official" administrative boundaries in most cases. States, counties, metro areas, cities, villages - we pull them all into our system with one long bash script, and then make them searchable for our customers.

place types

We retained the census-assigned GeoID of each place, which makes it easy for us to grab data via census APIs, check out demographic details via 3rd party apps, and even prepare ourselves for the updates that are due ahead of the 2020 census.

Our collection of places contains 78,000 unique geographies - it may sound like a lot, but we've weeded out tens of thousands of records we thought we could do without. Gazetteers are hard; we've very deliberately kept it simple.

Here's a shortcut to the data, or just head over and start searching on the platform!