API

Python Geoclient should be used through the public methods of Geoclient.

class geoclient.api.Geoclient(app_id=None, app_key=None, proxies=None)

This object’s methods provide access to the NYC Geoclient REST API.

You must have registered an app with the NYC Developer Portal (http://developer.cityofnewyork.us/api/geoclient-api-beta), and make sure that you check off access to the Geoclient API for the application. Take note of the Application’s ID and key. You will not be able to use the ID and key until DoITT approves you. All requests will return a 403 until you are approved.

Parameters:
  • app_id – Your NYC Geoclient application ID.
  • app_key – Your NYC Geoclient application key.
  • proxies – (optional) A dictionary of proxies.
address(houseNumber, street, borough)

Given a valid address, provides blockface-level, property-level, and political information.

Parameters:
  • houseNumber – The house number to look up.
  • street – The name of the street to look up.
  • borough – The borough to look within. Can be a valid Borough name, numeric value (1-5) or common borough abbreviation.
Returns:

A dict with blockface-level, property-level, and political information.
address_zip(houseNumber, street, zip)

Like the above address function, except it uses “zip code” instead of borough

Parameters:
  • houseNumber – The house number to look up.
  • street – The name of the street to look up
  • zip – The zip code of the address to look up.
Returns:

A dict with blockface-level, property-level, and political information.
bbl(borough, block, lot)

Given a valid borough, block, and lot provides property-level information.

Parameters:
  • borough – The borough to look within. Can be a valid Borough name, numeric value (1-5) or common borough abbreviation.
  • block – The tax block to look up.
  • lot – The tax lot to look up.
Returns:

A dict with property-level information.
bin(bin)

Given a valid building identification number (BIN) provides property-level information.

Parameters:bin – The BIN to look up.
Returns:A dict with property-level information.
blockface(onStreet, crossStreetOne, crossStreetTwo, borough, boroughCrossStreetOne=None, boroughCrossStreetTwo=None, compassDirection=None)

Given a valid borough, “on street” and cross streets provides blockface-level information.

Parameters:
  • onStreet – “On street” (street name of target blockface).
  • crossStreetOne – First cross street of blockface.
  • crossStreetTwo – Second cross street of blockface.
  • borough – The borough to look within. Can be a valid Borough name, numeric value (1-5) or common borough abbreviation.
  • boroughCrossStreetOne – (optional) Borough of first cross street. Defaults to value of borough parameter if not supplied.
  • boroughCrossStreetTwo – (optional) Borough of second cross street. Defaults to value of borough parameter if not supplied.
  • compassDirection – (optional) Used to request information about only one side of the street. Valid values are: N, S, E or W.
Returns:

A dict with blockface-level information.
intersection(crossStreetOne, crossStreetTwo, borough, boroughCrossStreetTwo=None, compassDirection=None)

Given a valid borough and cross streets returns information for the point defined by the two streets.

Parameters:
  • crossStreetOne – First cross street
  • crossStreetTwo – Second cross street
  • borough – Borough of first cross street or of all cross streets if no other borough parameter is supplied. Can be a valid Borough name, numeric value (1-5) or common borough abbreviation.
  • boroughCrossStreetTwo – (optional) Borough of second cross street. If not supplied, assumed to be same as borough parameter. Must be ‘Bronx’, ‘Brooklyn’, ‘Manhattan’, ‘Queens’, or ‘Staten Island’ (case-insensitive).
  • compassDirection – (optional) Optional. for most requests. Required for streets that intersect more than once. Valid values are: N, S, E or W.
Returns:

A dict with intersection-level information.
place(name, borough)

Same as ‘Address’ above using well-known NYC place name for input.

Parameters:
  • name – Place name of well-known NYC location.
  • borough – The borough to look within. Can be a valid Borough name, numeric value (1-5) or common borough abbreviation.
Returns:

A dict with place-level information.
search(input, exactMatchForSingleSuccess=None, exactMatchMaxLevel=None, returnPolicy=None, returnPossiblesWithExact=None, returnRejections=None, returnTokens=None, similarNamesDistance=None)

Beginning with version 1.10, any of the six request types documented in section 1.2 can be accessed using a single unparsed location string. Assuming that the Geoclient parser can guess the location type requested and the given single-field input parameter contains contains enough information to generate a successful Geosupport call, the service will return one or more sets of geocodes corresponding to the type of request that was made.

Parameters:
  • input – Unparsed location input.
  • exactMatchForSingleSuccess – (optional) Whether a search returning only one possible successfully geocoded location is considered an exact match. Defaults to false.
  • exactMatchMaxLevel – (optional) The maximum number of sub-search levels to perform if Geosupport rejects the input but suggests alternative street names, etc. Defaults to 3. Maximum is allowable value is 6.
  • returnPolicy – (optional) Whether to return information on the search policy used to perform the search. Defaults to false.
  • returnPossiblesWithExact – (optional) Whether to also return successfully geocoded possible matches when available in addition to the exact match. Defaults to false.
  • returnRejections – (optional) Whether to return rejected response data from Geosupport. Defaults to false.
  • returnTokens – (optional) Whether to return the parsed input tokens recognized by the parser. Defaults to false.
  • similarNamesDistance – (optional) Maximum allowable Levenshtein distance between user input and a similar name suggestion from Geosupport. Defaults to 8. A higher number will allow more “guesses” to be made about an unrecognized street name.
Returns:

List of geocodes corresponding to the type of request that was made.