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!