table_addOpenCageInfo: Add address fields to a known location table

In MazamaLocationUtils: Manage Spatial Metadata for Known Locations

Add address fields to a known location table

Description

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_".

Usage

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

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)

MazamaLocationUtils documentation built on Sept. 11, 2024, 9:08 p.m.