### Install tidygeocoder from GitHub

Source: https://github.com/jessecambon/tidygeocoder/blob/main/README.md

Use this command to install the latest development version of the package directly from GitHub.

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

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

### Data

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/index.html

Sample datasets for testing and examples.

```APIDOC
## Data

### Description
Sample datasets for testing and examples.

### Datasets
- `louisville`: Louisville, Kentucky street addresses.
- `sample_addresses`: Sample addresses for testing.
```

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

### Construct geocoder API queries

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/get_api_query.html

Examples of generating API parameter lists for different geocoding services.

```R
get_api_query("osm", list(address = "Hanoi, Vietnam"))
```

```R
get_api_query(
  "census", list(street = "11 Wall St", city = "NY", state = "NY"),
  list(benchmark = "Public_AR_Census2010")
)
```

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

### Geocoding with multiple methods

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geo_combine.html

Examples demonstrating how to use geo_combine with different geocoding methods and configurations.

```R
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")
)
```

```R
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
)
```

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

### Install tidygeocoder from CRAN

Source: https://github.com/jessecambon/tidygeocoder/blob/main/README.md

Use this command to install the stable version of the package from the official R package servers.

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

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

### Perform reverse geocoding with tidygeocoder

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/reverse_geo.html

Examples demonstrating single and batch coordinate reverse geocoding using the OSM method.

```R
options(tidygeocoder.progress_bar = FALSE)

reverse_geo(lat = 38.895865, long = -77.0307713, method = "osm")

reverse_geo(
  lat = c(38.895865, 43.6534817, 300),
  long = c(-77.0307713, -79.3839347, 600),
  method = "osm", full_results = TRUE
)
```

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

### Geocode addresses examples

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geocode.html

Demonstrates geocoding using single-line addresses and component-based address columns with different geocoding services.

```R
# \donttest{
library(dplyr, warn.conflicts = FALSE)
sample_addresses %>%
  slice(1:2) %>%
  geocode(addr, method = "arcgis")
#> Passing 2 addresses to the ArcGIS single address geocoder
#> Query completed in: 1.1 seconds
#> # A tibble: 2 × 4
#>   name                 addr                                         lat   long
#>   <chr>                <chr>                                      <dbl>  <dbl>
#> 1 White House          1600 Pennsylvania Ave NW Washington, DC     38.9  -77.0
#> 2 Transamerica Pyramid 600 Montgomery St, San Francisco, CA 94111  37.8 -122. 

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

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

### Geocode addresses using tidygeocoder

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geo.html

Examples of using the geo() function with different geocoding methods and parameters.

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

geo(
  street = "600 Peachtree Street NE", city = "Atlanta",
  state = "Georgia", method = "census"
)
#> Passing 1 address to the US Census single address geocoder
#> Query completed in: 0.4 seconds
#> # A tibble: 1 × 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"
)
#> Passing 3 addresses to the Nominatim single address geocoder
#> Query completed in: 3 seconds
#> # A tibble: 3 × 3
#>   address           lat  long
#>   <chr>           <dbl> <dbl>
#> 1 Tokyo, Japan    35.7  140. 
#> 2 Lima, Peru     -12.1  -77.0
#> 3 Nairobi, Kenya  -1.30  36.8

geo("100 Main St New York, NY",
  full_results = TRUE,
  method = "census", api_options = list(census_return_type = "geographies")
)
#> Passing 1 address to the US Census single address geocoder
#> Query completed in: 0.2 seconds
#> # A tibble: 1 × 29
#>   address          lat  long matchedAddress tigerLine.side tigerLine.tigerLineId
#>   <chr>          <dbl> <dbl> <chr>          <chr>          <chr>                
#> 1 100 Main St N…  40.7 -74.0 100 MAIN ST, … R              59662602             
#> # ℹ 23 more variables: geographies.States <list>,
#> #   `geographies.Combined Statistical Areas` <list>,
#> #   `geographies.County Subdivisions` <list>, `geographies.Urban Areas` <list>,
#> #   `geographies.Incorporated Places` <list>, geographies.Counties <list>,
#> #   `geographies.2024 State Legislative Districts - Upper` <list>,
#> #   `geographies.2024 State Legislative Districts - Lower` <list>,
#> #   `geographies.2020 Census Blocks` <list>, …

geo(
  county = "Jefferson", state = "Kentucky", country = "US",
  method = "osm"
)
#> Passing 1 address to the Nominatim single address geocoder
#> Query completed in: 1 seconds
#> # A tibble: 1 × 5
#>   county    state    country   lat  long
#>   <chr>     <chr>    <chr>   <dbl> <dbl>
#> 1 Jefferson Kentucky US       38.2 -85.7
# }
```

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

### Combine Multiple Geocoding Methods

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geocode_combine.html

This example shows how to use `geocode_combine` to geocode a dataset of addresses using multiple methods (census batch, census single, and OSM) and query names. It demonstrates how to specify global parameters for address components.

```r
more_addresses <- tibble::tribble(
  ~street_address, ~city, ~state, ~zip_cd,
  "624 W DAVIS ST #1D", "BURLINGTON", "NC", 27215,
  "201 E CENTER ST #268", "MEBANE", "NC", 27302,
  "100 Wall Street", "New York", "NY", 10005,
  "Bucharest", NA, NA, NA
)

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 a single address using OpenStreetMap

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/query_api.html

This example demonstrates geocoding a single address ('Hanoi, Vietnam') using the OpenStreetMap Nominatim API. It shows how to use get_api_query to format the request and then extract the results.

```R
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))
```

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

### GET api_info_reference

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/api_info_reference.html

Retrieves the reference dataset containing information about supported geocoding services.

```APIDOC
## GET api_info_reference

### Description
Returns a tibble dataframe containing metadata for geocoding services, including display names, official site URLs, and API documentation links.

### Method
GET

### Endpoint
api_info_reference

### Response
#### Success Response (200)
- **method** (string) - Geocoding service name
- **method_display_name** (string) - Geocoding service display name
- **site_url** (string) - Link to the main site of the geocoding service
- **api_documentation_url** (string) - Link to API documentation
- **api_usage_policy_url** (string) - Link to the usage policy
```

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

### Combine Geocoding Methods with Cascade and List Output

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geocode_combine.html

This example demonstrates `geocode_combine` with `cascade = FALSE` and `return_list = TRUE`. It uses different geocoding methods (census batch and ArcGIS) and specifies parameters directly within the query list. The output is returned as a list of data frames.

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

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

### Reverse geocode coordinates using OpenStreetMap

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/query_api.html

This example shows how to perform a reverse geocoding query for specific latitude and longitude coordinates using the OpenStreetMap Nominatim API. It utilizes get_api_query for request formatting and extract_reverse_results for parsing the response.

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

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

### Combine Geocoding Services Without Cascade

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

Use geocode_combine with cascade = FALSE to get results from multiple services for comparison. Set return_list = TRUE to receive separate results for each service.

```r
results <- addresses %>%
  geocode_combine(
    queries = list(
      list(method = "arcgis"),
      list(method = "osm")
    ),
    global_params = list(address = "address"),
    cascade = FALSE,
    return_list = TRUE  # Return separate results per service
  )
```

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

### Geocode Addresses with tidygeocoder

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/index.html

Geocode a list of addresses using the 'osm' method and store the results in a tibble. This example uses dplyr for data manipulation and tidygeocoder for geocoding.

```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"                                  
)

# geocode the addresses
lat_longs <- some_addresses %>%
  geocode(addr, method = 'osm', lat = latitude , long = longitude)
#> Passing 3 addresses to the Nominatim single address geocoder
#> Query completed in: 3.2 seconds
```

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

### Specify Custom API Parameters with custom_query

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Use the `custom_query` parameter to pass specific API arguments to the geocoding service. This example shows how to enable GeoJSON geometry output from Nominatim.

```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

```

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

### Combine Geocoding Methods in R

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geo_combine.html

Demonstrates how to use `geo_combine` to get geocoding results from multiple methods (ArcGIS and OSM) for a list of cities and countries. The `cascade = FALSE` argument ensures that all queries are run, regardless of whether a previous query succeeded.

```r
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
)
```

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

### Reverse geocode coordinates using ArcGIS

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/reverse_geocode.html

This example demonstrates reverse geocoding using the ArcGIS service. It takes a dataframe with latitude and longitude and returns address information. Ensure the input data is prepared correctly, and specify the desired geocoding method.

```R
louisville %>%
  head(3) %>%
  reverse_geocode(
    lat = latitude, long = longitude,
    method = "arcgis"
  )
```

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

### Geocode Single Address with OSM

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Geocodes a single address string using the OpenStreetMap (Nominatim) service. Use `full_results = TRUE` to get all returned fields and pipe the output to `select()` to remove unwanted columns like 'licence'.

```r
salz <- geo("Salzburg, Austria", method = "osm", full_results = TRUE) %>%
  select(-licence)
#> Passing 1 address to the Nominatim single address geocoder
#> Query completed in: 1 seconds
```

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

### Execute Raw Geocoding API Queries

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

The query_api function sends HTTP requests to geocoding services, supporting GET and POST requests for single or batch queries. It's a low-level function for custom workflows. Results require parsing.

```r
library(tidygeocoder)

# Execute a raw API query to Nominatim
raw_result <- query_api(
  "https://nominatim.openstreetmap.org/search",
  get_api_query("osm", list(address = "Hanoi, Vietnam"))
)

# Check HTTP status
raw_result$status
# [1] 200

# Parse the JSON response
parsed <- jsonlite::fromJSON(raw_result$content)

# Extract results using tidygeocoder's parser
results <- extract_results("osm", parsed)
# Returns tibble with lat, long, and other fields
```

```r
# Reverse geocoding query
raw_reverse <- query_api(
  "https://nominatim.openstreetmap.org/reverse",
  get_api_query("osm", custom_parameters = list(lat = 38.895865, lon = -77.0307713))
)

reverse_results <- extract_reverse_results("osm", jsonlite::fromJSON(raw_reverse$content))
# Returns tibble with address and other fields
```

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

### Reverse geocode coordinates using OSM

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/reverse_geocode.html

Use this function to convert coordinates to addresses. It requires latitude and longitude columns and can utilize various geocoding services like OSM. Set `full_results = TRUE` to get all available address details.

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

tibble(
  latitude = c(38.895865, 43.6534817),
  longitude = c(-77.0307713, -79.3839347)
) %>%
  reverse_geocode(
    lat = latitude,
    long = longitude,
    method = "osm",
    full_results = TRUE
  )
```

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

### Initialize DocSearch

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/adding_geocoder_services.html

Configures the DocSearch integration for the documentation site.

```javascript
docsearch({ apiKey: '2a4961d1f7b45ceee241419b8e8257d3', indexName: 'tidygeocoder', inputSelector: 'input#search-input.form-control', transformData: function(hits) { return hits.map(function (hit) { hit.url = updateHitURL(hit); return hit; }); } });
```

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

### Configure Geocoding Parameters and Rate Limits

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

Demonstrates how to inspect service limits and customize geocoding behavior, including overriding rate limits, forcing single-address mode, and using local servers.

```r
library(tidygeocoder)

# View minimum time between queries for each service
tidygeocoder::min_time_reference
# | method   | min_time | description                    |
# |----------|----------|--------------------------------|
# | osm      | 1        | 1 query per second             |
# | census   | 0        | no limit                       |
# | geocodio | 0        | no limit with API key          |

# View batch limits
tidygeocoder::batch_limit_reference
# | method   | batch_limit |
# |----------|-------------|
# | census   | 10000       |
# | geocodio | 10000       |
# | here     | 10000       |

# Control geocoding behavior
results <- geo(
  address = addresses,
  method = "osm",
  mode = "single",          # Force single-address mode (no batch)
  min_time = 2,             # Override default rate limit (2 sec between queries)
  progress_bar = TRUE,      # Show progress for single-mode queries
  verbose = TRUE,           # Display detailed query information
  quiet = FALSE             # Show query completion messages
)

# Use a local Nominatim server (no rate limits)
results <- geo(
  address = "123 Main St",
  method = "osm",
  api_url = "http://localhost:8080/search"  # Local Nominatim instance
)

# Set batch limit manually
results <- geo(
  address = large_address_list,
  method = "geocodio",
  batch_limit = 5000  # Override default batch limit
)
```

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

### GET /reverse_geo

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/reverse_geo.html

Performs reverse geocoding to convert latitude and longitude coordinates into addresses.

```APIDOC
## GET /reverse_geo

### Description
Converts latitude and longitude coordinates into address information using specified geocoding methods.

### 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.
```

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

### Geocode Using Sample Datasets

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

Shows how to access and geocode the built-in sample_addresses and louisville datasets provided by the package.

```r
library(tidygeocoder)
library(dplyr)

# View sample single-line addresses
tidygeocoder::sample_addresses
# | name                                | addr                                      |
# |-------------------------------------|-------------------------------------------|
# | White House                         | 1600 Pennsylvania Ave NW Washington, DC   |
# | Transamerica Pyramid                | 600 Montgomery St, San Francisco, CA 94111|
# | Empire State Building               |
350 Fifth Avenue New York, NY 10118  |

# Use sample addresses for testing
sample_addresses %>%
  slice(1:3) %>%
  geocode(addr, method = "osm")

# Louisville component addresses dataset
tidygeocoder::louisville
# | street                | city       | state | zip   | latitude  | longitude  |
# |-----------------------|------------|-------|-------|-----------|------------|
# | 525 W SAINT CATHERINE | Louisville | KY    | 40203 | 38.24354  | -85.76545  |

# Geocode Louisville addresses
louisville %>%
  head(5) %>%
  geocode(
    street = street,
    city = city,
    state = state,
    postalcode = zip,
    method = "census"
  )
```

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

### Release and Maintenance Commands

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/developer_notes.html

Utility functions for building documentation, checking URLs, verifying spelling, and initiating the release process.

```R
pkgdown::build_site()
```

```R
urlchecker::url_check()
```

```R
devtools::spell_check()
```

```R
devtools::release()
```

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

### Get Unique Geocoding Results

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Use `unique_only = TRUE` to retrieve only unique geocoding results. Note that this will discard the original dataframe format in favor of standard field names.

```R
uniqueonly1 <- duplicate_addrs %>%
  geocode(singlelineaddress, unique_only = TRUE)
#> Passing 2 addresses to the Nominatim single address geocoder
#> Query completed in: 2 seconds
```

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

### Manage Geocoding API Keys

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

API keys for commercial services are loaded from environment variables, specified in api_key_reference. Set keys using Sys.setenv() for a session or in .Renviron for persistence.

```r
library(tidygeocoder)

# View which environment variable each service uses
tidygeocoder::api_key_reference
# | 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       |
```

```r
# Set API key for a session
Sys.setenv(GEOCODIO_API_KEY = "your_api_key_here")

# Or permanently in .Renviron (recommended)
# Run: usethis::edit_r_environ()
# Add: GEOCODIO_API_KEY=your_api_key_here
```

```r
# Use a commercial service
results <- geo("1600 Pennsylvania Ave, Washington DC", method = "geocodio")
```

```r
# Geocodio HIPAA-compliant endpoint for healthcare data
results <- geo(
  "patient address here",
  method = "geocodio",
  api_options = list(geocodio_hipaa = TRUE)
)
```

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

### Prepare address data for geocoding

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Create tibbles containing addresses, either as single-line strings or separated into components like street, city, and state.

```r
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"
)
```

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

### Use Locally Hosted Nominatim Service

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/geocoder_services.html

Connect to a locally hosted Nominatim service by specifying its address using the `api_url` parameter. This is useful for maintaining data privacy.

```R
tidygeocoder::geo(address = "New York, USA", method = "osm", api_url = "http://localhost:8080")
```

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

### Get Full Geocoding Results with Census

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Retrieves full geocoding results, including geographic information like Census tracts and blocks, by setting `full_results = TRUE` and specifying `census_return_type = 'geographies'` in `api_options`.

```r
census_full1 <- address_single %>% geocode(
  address = singlelineaddress,
  method = "census", full_results = TRUE, api_options = list(census_return_type = 'geographies')
)
#> Passing 2 addresses to the US Census batch geocoder
#> Query completed in: 0.2 seconds
```

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

### Utility Functions

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/index.html

Helper functions for constructing and executing API queries, and extracting results.

```APIDOC
## Utility Functions

### Description
Helper functions for constructing and executing API queries, and extracting results.

### Functions
- `get_api_query()`: Construct a geocoder API query.
- `query_api()`: Execute a geocoder API query.
- `extract_results()`: Extract forward geocoding results.
- `extract_reverse_results()`: Extract reverse geocoding results.
```

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

### Run Package Checks and Tests

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/developer_notes.html

Commands for validating package integrity and running offline tests.

```R
devtools::check()
```

```R
devtools::test()
```

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

### Geocode addresses with components and full results

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

Demonstrates geocoding using specific address components or full address strings with the US Census method.

```r
result <- geo(
  street = "600 Peachtree Street NE",
  city = "Atlanta",
  state = "Georgia",
  method = "census"
)
```

```r
result <- geo(
  "100 Main St New York, NY",
  full_results = TRUE,
  method = "census",
  api_options = list(census_return_type = "geographies")
)
```

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

### Cite the tidygeocoder package

Source: https://github.com/jessecambon/tidygeocoder/blob/main/README.md

Use this function to retrieve the appropriate citation information for the package within an R session.

```r
citation('tidygeocoder')
```

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

### Load tidygeocoder and other libraries

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Before geocoding, load the necessary libraries: tibble for data frames, dplyr for data manipulation, and tidygeocoder for geocoding functions.

```r
library(tibble)
library(dplyr)
library(tidygeocoder)
```

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

### API Parameter Reference Overview

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/api_parameter_reference.html

This section outlines the structure and purpose of the `api_parameter_reference` dataset, which maps generic geocoding parameters to service-specific API parameter names.

```APIDOC
## API Parameter Reference Overview

### Description
This dataset contains the mapping that allows the tidygeocoder package to use a universal syntax to specify parameters for different geocoding services. It details the `generic_name` (universal parameter name) and `api_name` (parameter name for a specific geocoding service) for each method.

### Format
A tibble dataframe

### Columns
- **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** (string): Indicates if the parameter is required by the specified geocoding service.

### Notes
- Latitude and longitude input parameters for reverse geocoding are handled directly by the `reverse_geo` function and are not in this dataset.
- When `generic_name` is missing, the parameter is specific to that geocoding service.
- The `limit` argument is supported as a passthrough for services like 'census' and 'google' even if not directly in their APIs, to control the number of results per input.
- Some services only use the `limit` argument for forward geocoding. Refer to individual service API documentation for details.

### Supported Geocoding Services and API Documentation Links
- **Nominatim**: [https://nominatim.org/release-docs/develop/api/Search/](https://nominatim.org/release-docs/develop/api/Search/)
- **US Census**: [https://www.census.gov/programs-surveys/geography/technical-documentation/complete-technical-documentation/census-geocoder.html](https://www.census.gov/programs-surveys/geography/technical-documentation/complete-technical-documentation/census-geocoder.html)
- **ArcGIS**: [https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm](https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm)
- **Geocodio**: [https://www.geocod.io/docs/](https://www.geocod.io/docs/)
- **Location IQ**: [https://docs.locationiq.com/docs/introduction](https://docs.locationiq.com/docs/introduction)
- **Google**: [https://developers.google.com/maps/documentation/geocoding/overview](https://developers.google.com/maps/documentation/geocoding/overview)
- **OpenCage**: [https://opencagedata.com/api](https://opencagedata.com/api)
- **Mapbox**: [https://docs.mapbox.com/api/search/geocoding/](https://docs.mapbox.com/api/search/geocoding/)
- **HERE**: [https://www.here.com/docs/bundle/geocoding-and-search-api-developer-guide/page/README.html](https://www.here.com/docs/bundle/geocoding-and-search-api-developer-guide/page/README.html)
- **TomTom**: [https://developer.tomtom.com/search-api/search-api-documentation](https://developer.tomtom.com/search-api/search-api-documentation)
- **MapQuest**: [https://developer.mapquest.com/documentation/api/geocoding](https://developer.mapquest.com/documentation/api/geocoding)
- **Bing**: [https://learn.microsoft.com/en-us/bingmaps/rest-services/locations/](https://learn.microsoft.com/en-us/bingmaps/rest-services/locations/)
- **Geoapify**: [https://apidocs.geoapify.com/docs/geocoding/api/](https://apidocs.geoapify.com/docs/geocoding/api/)
```

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

### Construct Geocoding API Query Parameters

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

Use get_api_query to build service-specific API parameters from generic ones. This is useful for debugging or understanding query structures. Custom parameters can be included.

```r
library(tidygeocoder)

# Create OSM query parameters
osm_params <- get_api_query("osm", list(address = "Hanoi, Vietnam"))
# Returns:
# $q
# [1] "Hanoi, Vietnam"
# $format
# [1] "json"
# $limit
# [1] "1"
```

```r
# Create Census query with address components
census_params <- get_api_query(
  "census",
  list(street = "11 Wall St", city = "NY", state = "NY"),
  list(benchmark = "Public_AR_Census2010")  # Custom parameter
)
# Returns service-specific parameter names for the Census API
```

```r
# View the full API parameter mapping
tidygeocoder::api_parameter_reference
# Shows how generic parameters map to each service's API parameters
```

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

### Geocode addresses with tidygeocoder

Source: https://github.com/jessecambon/tidygeocoder/blob/main/README.md

Load the necessary libraries and create a tibble of addresses to prepare for geocoding.

```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"                                  
)
```

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

### Geocode addresses using OSM

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geocode.html

Uses the Nominatim (OSM) service to geocode a subset of addresses, returning full results.

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

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

### Forward geocode using OSM service with geo() function

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Alternatively, use the `geo()` function to geocode addresses by passing the address vector directly. Specify the geocoding service using the `method` argument (e.g., 'osm'). You can also rename the output latitude and longitude columns using `lat` and `long` arguments.

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

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

### Geocoding Service Configuration

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geo.html

Supported geocoding services and their respective environment variable requirements for API keys.

```APIDOC
## Supported Geocoding Services

### Description
List of supported geocoding services and the required environment variables for authentication.

### Services
- **tomtom**: Requires `TOMTOM_API_KEY` environment variable. Supports batch geocoding.
- **mapquest**: Requires `MAPQUEST_API_KEY` environment variable. Supports batch geocoding.
- **bing**: Requires `BINGMAPS_API_KEY` environment variable. Supports batch geocoding (requires `mode = "batch"`).
- **geoapify**: Requires `GEOAPIFY_KEY` environment variable.
```

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

### POST/GET query_api

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/query_api.html

Executes a geocoding API query against a specified base URL with custom parameters.

```APIDOC
## query_api

### Description
Executes a geocoder API query. This function is designed to be used in conjunction with get_api_query to construct and send requests to geocoding services.

### Parameters
- **api_url** (string) - Required - Base URL of the API.
- **query_parameters** (list) - Required - API query parameters in the form of a named list.
- **mode** (string) - Optional - Determines the type of query: 'single' (default), 'list', or 'file'.
- **batch_file** (string) - Optional - A CSV file path for batch geocoding when mode is 'file'.
- **input_list** (list) - Optional - A list of input data for batch geocoding when mode is 'list'.
- **content_encoding** (string) - Optional - Encoding to be used for parsing content (default 'UTF-8').
- **timeout** (numeric) - Optional - Timeout in minutes (default 20).
- **method** (string) - Optional - Specifies the service (e.g., 'mapquest' or 'arcgis') to adjust status code handling.

### Response
- **content** (string) - The response body content.
- **status** (integer) - The HTTP request status code.

### Request Example
query_api(
  "http://nominatim.openstreetmap.org/search",
  get_api_query("osm", list(address = "Hanoi, Vietnam"))
)
```

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

### Geocoding with Duplicate and NA Addresses

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

This code snippet creates a dataset with duplicate and NA addresses and then uses the geocode function with verbose output to show how these are handled. It demonstrates that only unique, non-NA addresses are passed to the geocoding service.

```R
duplicate_addrs <- address_single %>%
  bind_rows(address_single) %>%
  bind_rows(tibble(singlelineaddress = rep(NA, 3)))

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

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

### Geocode with Multiple Results Per Address

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Use the `limit` argument in `geo()` to retrieve multiple results per input address if available. The `full_results = TRUE` argument ensures all columns from the geocoding service are returned.

```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 with OSM

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/developer_notes.html

Demonstrates the geocode function processing a dataframe with duplicate locations using the OpenStreetMap service.

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

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

### Combine Multiple Geocoding Queries (Cascade)

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Use `geocode_combine()` to execute and merge results from multiple geocoding services. By default, only addresses not found in a previous query are passed to the next (`cascade = TRUE`).

```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')
  )
#> 
#> Passing 3 addresses to the US Census batch geocoder
#> Query completed in: 0.2 seconds
#> Passing 3 addresses to the Nominatim single address geocoder
#> Query completed in: 3 seconds
```

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

### Combine Multiple Geocoding Queries (No Cascade)

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/tidygeocoder.html

Set `cascade = FALSE` in `geocode_combine()` to attempt all addresses with each query, regardless of whether they were found previously.

```R
no_cascade_results1 <- addresses_combine %>%
  geocode_combine(
    queries = list(
      list(method = 'census'),
      list(method = 'osm')
    ),
    global_params = list(address = 'address'),
    cascade = FALSE
  )
#> 
#> Passing 3 addresses to the US Census batch geocoder
#> Query completed in: 0.2 seconds
#> Passing 3 addresses to the Nominatim single address geocoder
#> Query completed in: 3 seconds
```

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

### Construct Geocoder API Query

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/get_api_query.html

The `get_api_query` function constructs a geocoder API query. It uses universal 'generic' parameters and optional api-specific 'custom' parameters. Generic parameters are converted into API parameters using the `api_parameter_reference` dataset. The `query_api` function executes the queries created by this function.

```APIDOC
## GET /api/query

### Description
Constructs a geocoder API query using generic and custom parameters.

### Method
GET (Implicit, as it constructs a query to be executed later)

### Endpoint
N/A (This function constructs a query, it does not represent an endpoint itself)

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

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

### Response
#### Success Response (200)
- **API parameters** (named list) - A list containing the constructed API parameters.

#### Response Example
```R
# Example 1 Output:
list(
  q = "Hanoi, Vietnam",
  format = "json"
)

# Example 2 Output:
list(
  street = "11 Wall St",
  city = "NY",
  state = "NY",
  benchmark = "Public_AR_Census2010",
  format = "json",
  vintage = "Current_Current"
)
```

### See Also
- [query_api](query_api.html)
- [api_parameter_reference](api_parameter_reference.html)
- [geo](geo.html)
- [reverse_geo](reverse_geo.html)
```

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

### Environment Variables for Geocoding Services

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/geocoder_services.html

This section lists the environment variables required to authenticate with different geocoding services supported by Tidygeocoder.

```APIDOC
## Environment Variables

This API utilizes environment variables to store authentication keys for various geocoding services. Ensure the appropriate variable is set for the service you intend to use.

### Supported Services and Environment Variables:

- **Geocodio**: `GEOCODIO_API_KEY`
- **LocationIQ**: `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 Maps**: `BINGMAPS_API_KEY`
- **Geoapify**: `GEOAPIFY_KEY`
```

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

### Execute a geocoder API query

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/query_api.html

Use query_api to send requests to a geocoding service. Ensure you have the correct API URL and query parameters. The function returns the raw API response content and the HTTP status.

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

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

### Reference Datasets

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/index.html

Datasets used for geocoding queries and documentation.

```APIDOC
## Reference Datasets

### Description
Datasets used for geocoding queries and documentation.

### Datasets
- `api_parameter_reference`: Geocoding service API parameter reference.
- `min_time_reference`: Minimum time required per query.
- `batch_limit_reference`: Geocoding batch size limits.
- `api_key_reference`: API key environmental variables.
- `api_info_reference`: Geocoding service links and information.
```

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

### Minimum Time Per Query

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/geocoder_services.html

Information regarding the minimum time required between queries to adhere to the usage policies of geocoding services.

```APIDOC
## Minimum Time Per Query

The `min_time_reference` dataset stores the minimum time in seconds required per query to comply with the usage limitations policies of each geocoding service. Refer to the [min_time_reference reference](../reference/min_time_reference.html) for detailed information.
```

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

### Geocoding Query Parameters

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/reference/geo.html

Common parameters used to control geocoding queries, batch processing, and result formatting.

```APIDOC
## Geocoding Query Parameters

### Parameters
- **lat** (string) - Optional - Latitude column name.
- **long** (string) - Optional - Longitude column name.
- **limit** (integer) - Optional - Maximum number of results per input address.
- **full_results** (boolean) - Optional - If TRUE, returns all available data from the service.
- **mode** (string) - Optional - Set to 'batch' or 'single' to force geocoding mode.
- **unique_only** (boolean) - Optional - Only return results for unique inputs if TRUE.
- **return_addresses** (boolean) - Optional - Return input addresses with results if TRUE.
- **min_time** (numeric) - Optional - Minimum time in seconds for a query to take.
- **progress_bar** (boolean) - Optional - Display progress bar for single input geocoding.
- **quiet** (boolean) - Optional - Suppress console messages if TRUE.
- **api_url** (string) - Optional - Custom API URL to override default.
- **timeout** (numeric) - Optional - Query timeout in minutes.
- **flatten** (boolean) - Optional - Flatten nested dataframes if TRUE.
- **batch_limit** (integer) - Optional - Limit to the number of addresses in a batch query.
- **verbose** (boolean) - Optional - Output detailed logs if TRUE.
- **no_query** (boolean) - Optional - If TRUE, no queries are sent (used for testing).
- **custom_query** (list) - Optional - API-specific parameters passed as a named list.
- **api_options** (list) - Optional - Named list of service-specific parameters.
```

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

### Combine geocoding services

Source: https://context7.com/jessecambon/tidygeocoder/llms.txt

Executes multiple geocoding queries sequentially using cascade mode to maximize success rates.

```r
library(tidygeocoder)
library(dplyr)

# Addresses with varying geocodability
addresses <- tibble(
  address = c("100 Wall Street NY, NY", "Paris", "Not A Real Address")
)

# Cascade through Census then OSM - only unfound addresses go to next service
results <- addresses %>%
  geocode_combine(
    queries = list(
      list(method = "census"),
      list(method = "osm")
    ),
    global_params = list(address = "address")
  )
```

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

### Include API Key for ArcGIS Service

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/geocoder_services.html

An API Key can be included for the ArcGIS service using the `custom_query` parameter with the key `token`.

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

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

### Enable HIPAA Compliant Geocoding with Geocodio

Source: https://github.com/jessecambon/tidygeocoder/blob/main/docs/articles/geocoder_services.html

To use the HIPAA compliant API offered by Geocodio, set the `geocodio_hipaa` option to TRUE within the `api_options` parameter.

```R
tidygeocoder::geo(address = "New York, USA", method = "geocodio", api_options = list(geocodio_hipaa = TRUE))
```