tidygeocoder

Introduction

Tidygeocoder makes getting data from geocoder services easy. Both forward geocoding (providing addresses to obtain latitude and longitude) and reverse geocoding (providing latitude and longitude to obtain addresses) are supported. All results are returned in tibble format and the supported geocoder services are listed below.

Batch geocoding (geocoding multiple addresses or coordinates per query) is used by default if supported by the geocoder service when multiple inputs (addresses or coordinates) are provided. Duplicate, missing/NA, and blank input data is handled elegantly - only unique inputs are passed to geocoder services, but the rows in the original data are preserved by default.

In addition to the usage examples below you can refer to the following references:

• Mapping European soccer club stadiums
• Mapping Washington, DC landmarks
• Getting Started Vignette for more detailed and comprehensive usage examples. The last section of the vignette contains a helpful reference on geocoder service parameters.

Installation

To install the stable version from CRAN (the official R package servers):

install.packages('tidygeocoder')

Alternatively, you can install the latest development version from GitHub:

if(!require(devtools)) install.packages("devtools")
devtools::install_github("jessecambon/tidygeocoder")

Geocoder Services

The supported geocoder services are shown in the table below with their geographic limitations, if they support batch geocoding (geocoding multiple addresses or coordinates in a single query), if an API key is required, and the usage rate limitations. Refer to the website for each geocoder service for the most up-to-date details on costs, capabilities, and usage limitations.

Notes:

• The US Census service supports street-level addresses only (ie. “11 Wall St New York, NY” is OK but “New York, NY” is not).
• The US Census and Geocodio services both support a maximum of 10,000 addresses per batch query.
• The US Census and OSM services are free while Geocodio, Location IQ, OpenCage, Mapbox, HERE, TomTom and MapQuest are commercial services that offer both free and paid usage tiers. The Google service bills per query.
• The Census geocoder does not support reverse geocoding.
• The Mapbox service is capable of performing batch geocoding when using the permanent endpoint, but this capability is not currently implemented in tidygeocoder. If you’d like to add this capability to the package see issue #73.

Usage

In this example we will geocode a few addresses using the geocode() function and plot them on a map with ggplot.

library(dplyr)
library(tibble)
library(tidygeocoder)

# create a dataframe with addresses
some_addresses <- tribble(
~name,                  ~addr,
"White House",          "1600 Pennsylvania Ave NW, Washington, DC",
"Transamerica Pyramid", "600 Montgomery St, San Francisco, CA 94111",     
"Willis Tower",         "233 S Wacker Dr, Chicago, IL 60606"                                  
)

# geocode the addresses
lat_longs <- some_addresses %>%
  geocode(addr, method = 'census', lat = latitude , long = longitude)

The geocode() function attaches latitude and longitude columns to our input dataset of addresses. The US Census geocoder is used here, but other services can be specified with the method argument. See the geo() function documentation for details.

Now that we have the longitude and latitude coordinates, we can use ggplot to plot our addresses on a map.

library(ggplot2)
library(maps)
library(ggrepel)

ggplot(lat_longs, aes(longitude, latitude), color = "grey99") +
  borders("state") + geom_point() + 
  geom_label_repel(aes(label = name)) + 
  theme_void()

To return the full results from a geocoder service (not just latitude and longitude) you can use full_results = TRUE. Additionally, for the Census geocoder you can use return_type = 'geographies' to return geography columns (state, county, Census tract, and Census block).

full <- some_addresses %>%
  geocode(addr, method = 'census', full_results = TRUE, 
          return_type = 'geographies')

To perform reverse geocoding (obtaining addresses from latitude and longitude coordinates), we can use the reverse_geocode() function. The arguments are similar to the geocode() function, but we now are specifying the latitude and longitude columns in our dataset with the lat and long arguments. The single line address is returned in a column named by the address argument. See the reverse_geo() function documentation for more details on reverse geocoding.

coordinates <- tibble(latitude = c(38.895865, 43.6534817, 35.0844),
                longitude = c(-77.0307713, -79.3839347, -106.6504))

rev1 <- coordinates %>%
  reverse_geocode(lat = latitude, long = longitude, method = 'osm',
                  address = address_found, full_results = TRUE)

For further documentation, refer to the Getting Started Vignette and the function documentation.

Contributing

Contributions to the tidygeocoder package are welcome. File an issue for bug fixes or suggested features. If you would like to add support for a new geocoder service, reference this post for instructions.