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.

  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

See also


# \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
# }