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
for more details on geocoder services and API usage.
This function uses the get_api_query, query_api, and
extract_results functions to create, execute, and parse the geocoder
API queries.
geo(
address = NULL,
street = NULL,
city = NULL,
county = NULL,
state = NULL,
postalcode = NULL,
country = NULL,
method = "census",
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 = 10000,
verbose = FALSE,
no_query = FALSE,
custom_query = list(),
return_type = "locations",
iq_region = "us",
geocodio_v = 1.6
)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. Refer to `api_parameter_reference` and the API documentation for each geocoder service for usage details and limitations.
"census": US Census Geocoder. US street-level addresses only.
Can perform batch geocoding.
"osm": Nominatim (OSM). Worldwide coverage.
"geocodio": Commercial geocoder. Covers US and Canada and has
batch geocoding capabilities. Requires an API Key to be stored in
the "GEOCODIO_API_KEY" environmental variable.
"iq": Commercial Nominatim geocoder service. Requires an API Key to
be stored in the "LOCATIONIQ_API_KEY" environmental variable.
"cascade" : Attempts to use 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"
latitude column name. Can be quoted or unquoted (ie. lat or 'lat').
longitude column name. Can be quoted or unquoted (ie. long or 'long').
number of results to return per address. Note that limit > 1 is not compatible with batch geocoding if return_addresses = TRUE.
minimum amount of time for a query to take (in seconds) if using Location IQ or OSM. This parameter is used to abide by API usage limits. You can set it to a lower value (ie. 0) if using a local Nominatim server, for instance.
Custom API URL. If specified, the default API URL will be overridden. This can be used to specify a local Nominatim server.
query timeout (in minutes)
set to 'batch' to force batch geocoding and '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.
returns all data from geocoder service if TRUE
only return results for unique addresses if TRUE
return input addresses with results if TRUE
if TRUE then any nested dataframes in results are flattened
limit to the number of addresses in a batch geocoding query. Both geocodio and census batch geocoders have a 10,000 address limit so this is the default.
if TRUE then detailed logs are output to the console
if TRUE then no queries are sent to the geocoder and verbose is set to TRUE
API-specific parameters to be used, passed as a named list (ie. `list(vintage = 'Current_Census2010')`)
(census only) 'locations' (default) or 'geographies' which returns additional census geography columns. See the Census geocoder API documentation for more details.
'us' (default) or 'eu'. Used for establishing API URL for the 'iq' method
version of geocodio api. 1.6 is default. Used for establishing API URL for the 'geocodio' method.
parsed results from the geocoder service
# 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