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 geocoder 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 geocoder 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",
cascade_order = c("census", "osm"),
lat = lat,
long = long,
limit = 1,
min_time = NULL,
api_url = NULL,
timeout = 20,
mode = "",
full_results = FALSE,
unique_only = FALSE,
return_addresses = TRUE,
flatten = TRUE,
batch_limit = NULL,
batch_limit_error = TRUE,
verbose = FALSE,
no_query = FALSE,
custom_query = list(),
return_type = "locations",
iq_region = "us",
geocodio_v = 1.6,
param_error = TRUE,
mapbox_permanent = FALSE,
here_request_id = NULL,
mapquest_open = FALSE
)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 (zip code if in the United States)
country (ie. 'Japan')
the geocoder 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. An API key must be stored in "GEOCODIO_API_KEY". Batch geocoding is supported.
"iq": Location IQ. An API key must be stored in "LOCATIONIQ_API_KEY".
"google": Google. An API key must be stored in "GOOGLEGEOCODE_API_KEY".
"opencage": OpenCage. An API key must be stored in "OPENCAGE_KEY".
"mapbox": Mapbox. An API key must be stored in "MAPBOX_API_KEY".
"here": HERE. An API key must be stored in "HERE_API_KEY". Batch geocoding is supported, but must be explicitly called with mode = "batch".
"tomtom": TomTom. An API key must be stored in "TOMTOM_API_KEY". Batch geocoding is supported.
"mapquest": MapQuest. An API key must be stored in "MAPQUEST_API_KEY". Batch geocoding is supported.
"bing": Bing. An API key must be stored in "BINGMAPS_API_KEY". Batch geocoding is supported, but must be explicitly called with mode = "batch".
"cascade" : First uses one geocoder service and then uses
a second geocoder service if the first service didn't return results.
The services and order is specified by the cascade_order argument.
Note that this is not compatible with full_results = TRUE as geocoder
services have different columns that they return.
a vector with two character values for the method argument
in the order in which the geocoder services will be attempted for method = "cascade"
(ie. c("census", "geocodio"))
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 geocoder services
the maximum value of the limit parameter is 100. Pass limit = NULL to use
the default limit value of the selected geocoder service.
For batch geocoding, limit must be set to 1 (default) if return_addresses = TRUE.
Refer to api_parameter_reference for more details.
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.
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)
set to 'batch' to force batch geocoding or 'single' to force single address
geocoding (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'.
returns all data from the geocoder service if TRUE. If FALSE then only longitude and latitude are returned from the geocoder service.
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.
if TRUE 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 an error is thrown if the number of addresses exceeds the batch limit. (if executing a batch query). This is reverted to FALSE when using the cascade method.
if TRUE then detailed logs are output to the console
if TRUE then no queries are sent to the geocoder service and verbose is set to TRUE. Used for testing.
API-specific parameters to be used, passed as a named list
(ie. list(extratags = 1).
only used when method = "census". Two possible values:
"locations" (default)
"geographies": returns additional geography columns.
See the Census geocoder API documentation for more details.
"us" (default) or "eu". Used for establishing the API URL for the "iq" method.
version of geocodio API. Used for establishing the API URL for the "geocodio" method.
if TRUE then an error will be thrown if any address parameters are used that are
invalid for the selected service (method). If method = "cascade" then no errors will be thrown.
if TRUE then the mapbox.places-permanent
endpoint would be used. 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.
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 return_addresses
needs to be FALSE.
if TRUE then MapQuest would use the Open Geocoding endpoint, that relies solely on data contributed to OpenStreetMap.
tibble (dataframe)
geocode api_parameter_reference min_time_reference batch_limit_reference
# NOT RUN {
geo(street = "600 Peachtree Street NE", city = "Atlanta",
state = "Georgia", method = "census")
geo(address = c("Tokyo, Japan", "Lima, Peru", "Nairobi, Kenya"),
method = 'osm')
geo(county = 'Jefferson', state = "Kentucky", country = "US",
method = 'osm')
# }
Run the code above in your browser using DataLab