Geoclient Released Under Apache 2.0

Geoclient Released Under Apache 2.0

On the continuum of greater collaboration, there is open data, open API’s (application programming interface) and open source. Today’s release of Geoclient under an Apache 2.0 license (press release) on GitHub (here) further strengthens NYC’s overall commitment to openness and collaboration.

NYC government provided data for free download prior to the landmark NYC open data legislation in 2012. One of the earliest examples, if not the first, was the Department of City Planning’s (DCP) release of the LION street centerline file in November 2001. However, the open data legislation greatly opened the data spigot with many more data sets being released and included a plan to release all applicable data sets by 2018.

NYC’s open data portal was followed by a developer portal that was populated with data feeds and API’s. Geoclient was first released to the public on the developer portal as a freely available API. All that was required for access was the provision of an API key, which has since been automated.

We are excited about the release of Geoclient and hope it provides additional benefits to its end users. Although not the first release of source code on GitHub – there are already numerous NYC projects including my team’s Pre-K finder – Geoclient represents arguably the most significant when measured by volume of transactions and number of client application integrations. Geoclient is used by startups, universities, research institutes, other governments and the local developer community. Geoclient has seen almost 300% growth over the last year alone.

We look forward to greater collaboration and hearing from the community of users. However, like any open source projects we cannot guarantee a response to every issue and question but we will do our best. Hopefully the user community gets involved to answer some of the questions. Please bear in mind that Geoclient is a moving target under active development because it is used internally by City systems and staff whose needs are constantly evolving. Yes, we do eat our own dogfood.

Finally, none of this would have been possible without the dedicated staff at DCP who have maintained and extended Geosupport for over 30 years. And of course I’d be remiss without recognizing the hard work of Matt Lipper at DoITT. Kudos to all!

Source code – https://github.com/CityOfNewYork/geoclient

Developer Portal – https://developer.cityofnewyork.us/api/geoclient-api

 

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!