tidygeocoder

https://jessecambon.github.io/tidygeocoder/
Admin
tidygeocoder is an R package that provides a unified interface for geocoding services, enabling...
Tokens:20,525
Snippets:176
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Execute get_api_query examples

Source: https://jessecambon.github.io/tidygeocoder/reference/get_api_query.html

Examples demonstrating how to construct queries for OSM and Census geocoding services.

```R
get_api_query("osm", list(address = "Hanoi, Vietnam"))
#> $q
#> [1] "Hanoi, Vietnam"
#> 
#> $format
#> [1] "json"
#> 

get_api_query(
  "census", list(street = "11 Wall St", city = "NY", state = "NY"),
  list(benchmark = "Public_AR_Census2010")
)
#> $street
#> [1] "11 Wall St"
#> 
#> $city
#> [1] "NY"
#> 
#> $state
#> [1] "NY"
#> 
#> $benchmark
#> [1] "Public_AR_Census2010"
#> 
#> $format
#> [1] "json"
#> 
#> $vintage
#> [1] "Current_Current"
#>
```

--------------------------------

### Install tidygeocoder from GitHub

Source: https://jessecambon.github.io/tidygeocoder/index.html

Installs the latest development version of the tidygeocoder package from GitHub using devtools.

```r
devtools::install_github("jessecambon/tidygeocoder")
```

--------------------------------

### Install tidygeocoder from CRAN

Source: https://jessecambon.github.io/tidygeocoder/index.html

Installs the stable version of the tidygeocoder package from CRAN.

```r
install.packages('tidygeocoder')
```

--------------------------------

### Execute multiple geocoding queries

Source: https://jessecambon.github.io/tidygeocoder/reference/geo_combine.html

Examples demonstrating how to use geo_combine to run multiple geocoding methods, handle address inputs, and manage output formats.

```R
# \donttest{

options(tidygeocoder.progress_bar = FALSE)
example_addresses <- c("100 Main St New York, NY", "Paris", "Not a Real Address")

geo_combine(
  queries = list(
    list(method = "census"),
    list(method = "osm")
  ),
  address = example_addresses,
  global_params = list(address = "address")
)
#> 
#> 
#> Passing 3 addresses to the US Census batch geocoder
#> Query completed in: 0.2 seconds
#> Passing 2 addresses to the Nominatim single address geocoder
#> Query completed in: 2 seconds
#> # A tibble: 3 × 4
#>   address                    lat   long query   
#>   <chr>                    <dbl>  <dbl> <chr>   
#> 1 100 Main St New York, NY  40.7 -74.0  "census"
#> 2 Paris                     48.9   2.32 "osm"   
#> 3 Not a Real Address        NA    NA    ""      

geo_combine(
  queries = list(
    list(method = "arcgis"),
    list(method = "census", mode = "single"),
    list(method = "census", mode = "batch")
  ),
  global_params = list(address = "address"),
  address = example_addresses,
  cascade = FALSE,
  return_list = TRUE
)
#> 
#> 
#> 
#> Passing 3 addresses to the ArcGIS single address geocoder
#> Query completed in: 0.4 seconds
#> Passing 3 addresses to the US Census single address geocoder
#> Query completed in: 0.4 seconds
#> Passing 3 addresses to the US Census batch geocoder
#> Query completed in: 0.2 seconds
#> $arcgis
#> # A tibble: 3 × 3
#>   address                    lat   long
#>   <chr>                    <dbl>  <dbl>
#> 1 100 Main St New York, NY  40.8 -73.9 
#> 2 Paris                     48.9   2.36
#> 3 Not a Real Address        NA    NA   
#> 
#> $census1
#> # A tibble: 3 × 3
#>   address                    lat  long
#>   <chr>                    <dbl> <dbl>
#> 1 100 Main St New York, NY  40.7 -74.0
#> 2 Paris                     NA    NA  
#> 3 Not a Real Address        NA    NA  
#> 
#> $census2
#> # A tibble: 3 × 3
#>   address                    lat  long
#>   <chr>                    <dbl> <dbl>
#> 1 100 Main St New York, NY  40.7 -74.0
#> 2 Paris                     NA    NA  
#> 3 Not a Real Address        NA    NA  
#> 

geo_combine(
  queries = list(
    list(method = "arcgis", address = "city"),
    list(method = "osm", city = "city", country = "country")
  ),
  city = c("Tokyo", "New York"),
  country = c("Japan", "United States"),
  cascade = FALSE
)
#> 
#> 
#> Passing 2 addresses to the ArcGIS single address geocoder
#> Query completed in: 1.3 seconds
#> Passing 2 addresses to the Nominatim single address geocoder
#> Query completed in: 2 seconds
#> # A tibble: 4 × 5
#>   city     country         lat  long query 
#>   <chr>    <chr>         <dbl> <dbl> <chr> 
#> 1 Tokyo    Japan          35.7 140.  arcgis
#> 2 Tokyo    Japan          35.7 140.  osm   
#> 3 New York United States  40.7 -74.0 arcgis
#> 4 New York United States  40.7 -74.0 osm   
# }
```

--------------------------------

### ArcGIS Service - Custom Query Example

Source: https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html

Demonstrates how to use the ArcGIS service with a custom query to include an API Key.

```APIDOC
## POST /api/geocoder/arcgis

### Description
This example shows how to use the ArcGIS geocoding service with a custom query parameter to pass an API key.

### Method
POST

### Endpoint
/api/geocoder/arcgis

### Parameters
#### Query Parameters
- **address** (string) - Required - The address to geocode.
- **method** (string) - Required - The geocoding service to use (e.g., "arcgis").
- **custom_query** (list) - Optional - A list of custom query parameters to pass to the API.

### Request Example
```R
tidygeocoder::geo(address = "New York, USA", method = "arcgis",
  custom_query = list(token = "<API_KEY>"))
```

### Response
#### Success Response (200)
- **location** (list) - The geocoded location data.
- **accuracy** (numeric) - The accuracy of the geocoded result.

#### Response Example
```json
{
  "location": {
    "lat": 40.7128,
    "long": -74.0060
  },
  "accuracy": "Rooftop"
}
```
```

--------------------------------

### Perform Reverse Geocoding

Source: https://jessecambon.github.io/tidygeocoder/reference/reverse_geo.html

Examples of using reverse_geo to convert coordinates into addresses, including handling multiple inputs and full result sets.

```R
# \donttest{
options(tidygeocoder.progress_bar = FALSE)

reverse_geo(lat = 38.895865, long = -77.0307713, method = "osm")
#> Passing 1 coordinate to the Nominatim single coordinate geocoder
#> Query completed in: 1 seconds
#> # A tibble: 1 × 3
#>     lat  long address                                                           
#>   <dbl> <dbl> <chr>                                                             
#> 1  38.9 -77.0 L’Enfant's plan, Pennsylvania Avenue, Penn Quarter, Ward 2, Washi…

reverse_geo(
  lat = c(38.895865, 43.6534817, 300),
  long = c(-77.0307713, -79.3839347, 600),
  method = "osm", full_results = TRUE
)
#> Passing 2 coordinates to the Nominatim single coordinate geocoder
#> Query completed in: 2 seconds
#> # A tibble: 3 × 31
#>     lat  long address    place_id licence osm_type  osm_id osm_lat osm_lon class
#>   <dbl> <dbl> <chr>         <int> <chr>   <chr>      <int> <chr>   <chr>   <chr>
#> 1  38.9 -77.0 L’Enfant'…   3.20e8 Data ©… way       9.00e8 38.895… -77.03… tour…
#> 2  43.7 -79.4 Toronto C…   3.24e8 Data ©… way       1.99e8 43.653… -79.38… amen…
#> 3  NA    NA   NA          NA      NA      NA       NA      NA      NA      NA   
#> # ℹ 21 more variables: type <chr>, place_rank <int>, importance <dbl>,
#> #   addresstype <chr>, name <chr>, tourism <chr>, road <chr>, suburb <chr>,
#> #   borough <chr>, city <chr>, state <chr>, `ISO3166-2-lvl4` <chr>,
#> #   postcode <chr>, country <chr>, country_code <chr>, boundingbox <list>,
#> #   amenity <chr>, house_number <chr>, city_block <chr>, quarter <chr>,
#> #   state_district <chr>
# }
```

--------------------------------

### GET /api_parameter_reference

Source: https://jessecambon.github.io/tidygeocoder/reference/api_parameter_reference.html

Retrieves the mapping dataset used to translate universal parameter names to service-specific API parameters.

```APIDOC
## GET /api_parameter_reference

### Description
Returns a tibble dataframe containing the mapping between universal parameter names and service-specific API parameter names.

### Method
GET

### Endpoint
api_parameter_reference

### Response
#### Success Response (200)
- **method** (string) - Geocoding service name
- **generic_name** (string) - Universal parameter name
- **api_name** (string) - Name of the parameter for the specified geocoding service
- **default_value** (string) - Default value of the parameter
- **required** (boolean) - Is the parameter required by the specified geocoding service?
```

--------------------------------

### Combine Multiple Geocoders with Query Names

Source: https://jessecambon.github.io/tidygeocoder/reference/geocode_combine.html

Geocodes addresses using 'census' (batch and single) and 'osm' methods, assigning custom names to each query. This example demonstrates handling different address components for each geocoder.

```R
more_addresses %>%
  geocode_combine(
    queries = list(
      list(method = "census", mode = "batch"),
      list(method = "census", mode = "single"),
      list(method = "osm")
    ),
    global_params = list(
      street = "street_address",
      city = "city", state = "state", postalcode = "zip_cd"
    ),
    query_names = c("census batch", "census single", "osm")
  )
```

--------------------------------

### Geocode Single Address - tidygeocoder

Source: https://jessecambon.github.io/tidygeocoder/reference/query_api.html

Example of geocoding a single address using the Nominatim API. Requires get_api_query to format parameters and query_api to execute the request. Results are then extracted using extract_results.

```R
# \donttest{
raw1 <- query_api(
  "http://nominatim.openstreetmap.org/search",
  get_api_query("osm", list(address = "Hanoi, Vietnam"))
)

raw1$status
#> [1] 200

extract_results("osm", jsonlite::fromJSON(raw1$content))
#>        lat     lon  place_id
#> 1 21.02833 105.854 221315765
#>                                                                 licence
#> 1 Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright
#>   osm_type  osm_id    class           type place_rank importance addresstype
#> 1 relation 1903516 boundary administrative          8   0.681334        city
#>               name               display_name
#> 1 Thành phố Hà Nội Thành phố Hà Nội, Việt Nam
#>                                        boundingbox
#> 1 20.5645154, 21.3852777, 105.2889615, 106.0200725
# }
```

--------------------------------

### Pass Custom API Parameters

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Use the custom_query argument to pass service-specific parameters as a named list. This example requests GeoJSON geometry from the Nominatim geocoder.

```R
cairo_geo <- geo("Cairo, Egypt",
  method = "osm", full_results = TRUE,
  custom_query = list(polygon_geojson = 1), verbose = TRUE
)
#> 
#> Number of Unique Addresses: 1
#> Passing 1 address to the Nominatim single address geocoder
#> 
#> Number of Unique Addresses: 1
#> Querying API URL: https://nominatim.openstreetmap.org/search
#> Passing the following parameters to the API:
#> q : "Cairo, Egypt"
#> limit : "1"
#> polygon_geojson : "1"
#> format : "json"
#> HTTP Status Code: 200
#> Query completed in: 0.4 seconds
#> Total query time (including sleep): 1 seconds
#> 
#> Query completed in: 1 seconds

glimpse(cairo_geo)
```

--------------------------------

### Reverse Geocode Coordinates - tidygeocoder

Source: https://jessecambon.github.io/tidygeocoder/reference/query_api.html

Example of performing a reverse geocoding query using Nominatim API for given latitude and longitude. Uses get_api_query for parameters and query_api for execution, with results extracted by extract_reverse_results.

```R
raw2 <- query_api(
  "http://nominatim.openstreetmap.org/reverse",
  get_api_query("osm", custom_parameters = list(lat = 38.895865, lon = -77.0307713))
)

extract_reverse_results("osm", jsonlite::fromJSON(raw2$content))
#> # A tibble: 1 × 24
#>   display_name      place_id licence osm_type osm_id osm_lat osm_lon class type 
#>   <chr>                <int> <chr>   <chr>     <int> <chr>   <chr>   <chr> <chr>
#> 1 L’Enfant's plan,…   3.20e8 Data ©… way      9.00e8 38.895… -77.03… tour… artw…
#> # ℹ 15 more variables: place_rank <int>, importance <dbl>, addresstype <chr>,
#> #   name <chr>, tourism <chr>, road <chr>, suburb <chr>, borough <chr>,
#> #   city <chr>, state <chr>, `ISO3166-2-lvl4` <chr>, postcode <chr>,
#> #   country <chr>, country_code <chr>, boundingbox <list>
# }
```

--------------------------------

### GET /reverse_geo

Source: https://jessecambon.github.io/tidygeocoder/reference/reverse_geo.html

Performs reverse geocoding to retrieve address information from latitude and longitude coordinates.

```APIDOC
## GET /reverse_geo

### Description
Retrieves address information based on provided latitude and longitude coordinates.

### Method
GET

### Parameters
#### Query Parameters
- **lat** (numeric) - Required - Latitude coordinate(s).
- **long** (numeric) - Required - Longitude coordinate(s).
- **method** (string) - Required - The geocoding service to use (e.g., "osm").
- **full_results** (boolean) - Optional - Whether to return full API response details.

### Response
#### Success Response (200)
- **tibble** (dataframe) - A dataframe containing the geocoded address information.
```

--------------------------------

### Build Site with pkgdown

Source: https://jessecambon.github.io/tidygeocoder/articles/developer_notes.html

Use pkgdown to build the package website. Re-run if further updates are needed.

```r
pkgdown::build_site()
```

--------------------------------

### Check URLs with urlchecker

Source: https://jessecambon.github.io/tidygeocoder/articles/developer_notes.html

Verify all URLs within the package documentation are valid.

```r
urlchecker::url_check()
```

--------------------------------

### Access sample_addresses dataset

Source: https://jessecambon.github.io/tidygeocoder/reference/sample_addresses.html

Use this dataset to test geocoding functions with pre-defined address strings.

```R
sample_addresses
```

--------------------------------

### Geocode Addresses with tidygeocoder

Source: https://jessecambon.github.io/tidygeocoder/articles/developer_notes.html

Demonstrates forward geocoding of a list of locations using the 'osm' method. Shows how to handle duplicate inputs and retrieve full geocoding results with verbose output.

```R
library(dplyr)
library(tidygeocoder)

df <- tibble(
  id = c(1, 2, 1),
  locations = c('tokyo', 'madrid', 'tokyo')
  )

df %>%
  geocode(address = locations, method = 'osm', full_results = TRUE, verbose = TRUE)
```

--------------------------------

### Release New Version with devtools

Source: https://jessecambon.github.io/tidygeocoder/articles/developer_notes.html

Execute the final release process for the package once all checks are passed.

```r
devtools::release()
```

--------------------------------

### Tidygeocoder Arguments Reference

Source: https://jessecambon.github.io/tidygeocoder/reference/geo.html

A comprehensive list of arguments for Tidygeocoder functions, detailing their purpose, types, and usage.

```APIDOC
## Tidygeocoder Arguments

### Address Arguments

- **address** (string) - A single line address (e.g., '1600 Pennsylvania Ave NW, Washington, DC'). Do not combine with the address component arguments below (`street`, `city`, `county`, `state`, `postalcode`, `country`).
- **street** (string) - Street address (e.g., '1600 Pennsylvania Ave NW')
- **city** (string) - City (e.g., 'Tokyo')
- **county** (string) - County (e.g., 'Jefferson')
- **state** (string) - State (e.g., 'Kentucky')
- **postalcode** (string) - Postal code (e.g., zip code if in the United States)
- **country** (string) - Country (e.g., 'Japan')

### Geocoding Method

- **method** (string) - 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. Batch geocoding is supported. Store an API key in the environmental variable `"GEOCODIO_API_KEY"`.
  * "iq"`: Location IQ. Store an API key in the environmental variable `"LOCATIONIQ_API_KEY"`.
  * "google"`: Google. Store an API key in the environmental variable `"GOOGLEGEOCODE_API_KEY"`.
  * "opencage"`: OpenCage. Store an API key in the environmental variable `"OPENCAGE_KEY"`.
  * "mapbox"`: Mapbox. Store an API key in the environmental variable `"MAPBOX_API_KEY"`.
  * "here"`: HERE. Batch geocoding is supported, but must be explicitly called with `mode = "batch"`. Store an API key in the environmental variable `"HERE_API_KEY"`.
  * "tomtom"`: TomTom. Batch geocoding is supported. Store an API key in the environmental variable `"TOMTOM_API_KEY"`.
  * "mapquest"`: MapQuest. Batch geocoding is supported. Store an API key in the environmental variable `"MAPQUEST_API_KEY"`.
  * "bing"`: Bing. Batch geocoding is supported, but must be explicitly called with `mode = "batch"`. Store an API key in the environmental variable `"BINGMAPS_API_KEY"`.
  * "geoapify"`: Geoapify. Store an API key in the environmental variable `"GEOAPIFY_KEY"`.

### Output Control

- **lat** (string) - Latitude column name. Can be quoted or unquoted (e.g., `lat` or `"lat"`).
- **long** (string) - Longitude column name. Can be quoted or unquoted (e.g., `long` or `"long"`).
- **limit** (integer) - 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** (boolean) - 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** (string) - 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** (boolean) - Only return results for unique inputs if TRUE.
- **return_addresses** (boolean) - 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** (numeric) - 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** (boolean) - 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** (boolean) - 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** (string) - 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** (numeric) - Query timeout (in minutes).
- **flatten** (boolean) - 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** (integer) - Limit to the number of addresses in a batch geocoding query. Defaults to the value in batch_limit_reference if not specified.
- **verbose** (boolean) - If TRUE then detailed logs are output to the console. FALSE is default. Can be set permanently with `options(tidygeocoder.verbose = TRUE)`.
- **no_query** (boolean) - 
```

--------------------------------

### Prepare Address Data

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Define input dataframes for single-line addresses and address components.

```R
library(tibble)
library(dplyr)
library(tidygeocoder)

address_single <- tibble(singlelineaddress = c(
  "11 Wall St, NY, NY",
  "600 Peachtree Street NE, Atlanta, Georgia"
))
address_components <- tribble(
  ~street, ~cty, ~st,
  "11 Wall St", "NY", "NY",
  "600 Peachtree Street NE", "Atlanta", "GA"
)
```

--------------------------------

### POST geo_combine

Source: https://jessecambon.github.io/tidygeocoder/reference/geo_combine.html

Executes multiple geocoding queries based on provided parameters and service configurations.

```APIDOC
## POST geo_combine

### Description
Executes a list of geocoding queries using specified services and parameters. Results are returned as a tibble.

### Method
POST

### Endpoint
geo_combine

### Parameters
#### Request Body
- **queries** (list) - Required - A list of queries, each provided as a list of parameters.
- **global_params** (list) - Optional - A list of parameters to be used for all queries.
- **address** (string) - Optional - Single line address.
- **street** (string) - Optional - Street address.
- **city** (string) - Optional - City name.
- **county** (string) - Optional - County name.
- **state** (string) - Optional - State name.
- **postalcode** (string) - Optional - Postal code.
- **country** (string) - Optional - Country name.
- **lat** (string) - Optional - Latitude column name.
- **long** (string) - Optional - Longitude column name.

### Response
#### Success Response (200)
- **tibble** (object) - A dataframe containing the geocoding results including address, latitude, longitude, and the query method used.
```

--------------------------------

### API Key Reference

Source: https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html

Lists the environment variable names used to store API keys for various geocoding services.

```APIDOC
## API Key Retrieval

API keys for geocoding services are typically stored in environment variables. The following table lists the service method and the corresponding environment variable name.

| method | env_var |
|---|---|
| geocodio | GEOCODIO_API_KEY |
| iq | LOCATIONIQ_API_KEY |
| google | GOOGLEGEOCODE_API_KEY |
| opencage | OPENCAGE_KEY |
| mapbox | MAPBOX_API_KEY |
| here | HERE_API_KEY |
| tomtom | TOMTOM_API_KEY |
| mapquest | MAPQUEST_API_KEY |
| bing | BINGMAPS_API_KEY |
| geoapify | GEOAPIFY_KEY |
```

--------------------------------

### Geocode by county and state using OSM

Source: https://jessecambon.github.io/tidygeocoder/reference/geo.html

Geocode an address specified by county and state using the 'osm' method. This is useful when a full street address is not available.

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

--------------------------------

### Limit Geocoding Results

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Use the limit argument to specify the maximum number of results per input address. Setting limit = NULL uses the service default.

```R
geo_limit <- geo(
  c("Lima, Peru", "Cairo, Egypt"),
  method = "osm",
  limit = 3, full_results = TRUE
)
#> Passing 2 addresses to the Nominatim single address geocoder
#> Query completed in: 2 seconds

glimpse(geo_limit)
```

--------------------------------

### Geocode Addresses using OSM with Limited Results

Source: https://jessecambon.github.io/tidygeocoder/reference/geocode.html

Geocodes addresses using the Nominatim (OpenStreetMap) single address geocoder, limiting results to 2 per address and not returning input data. Requires the 'osm' method, 'limit = 2', and 'return_input = FALSE'.

```R
sample_addresses %>%
  slice(8:9) %>%
  geocode(addr,
    method = "osm", limit = 2,
    return_input = FALSE, full_results = TRUE
  )
```

--------------------------------

### Perform Dry-Run Queries

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Set no_query = TRUE to test the geocoding workflow without sending data to the service. This returns NA results.

```R
noquery1 <- geo(c("Vancouver, Canada", "Las Vegas, NV"),
  no_query = TRUE,
  method = "arcgis"
)
#> 
#> Number of Unique Addresses: 2
#> Passing 2 addresses to the ArcGIS single address geocoder
#> 
#> Number of Unique Addresses: 1
```

--------------------------------

### Geocoding Service Parameters

Source: https://jessecambon.github.io/tidygeocoder/reference/reverse_geo.html

Configuration parameters for specific geocoding service providers supported by the package.

```APIDOC
## Geocoding Service Parameters

### Description
Configuration options for various geocoding providers including Geocodio, Mapbox, MapQuest, and HERE.

### Parameters
- **census_return_type** (string) - Optional - Set to "geographies" to return additional geography columns (requires full_results = TRUE).
- **iq_region** (string) - Optional - Set to "eu" to use the European Union API endpoint.
- **geocodio_v** (numeric) - Optional - Version number of the Geocodio API.
- **geocodio_hipaa** (boolean) - Optional - Set to TRUE to use the HIPAA compliant Geocodio API endpoint.
- **mapbox_permanent** (boolean) - Optional - Set to TRUE to use the mapbox.places-permanent endpoint.
- **mapquest_open** (boolean) - Optional - Set to TRUE to use the Open Geocoding endpoint.
- **here_request_id** (string) - Optional - Returns a previous HERE batch job identified by its RequestID.
```

--------------------------------

### Usage Notes

Source: https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html

Important usage considerations and limitations for various geocoding services within Tidygeocoder.

```APIDOC
## Usage Notes

### US Census Batch Geocoding
- When using batch mode with the US Census geocoder, `NA` data is returned for addresses with multiple results. It is recommended to handle these "Tie" indications by performing single address geocoding for those specific addresses. See #87.

### Mapbox Reverse Geocoding
- For reverse geocoding with the Mapbox service, the `types` parameter must be set if `limit` is greater than 1. See #104.

### Bing Batch Geocoder
- The Bing batch geocoder does not support the `limit` parameter. See #106.

### US Census Address Level
- The US Census service only supports street-level addresses (e.g., "11 Wall St New York, NY"). Partial addresses like "New York, NY" are not supported.

### Mapbox Batch Geocoding Implementation
- While the Mapbox service supports batch geocoding via its permanent endpoint, this functionality is not yet implemented in Tidygeocoder. Contributions are welcome (see #73).

### ArcGIS Batch Geocoding Implementation
- Similar to Mapbox, the ArcGIS service supports batch geocoding, but this is not currently implemented in Tidygeocoder. Contributions are welcome (see #102).

### ArcGIS `outFields` Parameter
- As of tidygeocoder v1.0.6, the ArcGIS `outFields` parameter is set to `*` (all fields) by default. To return only default fields, use the following parameter in your query: `custom_query = list(outFields='')`. See #177 for more details.

### ArcGIS API Key
- An API Key is not strictly required for the ArcGIS service if used solely for search capabilities (refer to Free vs. paid operations). An API Key can be included via the `custom_query` parameter, as shown in the example for the ArcGIS service.
```

--------------------------------

### Check Spelling with devtools

Source: https://jessecambon.github.io/tidygeocoder/articles/developer_notes.html

Perform a spell check on the package documentation and code.

```r
devtools::spell_check()
```

--------------------------------

### Batch Query Size Limits

Source: https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html

Details the maximum number of inputs allowed per batch query for each geocoding service.

```APIDOC
## Batch Query Size Limits

The maximum number of inputs (addresses or coordinates) that can be included in a single batch query for each geocoding service is listed below.

| method | batch_limit |
|---|---|
| census | 10,000 |
| geocodio | 10,000 |
| tomtom | 10,000 |
| here | 1,000,000 |
| mapquest | 100 |
| bing | 50 |
```

--------------------------------

### Geocode Addresses with tidygeocoder

Source: https://jessecambon.github.io/tidygeocoder/index.html

Loads necessary libraries and creates a tibble of addresses for geocoding. This is a prerequisite for using the geocode() function.

```r
library(dplyr, warn.conflicts = FALSE)
library(tidygeocoder)

# create a dataframe with addresses
some_addresses <- tibble::tribble(
~name,                  ~addr,
"White House",          "1600 Pennsylvania Ave NW, Washington, DC",
"Transamerica Pyramid", "600 Montgomery St, San Francisco, CA 94111",     
"Willis Tower",         "233 S Wacker Dr, Chicago, IL 60606"
)
```

--------------------------------

### Create API Query - tidygeocoder

Source: https://jessecambon.github.io/tidygeocoder/reference/query_api.html

Use query_api to create geocoding API queries. Specify the API URL, query parameters, and mode (single, list, or file).

```R
query_api(
  api_url,
  query_parameters,
  mode = "single",
  batch_file = NULL,
  input_list = NULL,
  content_encoding = "UTF-8",
  timeout = 20,
  method = ""
)
```

--------------------------------

### API Parameter Reference

Source: https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html

A reference table mapping generic geocoding parameter names to specific API parameter names for different geocoding services.

```APIDOC
## API Parameters Reference

This table maps generic parameter names used in tidygeocoder to the specific parameter names required by each geocoding service.

### US Census Service Parameters

| generic_name | api_name | default_value | required |
|---|---|---|---|
| format | format | json | true |
| benchmark | benchmark | Public_AR_Current | true |
| vintage | vintage | Current_Current | true |
| address | address |  | false |
| street | street |  | false |
| city | city |  | false |
| state | state |  | false |
| postalcode | zip |  | false |

### OpenStreetMap (OSM) Service Parameters

| generic_name | api_name | default_value | required |
|---|---|---|---|
| format | format | json | true |
| limit | limit | 1 | false |
```

--------------------------------

### ArcGIS Geocoding with Custom Query Parameter

Source: https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html

Demonstrates how to use the ArcGIS geocoding service with a custom query parameter to include an API key. This is useful when an API key is not strictly required but can be provided.

```r
tidygeocoder::geo(address = "New York, USA", method = "arcgis",
  custom_query = list(token = "<API_KEY>"))
```

--------------------------------

### Retrieve citation for tidygeocoder

Source: https://jessecambon.github.io/tidygeocoder/index.html

Use this function within an R environment to display the package citation and BibTeX entry.

```R
citation('tidygeocoder')
```

--------------------------------

### Minimum Time Per Query Reference

Source: https://jessecambon.github.io/tidygeocoder/articles/geocoder_services.html

Specifies the minimum time in seconds required between queries for each geocoding service to comply with their usage policies.

```APIDOC
## Minimum Time Per Query

The minimum time (in seconds) required between queries for each geocoding service to adhere to usage limitations is provided below.

| method | min_time | description |
|---|---|---|
| osm | 1.00 | 1 query per second |
| geocodio | 0.06 | 1000 queries per minute (free tier) |
| iq | 1.00 | 60 queries per minute (free tier) |
| google | 0.02 | 50 queries per second |
| opencage | 1.00 | 1 query per second (free tier) |
| mapbox | 0.10 | 600 queries per minute (free tier) |
| tomtom | 0.20 | 5 queries per second (free tier) |
| here | 0.20 | 5 queries per second (free tier) |
| geoapify | 0.20 | 5 queries per second (free tier) |
```

--------------------------------

### Set Global Verbose Option

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Configures the verbose setting globally for all geocoding queries.

```R
options(tidygeocoder.verbose = TRUE)
```

--------------------------------

### Combine Multiple Geocoding Queries

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Executes multiple geocoding services sequentially using geocode_combine, with the default cascade behavior passing only unfound addresses to subsequent queries.

```R
addresses_combine <- tibble(
  address = c('100 Wall Street NY, NY', 'Paris', 'Not An Address')
)

cascade_results1 <- addresses_combine %>%
  geocode_combine(
    queries = list(
      list(method = 'census'),
      list(method = 'osm')
    ),
    global_params = list(address = 'address')
  )
```

--------------------------------

### Execute a geocoder API query

Source: https://jessecambon.github.io/tidygeocoder/reference/query_api.html

The `query_api` function is used to send requests to geocoding services. It supports single queries, batch queries from a list, or batch queries from a file.

```APIDOC
## POST /api/query

### Description
Executes a geocoding API query to a specified service.

### Method
POST

### Endpoint
/api/query

### Parameters
#### Query Parameters
- **api_url** (string) - Required - Base URL of the API. Query parameters are appended to this.
- **query_parameters** (list) - Required - API query parameters in the form of a named list.
- **mode** (string) - Optional - Determines the type of query to execute. Options: "single", "list", "file". Defaults to "single".
- **batch_file** (file) - Optional - A CSV file of input data to upload (for `mode = 'file'`).
- **input_list** (list) - Optional - A list of input data (for `mode = 'list'`).
- **content_encoding** (string) - Optional - Encoding to be used for parsing content. Defaults to "UTF-8".
- **timeout** (integer) - Optional - Timeout in minutes. Defaults to 20.
- **method** (string) - Optional - If 'mapquest' or 'arcgis', the query status code is changed appropriately.

### Request Example
```json
{
  "api_url": "http://nominatim.openstreetmap.org/search",
  "query_parameters": {
    "address": "Hanoi, Vietnam"
  },
  "mode": "single"
}
```

### Response
#### Success Response (200)
- **content** (string) - The response content from the API.
- **status** (integer) - The HTTP request status code.

#### Response Example
```json
{
  "content": "[JSON response from API]",
  "status": 200
}
```
```

--------------------------------

### Handle Duplicate and Missing Data

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Demonstrates how tidygeocoder automatically filters unique addresses and ignores NA values during geocoding.

```R
# create a dataset with duplicate and NA addresses
duplicate_addrs <- address_single %>%
  bind_rows(address_single) %>%
  bind_rows(tibble(singlelineaddress = rep(NA, 3)))

duplicates_geocoded <- duplicate_addrs %>%
  geocode(singlelineaddress, verbose = TRUE)
```

--------------------------------

### Geocode by Address Components

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Geocode using specific address fields like street, city, and state instead of a single string.

```R
census_c1 <- address_components %>%
  geocode(street = street, city = cty, state = st, method = "census")
```

--------------------------------

### Utility Functions

Source: https://jessecambon.github.io/tidygeocoder/reference/index.html

Functions for constructing, executing, and extracting results from geocoder API queries.

```APIDOC
## get_api_query()
### Description
Construct a geocoder API query.

## query_api()
### Description
Execute a geocoder API query.

## extract_results()
### Description
Extract forward geocoding results.

## extract_reverse_results()
### Description
Extract reverse geocoding results.
```

--------------------------------

### get_api_query

Source: https://jessecambon.github.io/tidygeocoder/reference/get_api_query.html

Constructs a geocoder API query using generic and custom parameters.

```APIDOC
## get_api_query

### Description
Constructs a geocoder API query using universal generic parameters and optional api-specific custom parameters. Generic parameters are converted into API parameters using the api_parameter_reference dataset.

### Parameters
- **method** (string) - Required - The geocoding service name (e.g., 'census', 'osm').
- **generic_parameters** (list) - Optional - Universal generic parameters for the geocoding request.
- **custom_parameters** (list) - Optional - Custom API-specific parameters.

### Request Example
get_api_query("osm", list(address = "Hanoi, Vietnam"))

### Response
- **Returns** (list) - API parameters as a named list.

### Response Example
{
  "q": "Hanoi, Vietnam",
  "format": "json"
}
```

--------------------------------

### Geocode multiple addresses using OSM

Source: https://jessecambon.github.io/tidygeocoder/reference/geo.html

Geocode a vector of addresses using the 'osm' (Nominatim) method. The function returns latitude and longitude for each address.

```R
geo(
  address = c("Tokyo, Japan", "Lima, Peru", "Nairobi, Kenya"),
  method = "osm"
)
```

--------------------------------

### Reverse geocoding with direct inputs

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Use reverse_geo to process vectors of coordinates directly. Setting full_results = TRUE returns comprehensive metadata from the geocoding service.

```R
rev2 <- reverse_geo(
  lat = lat_longs1$latitude,
  long = lat_longs1$longitude,
  method = "osm",
  full_results = TRUE
)

glimpse(rev2)
```

--------------------------------

### Geocode Single Address with Full Results

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Directly geocode a single address string and retrieve full metadata.

```R
salz <- geo("Salzburg, Austria", method = "osm", full_results = TRUE) %>%
  select(-licence)
```

--------------------------------

### Geocode with Nominatim Service

Source: https://jessecambon.github.io/tidygeocoder/articles/tidygeocoder.html

Use the geo() function to geocode addresses via the OpenStreetMap (Nominatim) service.

```R
osm_s1 <- geo(
  address = address_single$singlelineaddress, method = "osm",
  lat = latitude, long = longitude
)
```

--------------------------------

### Combine Multiple Geocoders with Cascade

Source: https://jessecambon.github.io/tidygeocoder/reference/geocode_combine.html

Geocodes addresses using a combination of 'census' and 'osm' methods. The 'cascade = TRUE' parameter ensures that if the first method fails, the next one is attempted.

```R
library(dplyr, warn.conflicts = FALSE)

sample_addresses %>%
  geocode_combine(
    queries = list(list(method = "census"), list(method = "osm")),
    global_params = list(address = "addr"), cascade = TRUE
  )
```

--------------------------------

### Forward Geocoding Functions

Source: https://jessecambon.github.io/tidygeocoder/reference/index.html

Functions used to obtain coordinates from addresses.

```APIDOC
## geocode()

### Description
Geocode addresses in a dataframe.

## geo()

### Description
Geocode addresses.

## geocode_combine()

### Description
Combine multiple geocoding queries for dataframes.

## geo_combine()

### Description
Combine multiple geocoding queries.
```

--------------------------------

### Combine Geocoders with List Output

Source: https://jessecambon.github.io/tidygeocoder/reference/geocode_combine.html

Geocodes addresses using 'census' (batch) and 'arcgis' methods, returning the results as a list. This is useful when you want to keep the results from each geocoder separate.

```R
more_addresses %>%
  geocode_combine(
    queries = list(
      list(
        method = "census", mode = "batch", street = "street_address",
        city = "city", state = "state", postalcode = "zip_cd"
      ),
      list(method = "arcgis", address = "street_address")
    ),
    cascade = FALSE,
    return_list = TRUE
  )
```

--------------------------------

### min_time_reference Dataset

Source: https://jessecambon.github.io/tidygeocoder/reference/min_time_reference.html

The `min_time_reference` dataset contains the minimum time in seconds required per query for different geocoding services to adhere to their usage restrictions. This is used by the `geo` and `reverse_geo` functions.

```APIDOC
## Dataset: min_time_reference

### Description
This dataset specifies the minimum time required per query for each geocoding service to comply with their usage restrictions. It is utilized by the `geo` and `reverse_geo` functions in the tidygeocoder package.

### Format
A tibble dataframe with the following columns:

- **method** (character): The name of the geocoding service.
- **min_time** (numeric): The minimum number of seconds required between consecutive queries to a service.
- **description** (character): A brief explanation of the usage rate restriction for the service.

### Details
Links to the usage policies for each geocoding service are provided:

* Nominatim
* US Census
* ArcGIS
* Geocodio
* Location IQ
* Google
* OpenCage
* Mapbox
* HERE
* TomTom
* MapQuest
* Bing
* Geoapify

### See also
`geo`, `reverse_geo`
```

--------------------------------

### Define get_api_query function signature

Source: https://jessecambon.github.io/tidygeocoder/reference/get_api_query.html

The function signature for constructing a geocoder API query.

```R
get_api_query(method, generic_parameters = list(), custom_parameters = list())
```

--------------------------------

### Geocode Addresses using Census with Full Results

Source: https://jessecambon.github.io/tidygeocoder/reference/geocode.html

Geocodes addresses using the US Census batch geocoder, returning full results. Specify street, city, state, and postal code. Requires the 'census' method and 'full_results = TRUE'.

```R
louisville %>%
  head(2) %>%
  geocode(
    street = street, city = city, state = state,
    postalcode = zip, method = "census", full_results = TRUE
  )
```
Tokens:
Raw