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
)

Arguments

address

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

street address (ie. '1600 Pennsylvania Ave NW')

city

city (ie. 'Tokyo')

county

county (ie. 'Jefferson')

state

state (ie. 'Kentucky')

postalcode

postalcode (zip code if in the United States)

country

country (ie. 'Japan')

method

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.

cascade_order

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'))

lat

latitude column name. Can be quoted or unquoted (ie. lat or 'lat').

long

longitude column name. Can be quoted or unquoted (ie. long or 'long').

limit

number of results to return per address. Note that limit > 1 is not compatible with batch geocoding if return_addresses = TRUE.

min_time

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.

api_url

custom API URL. If specified, the default API URL will be overridden. This can be used to specify a local Nominatim server.

timeout

query timeout (in minutes)

mode

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.

full_results

returns all data from the geocoder service if TRUE. If FALSE then only longitude and latitude are returned from the geocoder service.

unique_only

only return results for unique addresses if TRUE

return_addresses

return input addresses with results if TRUE

flatten

if TRUE then any nested dataframes in results are flattened if possible. Note that Geocodio batch geocoding results are flattened regardless.

batch_limit

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.

verbose

if TRUE then detailed logs are output to the console

no_query

if TRUE then no queries are sent to the geocoder and verbose is set to TRUE

custom_query

API-specific parameters to be used, passed as a named list (ie. list(vintage = 'Current_Census2010')).

return_type

only used when method = 'census'. Two possible values:

  • "locations" (default)

  • "geographies": returns additional geography columns. See the Census geocoder API documentation for more details.

iq_region

'us' (default) or 'eu'. Used for establishing API URL for the 'iq' method

geocodio_v

version of geocodio api. 1.6 is default. Used for establishing API URL for the 'geocodio' method.

Value

parsed geocoding results in tibble format

See also

Examples

# \donttest{ geo(street = "600 Peachtree Street NE", city = "Atlanta", state = "Georgia", method = "census")
#> # A tibble: 1 x 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')
#> # A tibble: 3 x 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(county = 'Jefferson', state = "Kentucky", country = "US", method = 'osm')
#> # A tibble: 1 x 5 #> county state country lat long #> <chr> <chr> <chr> <dbl> <dbl> #> 1 Jefferson Kentucky US 38.2 -85.7
# }