In austensen/geoclient: Tools to work with NYC's _Geoclient_ REST API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
options(tibble.print_min = 5, tibble.print_max = 5, tibble.max_extra_cols = 5)


library(geoclient)

geoclient

Tools to work with NYC's Geoclient REST API.

This packages uses NYC's Geoclient API but is neither endorsed nor supported by the the City of New York.

For information about the Geoclient API visit NYC's Developers Portal.

Installation

Install from Github with remotes:

# install.packages("remotes")
remotes::install_github("austensen/geoclient")

Set up Geoclient API keys

You can acquire your Geoclient app ID and Key by first registering with the NYC's Developer Portal at, then create a new project, selecting "Geoclient v1" from available APIs.

To avoid having to provide the ID and Key with each function call you can use geoclient_api_keys() to add your Geoclient app ID and Key to your .Renviron file so they can be called securely without being stored in your code.

library(geoclient)

geoclient_api_keys("xxx", "xxx")

Basic Usage

There are 6 main location types that can be set with Geoclient: Address, BBL (Borough-Block-Lot), BIN (Building Identification Number), Blockface, Intersection, and Place ("well-known NYC place name"). All of these functions return the results of the Geoclient API call as a dataframe, with additional columns for the arguments provided to the function.

geo_address(
  house_number = "139", 
  street = "MacDougal St", 
  borough = "MN",
  zip = "10012"
)

You can also pull out just a single column if that is all you need.

df <- tibble::tribble(
  ~num,  ~st,                ~boro,         ~zip,
  "139", "MacDougal St",     "manhattan",   "11231",
  "295", "Lafayette street", NA,            "10012-2722",
  "40",  "WASHINGTON SQ S",  "MN",          NA
)

dplyr::mutate(df, bbl = geo_address(num, st, boro, zip)[["bbl"]])

For each of these location types there are two functions in this package that allow the arguments to be supplied either as individual vector, or with a dataframe and bare column names.

geo_address_data(df, num, st, boro, zip)

The return dataframe will always be the same length and in the same order, so you can easily add all the return columns to your existing dataframe.

dplyr::bind_cols(df, geo_address_data(df, num, st, boro, zip))

In addition to the 6 location types, Geoclient also provides a single-field search option, which will guess the location type. This can be particularly helpful when you have address data that is not easily separated for use with geo_address().

df <- tibble::tribble(
  ~address,
  "139 MacDougal St manhattan, 11231",
  "295 Lafayette street, 10012-2722",
  "40 WASHINGTON SQ S MN"
)

geo_search_data(df, address)