---
title: "Get started with arcgeocoder"
description: Quick examples showing what arcgeocoder can do for you.
vignette: >
  %\VignetteIndexEntry{Get started with arcgeocoder}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
bibliography: REFERENCES.bib
link-citations: true
tbl-cap-location: bottom
---

<!-- arcgeocoder.qmd is generated from arcgeocoder.qmd.orig. Please edit that file -->



The goal of **arcgeocoder** is to provide a lightweight interface for
geocoding addresses and reverse geocoding coordinates through the
[ArcGIS REST API geocoding service](https://developers.arcgis.com/rest/geocode/api-reference/overview-world-geocoding-service.htm).

The full site with examples and vignettes is available at
<https://dieghernan.github.io/arcgeocoder/>.

## Why arcgeocoder?

**arcgeocoder** provides a lightweight interface for geocoding and reverse
geocoding with the ArcGIS REST API service. It accesses the API without
depending on additional HTTP packages such as **curl**. In some situations,
**curl** may not be available or accessible, so **arcgeocoder** uses base
functions to avoid this limitation.

The interface of **arcgeocoder** is designed to make ArcGIS geocoding features
easier to access. The API endpoints used by **arcgeocoder** are
`findAddressCandidates` and `reverseGeocode`, which can be accessed without an
API key.

## Recommended packages

Other packages are more mature and provide similar features:

- [**tidygeocoder**](https://jessecambon.github.io/tidygeocoder/)
  [@R-tidygeocoder] provides an interface to ArcGIS, Nominatim
  (OpenStreetMap), Google, TomTom, Mapbox and other services for geocoding and
  reverse geocoding.
- [**nominatimlite**](https://dieghernan.github.io/nominatimlite/)
  [@R-nominatimlite] is similar to **arcgeocoder** but uses data from
  OpenStreetMap through the [Nominatim
  API](https://nominatim.org/release-docs/latest/) service.

## Usage

### Geocoding and reverse geocoding

*Note: examples adapted from the **tidygeocoder** package.*

In this first example, we geocode a few addresses using the `arc_geo()`
function. Note that **arcgeocoder** works without additional setup, and you do
not need to provide an API key to start geocoding.


``` r
library(arcgeocoder)
library(dplyr)

# Create a data frame with addresses.
some_addresses <- 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 <- arc_geo(
  some_addresses$addr,
  lat = "latitude",
  long = "longitude",
  progressbar = FALSE
)
```

Only a few fields are returned from the geocoding service in this example, but
`full_results = TRUE` can be used to return all data from the service.

::: {#tbl-geo}


|query                                      | latitude|  longitude|address                                                           | score|          x|        y|       xmin|     ymin|       xmax|     ymax| wkid| latestWkid|
|:------------------------------------------|--------:|----------:|:-----------------------------------------------------------------|-----:|----------:|--------:|----------:|--------:|----------:|--------:|----:|----------:|
|1600 Pennsylvania Ave NW, Washington, DC   | 38.89768|  -77.03655|1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500 |   100|  -77.03655| 38.89768|  -77.03755| 38.89668|  -77.03555| 38.89868| 4326|       4326|
|600 Montgomery St, San Francisco, CA 94111 | 37.79516| -122.40273|600 Montgomery St, San Francisco, California, 94111               |   100| -122.40273| 37.79516| -122.40373| 37.79416| -122.40173| 37.79616| 4326|       4326|
|233 S Wacker Dr, Chicago, IL 60606         | 41.87867|  -87.63587|233 S Wacker Dr, Chicago, Illinois, 60606                         |   100|  -87.63587| 41.87867|  -87.63687| 41.87767|  -87.63487| 41.87967| 4326|       4326|



Example: geocoding addresses
:::

To perform reverse geocoding (obtaining addresses from geographic coordinates),
we can use the `arc_reverse_geo()` function. The arguments are similar to those
in `arc_geo()`, but now we specify the input data columns with the `x` and `y`
arguments. The data used here comes from the geocoding query above. The
single-line address is returned in the column named by `address`.


``` r
reverse <- arc_reverse_geo(
  x = lat_longs$longitude,
  y = lat_longs$latitude,
  address = "address_found",
  progressbar = FALSE
)
```

::: {#tbl-reverse}


|          x|        y|address_found                                                     |
|----------:|--------:|:-----------------------------------------------------------------|
|  -77.03655| 38.89768|White House, 1600 Pennsylvania Ave NW, Washington, DC, 20500, USA |
| -122.40273| 37.79516|Chess Ventures, 600 Montgomery St, San Francisco, CA, 94111, USA  |
|  -87.63587| 41.87867|The Metropolitan, 233 South Wacker Drive, Chicago, IL, 60606, USA |



Example: reverse geocoding addresses.
:::

It is also possible to search for specific locations within or near a reference
area or location using [category
filtering](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-category-filtering.htm).
See the documentation for the `arc_categories` data object for more
information.

In the following example, we look for food-related points of interest (POIs),
such as restaurants, coffee shops and bakeries, near the Eiffel Tower in France.


``` r
library(ggplot2) # For plotting.

# Step 1: Locate the Eiffel Tower using a multi-field query.

eiffel_tower <- arc_geo_multi(
  address = "Tour Eiffel",
  city = "Paris",
  countrycode = "FR",
  langcode = "FR",
  custom_query = list(outFields = "LongLabel")
)

# Display results.
eiffel_tower |>
  select(lon, lat, LongLabel)
#> # A tibble: 1 × 3
#>     lon   lat LongLabel                                                          
#>   <dbl> <dbl> <chr>                                                              
#> 1  2.29  48.9 Tour Eiffel, 3 Rue de l'Université, 75007, 7e Arrondissement, Pari…

# Use `lon` and `lat` as a reference location for `category = "Food"`.
food_eiffel <- arc_geo_categories(
  "Food",
  x = eiffel_tower$lon,
  y = eiffel_tower$lat,
  limit = 50,
  full_results = TRUE
)

# Plot by food type.
ggplot(eiffel_tower, aes(x, y)) +
  geom_point(shape = 17, color = "red", size = 4) +
  geom_point(data = food_eiffel, aes(x, y, color = Type)) +
  labs(
    title = "Food near the Eiffel Tower",
    subtitle = "Using arcgeocoder",
    color = "Type of place",
    x = "",
    y = "",
    caption = "Data from the ArcGIS REST API service"
  )
```

![Example: Food places near the Eiffel Tower](./eiffel-1.png)

## References
