Published in · 5 min read · Mar 8, 2019
--
At School of Data 2019 last weekend, the Planning Labs team demonstrated several applications and services, including the GeoSearch API. A frequent question that comes up when we demo is “How is that different from GeoClient/GOAT/GeoSupport?” This post will try to clarify the various tooling around NYC’s address data and geocoding software and services. It’s a tangled web we weave… 😇
GeoSupport
Let’s start with GeoSupport, the city’s official geocoding software. What is it? From the GeoSupport User Programming Guide:
The GeoSupport System is an integrated system of software and data files that processes New York City geographic locations. Input locations can be accepted in various forms, including addresses, place names, street intersections, blockfaces, street stretches and property parcels (tax lots).
Ok, so it’s software, how do you use it? First, it’s important to understand that GeoSupport is a low-level software package, it’s not something you double-click or load in a web browser and see a user interface. It’s intended to have custom-made software built on top of it; it takes input data (e.g. borough, house number, street name) into its various functions and spits data back out (e.g. lat/lon, sanitation district, police precinct, election district, etc).
If you install GeoSupport Desktop Edition, it will unzip into a collection of files.
You’re less likely to be a user of GeoSupport directly unless you’re building an application that consumes it. You’re much more likely to interact with one of the many higher-level applications and tools that provide an interface to GeoSupport.
One important note about using GeoSupport and products built on top of it is the requirement to have well-structured discrete inputs (for example, you must specify borough, house number, street name, and zip code as separate fields).
GeoClient API
GeoClient is a web API maintained by NYC DoITT built on top of GeoSupport. It makes GeoSupport’s functionality accessible via the web, where anyone (with an API key) can easily make geocoding requests via HTTP.
Here’s what a GeoClient API call actually looks like, requesting geographic information for City Planning’s HQ at 120 Broadway:
The JSON response contains all the goodies you could ask for, all for the parsing (there’s A LOT more in the response to this call, but I’ve limited what to show for this screenshot)
GeoClient is open source, built with Java, and well-documented, so you can participate in its development. I’ve seen it used directly by web applications, and used for batch geocoding via Python or Node.js scripts.
GeoSearch API
GeoSearch is another web API for geocoding addresses, maintained by NYC Planning Labs. It was built to allow for “autocomplete” geocoding in modern web applications. (This is the “google maps”-style search experience where as you type, an application can show you a list of possible matches, which you can choose from in a dropdown.
GeoSearch is not built around GeoSupport, but uses the same source data (NYC’s Property Address Database, aka PAD). PAD is maintained by the NYC Department of City Planning, and includes every single address in New York City, including alternate street names, non-addressable places, vanity addresses, and more.
GeoSearch is built on the open source geocoder Pelias, and benefits from a great community of developers who are constantly improving the codebase.
We’ve set up a documentation site here, so you can see the API calls happening behind the scenes as you interact with the search box, and learn how to parse the response.
While it’s intended use is for use in interactive web mapping applications, some have used it for batch geocoding of NYC addresses. Here’s a blog post by Mike Treglia describing his use of GeoSearch API from R.
GOAT
Geographic Online Address Translator, or GOAT, is a website managed by DCP that exposes GeoSupport’s functionality via a simple web interface. You can use a simple web UI to fire off individual requests to GeoSupport and see the results. You can also do things like search for intersections, results for BBL (property id aka “borough, block and lot”), or BIN (Building ID Number)
GOAT displays GeoSupport’s response in a table. Look at all that data! It returns so much more than political districts and geographic coordinates; It’s everything you ever wanted to know about an address* (but were afraid to ask)
Other NYC Geo Tools & Packages
- GBAT — A Windows geocoding application that utilizes GeoSupport without needing to know how to code. Users can connect GBAT to Microsoft Excel to do batch geocoding on the desktop
- python-geosupport — Python Bindings for GeoSupport’s binaries
- node-geosupport — Node.js Bindings for GeoSupport’s binaries (by yours truly, PRs welcome!)
- Ruby Bindings for GeoSupport
- geosupport-docker — Dockerfile for accessing GeoSupport as a Docker data volume
- nyc-batch-geocoder — Dockerfile for a crazy fast batch geocoder for NYC addresses
- nyc-geoclient — Python bindings for DoITT’s GeoClient API
- Ruby Bindings for GeoClient
- R Bindings for GeoClient
Happy Geocoding!
Still Confused? Shoot us a message on twitter at @nycplanninglabs, we’re happy to help point you in the right direction.
