geo {tidygeocoder}

Geocode addresses

Description

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 geocoding 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 geocoding 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.

Usage

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,
  full_results = FALSE,
  mode = "",
  unique_only = FALSE,
  return_addresses = TRUE,
  min_time = NULL,
  progress_bar = show_progress_bar(),
  quiet = getOption("tidygeocoder.quiet", FALSE),
  api_url = NULL,
  timeout = 20,
  flatten = TRUE,
  batch_limit = NULL,
  batch_limit_error = TRUE,
  verbose = getOption("tidygeocoder.verbose", FALSE),
  no_query = FALSE,
  custom_query = list(),
  api_options = list(),
  return_type = "locations",
  iq_region = "us",
  geocodio_v = 1.6,
  param_error = TRUE,
  mapbox_permanent = FALSE,
  here_request_id = NULL,
  mapquest_open = FALSE
)

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 (ie. zip code if in the United States)

country

country (ie. 'Japan')

method

the geocoding 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 the environmental variable "GEOCODIO_API_KEY". Batch geocoding is supported.

• "iq": Location IQ. An API key must be stored in the environmental variable "LOCATIONIQ_API_KEY".

• "google": Google. An API key must be stored in the environmental variable "GOOGLEGEOCODE_API_KEY".

• "opencage": OpenCage. An API key must be stored in the environmental variable "OPENCAGE_KEY".

• "mapbox": Mapbox. An API key must be stored in the environmental variable "MAPBOX_API_KEY".

• "here": HERE. An API key must be stored in the environmental variable "HERE_API_KEY". Batch geocoding is supported, but must be explicitly called with mode = "batch".

• "tomtom": TomTom. An API key must be stored in the environmental variable "TOMTOM_API_KEY". Batch geocoding is supported.

• "mapquest": MapQuest. An API key must be stored in the environmental variable "MAPQUEST_API_KEY". Batch geocoding is supported.

• "bing": Bing. An API key must be stored in the environmental variable "BINGMAPS_API_KEY". Batch geocoding is supported, but must be explicitly called with mode = "batch".

• "geoapify": Geoapify. An API key must be stored in the environmental variable "GEOAPIFY_KEY".

• "cascade" use geocode_combine or geo_combine instead. The "cascade" method first uses one geocoding service and then uses a second geocoding 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 geocoding 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 geocoding 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

maximum number of results to return per input address. For many geocoding services the maximum value of the limit parameter is 100. Pass limit = NULL to use the default limit value of the selected geocoding service. For batch geocoding, limit must be set to 1 (default) if return_addresses = TRUE. Refer to api_parameter_reference for more details.

full_results

returns all available data from the geocoding service if TRUE. If FALSE (default) then only latitude and longitude columns are returned from the geocoding service.

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. For the "here" and "bing" methods the batch mode should be explicitly specified with mode = 'batch'.

unique_only

only return results for unique inputs if TRUE

return_addresses

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.

min_time

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.

progress_bar

if TRUE then a progress bar will be displayed for single input geocoding (1 input per query). By default the progress bar will not be shown for code executed when knitting R Markdown files or code within an RStudio notebook chunk. Can be set permanently with options(tidygeocoder.progress_bar = FALSE).

quiet

if TRUE then console messages that are displayed by default regarding queries will be suppressed. FALSE is default. Can be set permanently with options(tidygeocoder.quiet = TRUE).

api_url

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.

timeout

query timeout (in minutes)

flatten

if TRUE (default) 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.

batch_limit

limit to the number of addresses in a batch geocoding query. Defaults to the value in batch_limit_reference if not specified.

batch_limit_error

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.

verbose

if TRUE then detailed logs are output to the console. FALSE is default. Can be set permanently with options(tidygeocoder.verbose = TRUE)

no_query

if TRUE then no queries are sent to the geocoding service and verbose is set to TRUE. Used for testing.

custom_query

API-specific parameters to be used, passed as a named list (ex. list(extratags = 1).

api_options

a named list of parameters specific to individual services. (ex. list(geocodio_v = 1.6, geocodio_hipaa = TRUE)). Each parameter begins with the name of the method (service) it applies to. The possible parameters are shown below with their default values.

• census_return_type (default: "locations"): set to "geographies" to return additional geography columns. Make sure to use full_results = TRUE if using the "geographies" setting.

• iq_region (default: "us"): set to "eu" to use the European Union API endpoint

• geocodio_v (default: 1.6): the version number of the Geocodio API to be used

• geocodio_hipaa (default: FALSE): set to TRUE to use the HIPAA compliant Geocodio API endpoint

• mapbox_permanent (default: FALSE): set to TRUE to use the mapbox.places-permanent endpoint. 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.

• mapbox_open (default: FALSE): set to TRUE to use the Open Geocoding endpoint which relies solely on OpenStreetMap data

• here_request_id (default: NULL): 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 the return_addresses or return_coords parameters need to be FALSE.

return_type

use the api_options parameter instead

iq_region

use the api_options parameter instead

geocodio_v

use the api_options parameter instead

param_error

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.

mapbox_permanent

use the api_options parameter instead

here_request_id

use the api_options parameter instead

mapquest_open

use the api_options parameter instead

Value

tibble (dataframe)

See Also

geocode api_parameter_reference min_time_reference batch_limit_reference

Examples

options(tidygeocoder.progress_bar = FALSE)

geo(street = "600 Peachtree Street NE", city = "Atlanta",
 state = "Georgia", method = "census")

geo(address = c("Tokyo, Japan", "Lima, Peru", "Nairobi, Kenya"),
 method = 'osm')
 
geo("100 Main St New York, NY",  full_results = TRUE,
 method = "census", api_options = list(census_return_type = 'geographies'))

geo(county = 'Jefferson', state = "Kentucky", country = "US",
     method = 'osm')