tidygeocoder

Tidygeocoder makes getting data from geocoding services easy. A unified high-level interface is provided for a selection of supported geocoding services and results are returned in tibble (dataframe) format.

Features:

  • Forward geocoding (addresses ⮕ coordinates)
  • Reverse geocoding (coordinates ⮕ addresses)
  • Batch geocoding (geocoding multiple addresses or coordinates in a single query) is automatically used if applicable.
  • Duplicate, NA, and blank input data is handled elegantly; only unique inputs are submitted in queries, but the rows in the original data are preserved by default.
  • The maximum rate of querying is automatically set according to the usage policies of the selected geocoding service.

In addition to the usage examples below, see the Getting Started Vignette and blog posts on tidygeocoder.

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:

devtools::install_github("jessecambon/tidygeocoder")

Usage

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

library(dplyr, warn.conflicts = FALSE)
library(tidygeocoder)

# create a dataframe with addresses
some_addresses <- tibble::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 = 'osm', lat = latitude , long = longitude)
#> Passing 3 addresses to the Nominatim single address geocoder
#> Query completed in: 3 seconds

The geocode() function geocodes addresses contained in a dataframe. The Nominatim (“osm”) geocoding service is used here, but other services can be specified with the method argument. Only latitude and longitude are returned from the geocoding service in this example, but full_results = TRUE can be used to return all of the data from the geocoding service. See the geo() function documentation for details.

nameaddrlatitudelongitude
White House1600 Pennsylvania Ave NW, Washington, DC38.89770-77.03655
Transamerica Pyramid600 Montgomery St, San Francisco, CA 9411137.79520-122.40279
Willis Tower233 S Wacker Dr, Chicago, IL 6060641.87535-87.63576

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

library(ggplot2)

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

To perform reverse geocoding (obtaining addresses from geographic coordinates), we can use the reverse_geocode() function. The arguments are similar to the geocode() function, but now we specify the input data columns with the lat and long arguments. The input dataset used here is the results of the geocoding query above.

The single line address is returned in a column named by the address argument and all columns from the geocoding service results are returned because full_results = TRUE. See the reverse_geo() function documentation for more details.

reverse <- lat_longs %>%
  reverse_geocode(lat = latitude, long = longitude, method = 'osm',
                  address = address_found, full_results = TRUE) %>%
  select(-addr, -licence)
#> Passing 3 coordinates to the Nominatim single coordinate geocoder
#> Query completed in: 3 seconds
namelatitudelongitudeaddress_foundplace_idosm_typeosm_idosm_latosm_lonofficehouse_numberroadcitystatepostcodecountrycountry_codeboundingboxtourismneighbourhoodcountysuburb
White House38.89770-77.03655White House, 1600, Pennsylvania Avenue Northwest, Washington, District of Columbia, 20500, United States159983331way23824102238.897699700000004-77.03655315White House1600Pennsylvania Avenue NorthwestWashingtonDistrict of Columbia20500United Statesus38.8974908 , 38.897911 , -77.0368537, -77.0362519NANANANA
Transamerica Pyramid37.79520-122.40279Transamerica Pyramid, 600, Montgomery Street, Chinatown, San Francisco, San Francisco City and County, San Francisco, California, 94111, United States106008002way2422297337.795200550000004-122.40279267840137NA600Montgomery StreetSan FranciscoCalifornia94111United Statesus37.7948854 , 37.7954472 , -122.4031399, -122.4024317Transamerica PyramidChinatownSan FranciscoNA
Willis Tower41.87535-87.63576South Wacker Drive, Printer’s Row, Loop, Chicago, Cook County, Illinois, 60606, United States182238096way33768134241.8753503-87.6357587NANASouth Wacker DriveChicagoIllinois60606United Statesus41.8749718 , 41.8757997 , -87.6361005, -87.6354602NAPrinter’s RowCook CountyLoop

In the Wild

For inspiration, here are a few articles (with code) that leverage tidygeocoder:

Contributing

Contributions to the tidygeocoder package are welcome. File an issue for bug fixes or suggested features. If you would like to contribute code such as adding support for a new geocoding service, reference the developer notes for instructions and documentation.

Citing tidygeocoder

Use the citation() function:

citation('tidygeocoder')
To cite tidygeocoder use:

  Cambon J, Hernangómez D, Belanger C, Possenriede D (2021).
  tidygeocoder: An R package for geocoding. Journal of Open Source
  Software, 6(65), 3544, https://doi.org/10.21105/joss.03544 (R package
  version 1.0.5)

A BibTeX entry for LaTeX users is

  @Article{,
    title = {tidygeocoder: An R package for geocoding},
    author = {Jesse Cambon and Diego Hernangómez and Christopher Belanger and Daniel Possenriede},
    year = {2021},
    journal = {Journal of Open Source Software},
    publisher = {The Open Journal},
    doi = {10.21105/joss.03544},
    url = {https://doi.org/10.21105/joss.03544},
    volume = {6},
    number = {65},
    pages = {3544},
    note = {R package version 1.0.5},
  }

Or refer to the citation page.

Copy Link

Version

Down Chevron

Install

install.packages('tidygeocoder')

Monthly Downloads

5,079

Version

1.0.5

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Last Published

November 2nd, 2021

Functions in tidygeocoder (1.0.5)