Add address fields to a known location table

The OpenCage reverse geocoding service is used to update an existing table. Updated columns include:

• countryCode

• stateCode

• countyName

• timezone

• houseNumber

• street

• city

• postalCode

• address

When replaceExisting = TRUE, all existing address fields are discarded in favor of the OpenCage versions. To only fill in missing values in locationTbl, use replaceExisting = FALSE.

The OpenCage service returns a large number of fields, some of which may be useful. To add all OpenCage fields to a location table, use retainOpenCage = TRUE. This will append 78+ fields of information, each each named with a prefix of "opencage_".

table_addOpenCageInfo(
  locationTbl = NULL,
  replaceExisting = FALSE,
  retainOpenCage = FALSE,
  verbose = FALSE
)

Arguments

locationTbl

Tibble of known locations.

replaceExisting

Logical specifying whether to replace existing data with data obtained from OpenCage.

retainOpenCage

Logical specifying whether to retain all fields obtained from OpenCage, each named with a prefix of opencage_.

verbose

Logical controlling the generation of progress messages.

Value

Tibble of "known locations" enhanced with information from the OpenCage reverse geocoding service.

Note

The OpenCage service requires an API key which can be obtained from their web site. This API key must be set as an environment variable with:

Sys.setenv("OPENCAGE_KEY" = "<your api key>")

Parameters are set for use at the OpenCage "free trial" level which allows for 1 request/sec and a maximum of 2500 requests per day.

Because of the 1 request/sec default, it is recommended that table_addOpenCageInfo() only be used in an interactive session when updating a table with a large number of records.

References

https://opencagedata.com

Examples

# \donttest{
library(MazamaLocationUtils)

# Fail gracefully if any resources are not available
try({

  myTbl <- id_monitors_500[1:3,]
  myTbl$countryCode[1] <- NA
  myTbl$countryCode[2] <- "WRONG"
  myTbl$countyName[3] <- "WRONG"
  myTbl$timezone <- NA

  dplyr::glimpse(myTbl)

  Sys.setenv("OPENCAGE_KEY" = "<YOUR_KEY>")

  table_addOpenCageInfo(myTbl) %>% 
    dplyr::glimpse()

  table_addOpenCageInfo(myTbl, replaceExisting = TRUE) %>% 
    dplyr::glimpse()

  table_addOpenCageInfo(myTbl, replaceExisting = TRUE, retainOpenCage = TRUE) %>% 
    dplyr::glimpse()
  
}, silent = FALSE)
#> Rows: 3
#> Columns: 13
#> $ locationID   <chr> "9rx46swbwb", "c2kfgvwwxu", "9xb3pzm2u0"
#> $ locationName <chr> "us.id_9rx46s", "us.id_c2kfgv", "us.id_9xb3pz"
#> $ longitude    <dbl> -113.7868, -116.8962, -111.8005
#> $ latitude     <dbl> 42.60782, 46.92100, 43.80949
#> $ elevation    <dbl> 1264.6, 784.2, 1480.6
#> $ countryCode  <chr> NA, "WRONG", "US"
#> $ stateCode    <chr> "ID", "ID", "ID"
#> $ countyName   <chr> "Minidoka", "Latah", "WRONG"
#> $ timezone     <lgl> NA, NA, NA
#> $ houseNumber  <chr> NA, NA, NA
#> $ street       <chr> NA, NA, NA
#> $ city         <chr> "Paul", "Potlatch", "Rexburg"
#> $ postalCode   <chr> "83347", "83855", "83440"
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Rows: 3
#> Columns: 14
#> $ locationID   <chr> "9rx46swbwb", "c2kfgvwwxu", "9xb3pzm2u0"
#> $ locationName <chr> "us.id_9rx46s", "us.id_c2kfgv", "us.id_9xb3pz"
#> $ longitude    <dbl> -113.7868, -116.8962, -111.8005
#> $ latitude     <dbl> 42.60782, 46.92100, 43.80949
#> $ elevation    <dbl> 1264.6, 784.2, 1480.6
#> $ countryCode  <chr> NA, "WRONG", "US"
#> $ stateCode    <chr> "ID", "ID", "ID"
#> $ countyName   <chr> "Minidoka", "Latah", "WRONG"
#> $ timezone     <lgl> NA, NA, NA
#> $ houseNumber  <chr> NA, NA, NA
#> $ street       <chr> NA, NA, NA
#> $ city         <chr> "Paul", "Potlatch", "Rexburg"
#> $ postalCode   <chr> "83347", "83855", "83440"
#> $ address      <chr> NA, NA, NA
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Rows: 3
#> Columns: 14
#> $ locationID   <chr> "9rx46swbwb", "c2kfgvwwxu", "9xb3pzm2u0"
#> $ locationName <chr> "us.id_9rx46s", "us.id_c2kfgv", "us.id_9xb3pz"
#> $ longitude    <dbl> -113.7868, -116.8962, -111.8005
#> $ latitude     <dbl> 42.60782, 46.92100, 43.80949
#> $ elevation    <dbl> 1264.6, 784.2, 1480.6
#> $ countryCode  <chr> NA, "WRONG", "US"
#> $ stateCode    <chr> "ID", "ID", "ID"
#> $ countyName   <chr> "Minidoka", "Latah", "WRONG"
#> $ timezone     <lgl> NA, NA, NA
#> $ houseNumber  <chr> NA, NA, NA
#> $ street       <chr> NA, NA, NA
#> $ city         <chr> "Paul", "Potlatch", "Rexburg"
#> $ postalCode   <chr> "83347", "83855", "83440"
#> $ address      <chr> NA, NA, NA
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Warning: Unauthorized (HTTP 401).
#> Error: invalid API key
#> Rows: 3
#> Columns: 17
#> $ locationID       <chr> "9rx46swbwb", "c2kfgvwwxu", "9xb3pzm2u0"
#> $ locationName     <chr> "us.id_9rx46s", "us.id_c2kfgv", "us.id_9xb3pz"
#> $ longitude        <dbl> -113.7868, -116.8962, -111.8005
#> $ latitude         <dbl> 42.60782, 46.92100, 43.80949
#> $ elevation        <dbl> 1264.6, 784.2, 1480.6
#> $ countryCode      <chr> NA, "WRONG", "US"
#> $ stateCode        <chr> "ID", "ID", "ID"
#> $ countyName       <chr> "Minidoka", "Latah", "WRONG"
#> $ timezone         <lgl> NA, NA, NA
#> $ houseNumber      <chr> NA, NA, NA
#> $ street           <chr> NA, NA, NA
#> $ city             <chr> "Paul", "Potlatch", "Rexburg"
#> $ postalCode       <chr> "83347", "83855", "83440"
#> $ address          <chr> NA, NA, NA
#> $ opencage_lat     <dbl> 42.60782, 46.92100, 43.80949
#> $ opencage_long    <dbl> -113.7868, -116.8962, -111.8005
#> $ opencage_address <chr> NA, NA, NA
# }