Geocoding

library(AOI)

Geocoding is the act of converting a named entity to a spatial representation. AOI uses the tidygeocoder package for geocoding and overlays some basic syntax to return optional representations.

The tidygeocoder package provides a range of services (see ?tidygeocoder::geo mehtods). You are free to chose your own with the method argument. The default method for the package is arcgis.

(AOI:::default_method)
#> [1] "arcgis"

Basic Usage

The default AOI::geocode behavior returns adata.frame with a “request” named after the input geo, and an x, y column along with the {method}_address and score.

geocode("Fort Collins") |>
  glimpse()
#> Rows: 1
#> Columns: 5
#> $ request        <chr> "Fort Collins"
#> $ score          <int> 100
#> $ arcgis_address <chr> "Fort Collins, Colorado"
#> $ x              <dbl> -105.0766
#> $ y              <dbl> 40.58147

Return a POINT representation

The basic return can be converted to a POINT representation by setting pt = TRUE.

geocode("Fort Collins", pt = TRUE) |> 
  glimpse()
#> Rows: 1
#> Columns: 6
#> $ request        <chr> "Fort Collins"
#> $ score          <int> 100
#> $ arcgis_address <chr> "Fort Collins, Colorado"
#> $ geometry       <POINT [°]> POINT (-105.0766 40.58147)
#> $ x              <dbl> -105.0766
#> $ y              <dbl> 40.58147

The data will be returned in the crs specified in the function signature. By default, all AOI utilities act on:

This can be changed to meet your application needs:

geocode("Fort Collins", pt = TRUE, crs = 5070) |> 
  glimpse()
#> Rows: 1
#> Columns: 6
#> $ request        <chr> "Fort Collins"
#> $ score          <int> 100
#> $ arcgis_address <chr> "Fort Collins, Colorado"
#> $ geometry       <POINT [m]> POINT (-760708 1988474)
#> $ x              <dbl> -760708
#> $ y              <dbl> 1988474

AOI::geocode is setup to take more then one request and all prior arguments apply:

geocode(c("Boulder", "Fort Collins"), pt = TRUE, crs = 5070) |> 
  glimpse()
#> Rows: 2
#> Columns: 6
#> $ request        <chr> "Boulder", "Fort Collins"
#> $ score          <int> 100, 100
#> $ arcgis_address <chr> "Boulder, Colorado", "Fort Collins, Colorado"
#> $ geometry       <POINT [m]> POINT (-783814.6 1927038), POINT (-760708 1988474)
#> $ x              <dbl> -783814.6, -760708.0
#> $ y              <dbl> 1927038, 1988474

Return bounding box representation

Setting bbox = TRUE will return the bounding box representation of the geo input using the following rules:

If the geocoding method does not return an extent for an input, the POINT is returned
If a single geo is passed AND and extent is returned, the POLYGON is generated
If multiple geo objects are passed, the POLYGON representing the extent of all POINT(s) is returned

Default behavior

geocode("Fort Collins", bbox = TRUE)  |> 
  glimpse()
#> Rows: 1
#> Columns: 6
#> $ request        <chr> "Fort Collins"
#> $ score          <int> 100
#> $ arcgis_address <chr> "Fort Collins, Colorado"
#> $ x              <dbl> -105.0766
#> $ y              <dbl> 40.58147
#> $ geometry       <POLYGON [°]> POLYGON ((-105.1606 40.4974...

Multiple inputs return a single bounding box:

# EPSG:5070
geocode(c("Boulder", "Fort Collins"), bbox = TRUE, crs = 5070)  |> 
  aoi_map(returnMap = TRUE)

If you actually do want the extents of multiple inputs, then pass the inputs through lapply:

lapply(c('Fort Collins', 'Boulder'), FUN = geocode, bbox = TRUE) |>
  bind_rows() |>
  aoi_map(returnMap = TRUE)

Return bounding box and POINT representations

Setting all = TRUE will return both the point and bbox representation. The bbox returned will still follow the same rules:

geocode('Fort Collins', all = TRUE) |>
  aoi_map(returnMap = TRUE)


geocode(geo = c('Fort Collins', 'Boulder'), all = TRUE) |>
  aoi_map(returnMap = TRUE)

xy

Setting xy = TRUE will return just the XY coordinates of the geocoded point. This is useful for applications shown later:

geocode("Fort Collins", xy = TRUE)
#>          X          Y 
#> -105.07662   40.58147
geocode(geo = "Fort Collins", xy = TRUE, crs = 5070)
#>       X       Y 
#> -760708 1988474

Event based

Moving away for just tidygeocdoing, AOI::geocode provides tha

geocode(event = "dday") |>
 aoi_map(returnMap = TRUE)

geocode(event = "Hurricane Harvey", all = TRUE) |>
  aoi_map(returnMap = TRUE)

Reverse Geocoding

Reverse geocoding is the act of converting a XY location to a named entity.

# getting an xy input
xy = geocode("UCSB", xy = TRUE)

geocode_rev(xy)
#> # A tibble: 1 × 3
#>   address                                                                x     y
#>   <chr>                                                              <dbl> <dbl>
#> 1 University of California Santa Barbara Campus, University of Cali… -120.  34.4

geocode_rev(xy, pt = TRUE)
#> Simple feature collection with 1 feature and 1 field
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -119.8471 ymin: 34.4134 xmax: -119.8471 ymax: 34.4134
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 2
#>   address                                                         geometry
#> * <chr>                                                        <POINT [°]>
#> 1 University of California Santa Barbara Campus, Univ… (-119.8471 34.4134)

Mike Johnson