geocode function

Geocode

Geocodes (finds latitude and longitude of) a location using the Google Geocoding API. Note: To use Google's Geocoding API, you must first enable the API in the Google Cloud Platform Console. See register_google().

geocode(
  location,
  output = c("latlon", "latlona", "more", "all"),
  source = c("google", "dsk"),
  force = ifelse(source == "dsk", FALSE, TRUE),
  urlonly = FALSE,
  override_limit = FALSE,
  nameType = c("long", "short"),
  ext = "com",
  inject = "",
  ...
)

mutate_geocode(data, location, ...)

geocodeQueryCheck()

geocode_cache()

write_geocode_cache(path, ...)

load_geocode_cache(path, overwrite = FALSE)

clear_geocode_cache(path)

Arguments

• location: a character vector of street addresses or place names (e.g. "1600 pennsylvania avenue, washington dc" or "Baylor University")
• output: amount of output, "latlon", "latlona", "more", or "all"
• source: "google" for Google (note: "dsk" is defunct)
• force: force online query even if cached.
• urlonly: return only the url?
• override_limit: override the current query rate
• nameType: in some cases, Google returns both a long name and a short name. this parameter allows the user to specify which to grab.
• ext: top level domain (e.g. "com", "co.nz"); helpful for non-US users
• inject: character string to add to the url or named character vector of key-value pairs to be injected (e.g. c("a" = "b") get converted to "a=b" and appended to the query)
• ...: In mutate_geocode(), arguments to pass to geocode(). In write_geocode_cache(), arguments to pass to saveRDS().
• data: a data frame or equivalent
• path: path to file
• overwrite: in load_geocode_cache(), should the current cache be wholly replaced with the one on file?

Returns

If output is "latlon", "latlona", or "more", a tibble (classed data frame). If "all", a list.

Details

Note: geocode() uses Google's Geocoding API to geocode addresses. Please take care not to disclose sensitive information. https://www.ncbi.nlm.nih.gov/pmc/articles/PMC8972108/ suggest various alternative options for such data.

Examples

## Not run:
 requires Google API key, see ?register_google

## basic usage
########################################

# geocoding is most commonly used for addresses
geocode("1600 Amphitheatre Parkway, Mountain View, CA")
geocode("1600 Amphitheatre Parkway, Mountain View, CA", urlonly = TRUE)

# google can also geocode colloquial names of places
geocode("the white house")

# geocode can also accept character vectors of places
geocode(c("the white house", "washington dc"))


## types of output
########################################

geocode("waco texas")
geocode("waco texas", output = "latlona")
geocode("waco texas", output = "more")
str(geocode("waco texas", output = "all"))

geocode(c("waco, texas", "houston, texas"))
geocode(c("waco, texas", "houston, texas"), output = "latlona")
geocode(c("waco, texas", "houston, texas"), output = "all") %>% str(4)


## mutate_geocode
########################################

# mutate_geocode is used to add location columns to an existing dataset
# that has location information

df <- data.frame(
  address = c("1600 Pennsylvania Avenue, Washington DC", "", "houston texas"),
  stringsAsFactors = FALSE
)

mutate_geocode(df, address)
df %>% mutate_geocode(address)

## known issues
########################################

# in some cases geocode finds several locations
## End(Not run)

See Also

https://developers.google.com/maps/documentation/geocoding/, https://developers.google.com/maps/documentation/javascript/geocoding/, https://developers.google.com/maps/documentation/geocoding/usage-and-billing/, https://www.ncbi.nlm.nih.gov/pmc/articles/PMC8972108/

Author(s)

David Kahle david@kahle.io