Skip to contents

Read National Address Database (NAD) tables into R

Source: R/nad.R
nad.Rd

The U.S. Department of Transportation partners with address programs from state, local, and tribal governments to compile their authoritative data into a database. Find more information in the source data portal: https://data.transportation.gov/d/yw36-suxr

nad_read() reads data from the NAD geodatabase by county, using source data already downloaded with nad_download() or downloading it when refresh_source = "yes", and readies it for R. Counties can be identified either by county name plus state, or by a 5-digit county FIPS identifier. County names and state abbreviations are resolved internally and still determine the cache path and source query. The NAD geodatabase has a very large size on disk (~10 GB).

Data binaries are the cached outputs of nad_read() for each County/State and are created on first run with nad(). Download data binaries to the tools::R_user_dir() data directory, or point R to these files on disk, to read NAD tables without downloading the nationwide NAD geodatabase. (Files are organized by major package version, NAD version, state, and named by county; e.g., see list.files(tools::R_user_dir("addr", "data"), recursive = TRUE))

Usage

nad(
  county,
  state = NULL,
  version = 22L,
  refresh_binary = c("yes", "no", "force"),
  refresh_source = c("no", "yes", "force")
)

nad_read(
  county,
  state = NULL,
  version = 22L,
  refresh_source = c("no", "yes", "force")
)

nad_download(version = 22L, refresh_source = c("yes", "no", "force"))

Arguments

county

character, length one; county name or 5-digit county FIPS identifier

state

character, length one; name or abbreviation of state. Required when county is a county name; ignored when county is a 5-digit county FIPS identifier

version

integer, length one; NAD revision to use. Defaults to 22L, revision 22 of the National Address Database.

refresh_binary

character, length one; choose how to refresh NAD data binaries cached on disk if not already present; "yes" will create data binary if not already present, "no" will error if data binary is not already present, "force" will create the data binary and overwrite any existing data binary

refresh_source

character, length one; choose how to refresh NAD source geodatabase on disk if not already present; "yes" will download the geodatabase if not already present, "no" will error if the file does not already exist, "force" will download and overwrite any existing geodatabase

Details

NAD source geodatabases are downloaded from the transportation.gov data portal: https://data.transportation.gov/d/yw36-suxr Downloads use the R curl package and resume from any interrupted partial download left in the addr user data directory. If the download cannot complete, nad_download() will also work with a NAD ZIP file that was downloaded another way and placed where tools::R_user_dir("addr", "data") can find it. Before downloading, review the source metadata and disclaimer in the data portal.

Investigate individual address points in the online viewer: https://usdot.maps.arcgis.com/apps/instant/portfolio/index.html?appid=59f7e4fb71994d13b61f424e21a6cffe

The NAD does not distinguish between empty and missing address components. When reading into R, all missing address components are replaced with an empty string ("") except for address number (digits), street name, and ZIP code. Addresses with malformed ZIP codes are removed.

Examples

# explicitly download source data, then cache county output on first read
if (FALSE) { # \dontrun{
  nad_download(version = 22L)
  nad("Butler", "OH")
  nad("39017")
} # }

# small packaged fixture derived from Hamilton County, OH
nad_example_data()
#> # A tibble: 5,000 × 7
#>    nad_addr            subaddress uuid  date_update s2    address_type parcel_id
#>    <addr>              <chr>      <chr> <date>      <s2_> <chr>        <chr>    
#>  1 3359 QUEEN CITY Av… NA         {E3A… 2025-03-30  -6.7… Unknown      NA       
#>  2 1040 KREIS Ln CINC… NA         {D05… 2025-03-30  -6.7… Unknown      NA       
#>  3 9960 DALY Rd CINCI… NA         {109… 2025-03-30  -6.1… Unknown      NA       
#>  4 413 VOLKERT Pl CIN… NA         {1BB… 2025-03-30  -6.7… Unknown      NA       
#>  5 8519 LINDERWOOD Ln… NA         {F78… 2025-03-30  -6.6… Unknown      NA       
#>  6 6361 BEECHMONT Ave… NA         {6D4… 2025-03-30  -6.6… Unknown      NA       
#>  7 10466 ADVENTURE Ln… NA         {1D1… 2025-03-30  -6.1… Unknown      NA       
#>  8 3156 LOOKOUT Cir C… NA         {AE8… 2025-03-30  -6.6… Unknown      NA       
#>  9 310 WYOMING Ave CI… NA         {331… 2025-03-30  -6.1… Unknown      NA       
#> 10 118 SPRINGFIELD Pi… NA         {F3E… 2025-03-30  -6.1… Unknown      NA       
#> # ℹ 4,990 more rows