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"
(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').
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 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.
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 addresses if TRUE
return input addresses with results if TRUE
if TRUE then any nested dataframes in results are flattened if possible. Note that Geocodio batch geocoding results are flattened regardless.
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')).
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 API URL for the 'iq' method
version of geocodio api. 1.6 is default. Used for establishing API URL for the 'geocodio' method.
parsed geocoding results in tibble format
# 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