Geocodes addresses given as character values. The geocode
function utilizes this function on addresses contained in dataframes.
See example usage in vignette("tidygeocoder").
Note that not all geocoding services support certain address component parameters. For example, the Census geocoder only covers the United States and does not have a "country" parameter.
Refer to api_parameter_reference, min_time_reference, and batch_limit_reference for more details on geocoding service parameters and usage.
This function uses the get_api_query, query_api, and extract_results functions to create, execute, and parse geocoder API queries.
geo(
address = NULL,
street = NULL,
city = NULL,
county = NULL,
state = NULL,
postalcode = NULL,
country = NULL,
method = "osm",
lat = "lat",
long = "long",
limit = 1,
full_results = FALSE,
mode = "",
unique_only = FALSE,
return_addresses = TRUE,
min_time = NULL,
progress_bar = show_progress_bar(),
quiet = getOption("tidygeocoder.quiet", FALSE),
api_url = NULL,
timeout = 20,
flatten = TRUE,
batch_limit = NULL,
verbose = getOption("tidygeocoder.verbose", FALSE),
no_query = FALSE,
custom_query = list(),
api_options = list()
)single line address (ie. '1600 Pennsylvania Ave NW, Washington, DC').
Do not combine with the address component arguments below
(street, city, county, state, postalcode, country).
street address (ie. '1600 Pennsylvania Ave NW')
city (ie. 'Tokyo')
county (ie. 'Jefferson')
state (ie. 'Kentucky')
postalcode (ie. zip code if in the United States)
country (ie. 'Japan')
the geocoding service to be used. API keys are loaded from environmental variables. Run usethis::edit_r_environ() to open your .Renviron file and add an API key as an environmental variable. For example, add the line GEOCODIO_API_KEY="YourAPIKeyHere"
"osm": Nominatim.
"census": US Census. Geographic coverage is limited to the United States. Batch geocoding is supported.
"arcgis": ArcGIS.
"geocodio": Geocodio. Geographic coverage is limited to the United States and Canada. Batch geocoding is supported. Store an API key in the environmental variable "GEOCODIO_API_KEY".
"iq": Location IQ. Store an API key in the environmental variable "LOCATIONIQ_API_KEY".
"google": Google. Store an API key in the environmental variable "GOOGLEGEOCODE_API_KEY".
"opencage": OpenCage. Store an API key in the environmental variable "OPENCAGE_KEY".
"mapbox": Mapbox. Store an API key in the environmental variable "MAPBOX_API_KEY".
"here": HERE. Batch geocoding is supported, but must be explicitly called with mode = "batch". Store an API key in the environmental variable "HERE_API_KEY".
"tomtom": TomTom. Batch geocoding is supported. Store an API key in the environmental variable "TOMTOM_API_KEY".
"mapquest": MapQuest. Batch geocoding is supported. Store an API key in the environmental variable "MAPQUEST_API_KEY".
"bing": Bing. Batch geocoding is supported, but must be explicitly called with mode = "batch". Store an API key in the environmental variable "BINGMAPS_API_KEY".
"geoapify": Geoapify. Store an API key in the environmental variable "GEOAPIFY_KEY".
latitude column name. Can be quoted or unquoted (ie. lat or "lat").
longitude column name. Can be quoted or unquoted (ie. long or "long").
maximum number of results to return per input address. For many geocoding services the maximum value of the limit parameter is 100. Pass limit = NULL to use the default limit value of the selected geocoding service. For batch geocoding, limit must be set to 1 (default) if return_addresses = TRUE. Refer to api_parameter_reference for more details.
returns all available data from the geocoding service if TRUE. If FALSE (default) then only latitude and longitude columns are returned from the geocoding service.
set to 'batch' to force batch geocoding or 'single' to force single addressgeocoding (one address per query). If not specified then batch geocoding will be used if available (given method selected) when multiple addresses are provided; otherwise single address geocoding will be used. For the "here" and "bing" methods the batch mode should be explicitly specified with mode = 'batch'.
only return results for unique inputs if TRUE
return input addresses with results if TRUE. Note that
most services return the input addresses with full_results = TRUE and setting
return_addresses to FALSE does not prevent this.
minimum amount of time for a query to take (in seconds). If NULL then min_time will be set to the default value specified in min_time_reference.
if TRUE then a progress bar will be displayed
for single input geocoding (1 input per query). By default the progress bar
will not be shown for code executed when knitting R Markdown files or code within
an RStudio notebook chunk. Can be set permanently with options(tidygeocoder.progress_bar = FALSE).
if TRUE then console messages that are displayed by default
regarding queries will be suppressed. FALSE is default.
Can be set permanently with options(tidygeocoder.quiet = TRUE).
custom API URL. If specified, the default API URL will be overridden. This parameter can be used to specify a local Nominatim server, for instance.
query timeout (in minutes)
if TRUE (default) then any nested dataframes in results are flattened if possible. Note that in some cases results are flattened regardless such as for Geocodio batch geocoding.
limit to the number of addresses in a batch geocoding query.Defaults to the value in batch_limit_reference if not specified.
if TRUE then detailed logs are output to the console. FALSE is default. Can be set
permanently with options(tidygeocoder.verbose = TRUE)
if TRUE then no queries are sent to the geocoding service and verbose is set to TRUE. Used for testing.
API-specific parameters to be used, passed as a named list
(ex. list(extratags = 1).
a named list of parameters specific to individual services.
(ex. list(geocodio_v = 1.6, geocodio_hipaa = TRUE)). Each parameter begins
with the name of the method (service) it applies to. The possible parameters
are shown below with their default values.
census_return_type (default: locations): set to "geographies" to return
additional geography columns. Make sure to use full_results = TRUE if using
the "geographies" setting.
iq_region (default: "us"): set to "eu" to use the European Union API endpoint
geocodio_v (default: 1.7): the version number of the Geocodio API to be used
geocodio_hipaa (default: FALSE): set to TRUE to use the HIPAA compliant
Geocodio API endpoint
mapbox_permanent (default: FALSE): set to TRUE to use the mapbox.places-permanent
endpoint. Note that this option should be used only if you have applied for a permanent
account. Unsuccessful requests made by an account that does not have access to the
endpoint may be billable.
mapquest_open (default: FALSE): set to TRUE to use the Open Geocoding endpoint which
relies solely on OpenStreetMap data
here_request_id: this parameter would return a previous HERE batch job,
identified by its RequestID. The RequestID of a batch job is displayed
when verbose is TRUE. Note that this option would ignore the
current address parameter on the request, so the return_addresses or return_coords
parameters need to be FALSE.
tibble (dataframe)
# \donttest{
options(tidygeocoder.progress_bar = FALSE)
geo(
street = "600 Peachtree Street NE", city = "Atlanta",
state = "Georgia", method = "census"
)
#> Passing 1 address to the US Census single address geocoder
#> Query completed in: 5.9 seconds
#> # A tibble: 1 × 5
#> street city state lat long
#> <chr> <chr> <chr> <dbl> <dbl>
#> 1 600 Peachtree Street NE Atlanta Georgia 33.8 -84.4
geo(
address = c("Tokyo, Japan", "Lima, Peru", "Nairobi, Kenya"),
method = "osm"
)
#> Passing 3 addresses to the Nominatim single address geocoder
#> Query completed in: 3 seconds
#> # A tibble: 3 × 3
#> address lat long
#> <chr> <dbl> <dbl>
#> 1 Tokyo, Japan 35.7 140.
#> 2 Lima, Peru -12.1 -77.0
#> 3 Nairobi, Kenya -1.28 36.8
geo("100 Main St New York, NY",
full_results = TRUE,
method = "census", api_options = list(census_return_type = "geographies")
)
#> Passing 1 address to the US Census single address geocoder
#> Query completed in: 4.7 seconds
#> # A tibble: 1 × 27
#> address lat long match…¹ tiger…² tiger…³ geogr…⁴ geogr…⁵ geogr…⁶ geogr…⁷
#> <chr> <dbl> <dbl> <chr> <chr> <chr> <list> <list> <list> <list>
#> 1 100 Main … 40.7 -74.0 100 MA… R 596626… <df> <df> <df> <df>
#> # … with 17 more variables: geographies.Counties <list>,
#> # `geographies.2018 State Legislative Districts - Lower` <list>,
#> # `geographies.116th Congressional Districts` <list>,
#> # `geographies.2020 Census Blocks` <list>,
#> # `geographies.Census Tracts` <list>, addressComponents.zip <chr>,
#> # addressComponents.streetName <chr>, addressComponents.preType <chr>,
#> # addressComponents.city <chr>, addressComponents.preDirection <chr>, …
geo(
county = "Jefferson", state = "Kentucky", country = "US",
method = "osm"
)
#> Passing 1 address to the Nominatim single address geocoder
#> Query completed in: 1 seconds
#> # A tibble: 1 × 5
#> county state country lat long
#> <chr> <chr> <chr> <dbl> <dbl>
#> 1 Jefferson Kentucky US 38.2 -85.7
# }