Geoclient: An Open NYC Geocoding API

Overview
Geoclient is a geocoding API that recognizes and geocodes addresses, intersections and blockfaces (on street and two cross streets) located in New York City. The Geoclient service provides a RESTful web service interface to the Department of City Planning’s (DCP) Geosupport system. Geoclient provides “pass-through” style access to native Geosupport functions. It does not change or modify Geosupport functionality in any way. However, Geoclient does add some very useful features (some of which are considered standard by today’s developers). While Geoclient is intended for programmatic use, DCP hosts GOAT, a website that provides direct access to Geosupport native functions. Geoclient developers often use GOAT to compare results or test data interactively.

Access
There are two primary Geoclient installations. One is for use internally by official City agencies and the second intended for the public developer community. However, the data and logic behind all instances of Geoclient are exactly the same. By sharing the same code base and deployment scripts, it is easier to maintain and support. For the public, access to Geoclient is through the NYC Developer Portal. For City agencies, contact us directly.

Functionality
Geoclient provides two notable enhancements which can be used to simplify and optimize access to Geosupport. The first is single-field search functionality which parses a single input string into the discrete location elements that are required by the different Geosupport functions. For example, an input of “59 Maiden Lane, Manhattan” is parsed into its house number (59), street name (Maiden Lane) and Borough (Manhattan) for submission to Geosupport. Note that parsing is not case-sensitive, punctuation is ignored and most standard street pre- and post-modifiers, types and directionals are recognized.

A fully qualified (i.e., expanded) address is often referred to as a ‘normalized’ address. An example is ‘314 w 100 st mn’ which is the equivalent of the normalized ‘314 West 100 Street, Manhattan’. Normalization is native to Geosupport. If your data is already parsed into discrete address elements, using the /geoclient/v1/address endpoint directly is less ambiguous and slightly more efficient.

Building on it’s ability to parse single-field search locations, Geoclient can also be used to “guess” the intended target of an incomplete or ambiguous input. One example is the submission of an address without a borough. As long as Geoclient can recognize the search text as an address (house number and street), the /geoclient/v1/search endpoint will try that address in all five boroughs. By default, if the address exists in one or more boroughs, all locations will be fully geocoded and returned as possible matches. This behavior can be customized, for example, by calling the service with the optional ‘exactMatchForSingleSuccess’ parameter set to true. In that case, if the address exists in only one borough it will be geocoded and returned as an exact match.

Using the previous example, entering “59 maiden ln” without the borough will result in the same response as entering “59 Maiden Lane, Manhattan”. The figure below shows the response for “59 Maiden Ln” using the Pre-K Finder application.

geoclient_imputed

In cases where the same address exists in multiple boroughs, Geoclient will return a candidate list of possible addresses. In each case, the candidate address is validated to ensure a successful response. See example below.

geoclient_candidate

 

Developers can customize this and several other search features as documented by the Geoclient API.

Hopefully this will clear up some of the misconceptions associated with Geoclient and contribute to the knowledge base. And please check back in the coming weeks for a more detailed Geoclient post. In addition, expect some enhancements over the coming months. Nice work Matt!

5 thoughts on “Geoclient: An Open NYC Geocoding API

  1. Hi Colin,

    Your work is important to me. I am grateful for the fabulous interactive mapping and data capabilities that you enable. I think the NYC GIS maps are the best in the world!

    I am involved in an unusual history project that is attempting to look up the current day Manhattan tax lot address and lat/long for 10,000 events that have occurred in Manhattan’s history. Through painful research, we have realized how complicated the address situation is–different street names over time, different house numbers, multiple street addresses or an address range for a single tax lot, retail frontage addresses, addresses for what is now a blank wall, etc etc etc. I am looking for a way to automate the process as much as possible and tap into your wonderful GIS data. For example, I would love to know how to input an address in a search request, and get returned ALL the alias addresses that fit with that place and its tax lot–or have over time.

    This is a long message, sorry. May I call you when its convenient to pick your brain for 5 minutes?

    Please reply, even to say you’re too busy or to refer me somewhere.

    Thank You!!!

    ksacharin@gmail.com
    6469644679

    ken sacharin

    • Ken,

      Thanks for the positive feedback. We certainly appreciate it.

      Unfortunately, there isn’t much historical address data and what exists is included in LION. If you look in the LION metadata (http://www.nyc.gov/html/dcp/pdf/bytes/lion_metadata.pdf?v=14d) there is a field ‘SpecAddr’ that contains some historical data but certainly not all. This data would be returned by Geosupport. There is really no other source of historical address/parcel data in NYC government that I am aware of.

      Colin

  2. Hi Colin,
    Love the single field search function! Mea culpa – I plead guilty of having the misconception that GeoClient needs structured input 🙂

    It’s just that in the 3Scale Developer sandbox (https://dev-mgmt.cityofnewyork.us/docs/geoclient/v1), the SFS endpoint is not included, and TLDRed the documentation… (RTFM!)

    Anyways, great stuff! We’re actually releasing a little tool to next week that makes use of SFS. Stay tuned 🙂

    Joel

    P.S.
    For Ken’s query, would requesting older versions of GeoSupport Desktop help? Also, you may want to update the 3Scale developer sandbox to expose SFS.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s