R Package for the OpenCage API

NOT_CRAN <- identical(tolower(Sys.getenv("NOT_CRAN")), "true")
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  purl = NOT_CRAN,
  eval = NOT_CRAN
)

This package is an interface to the OpenCage API that allows forward and reverse geocoding. To use the package, you will need an API key. To get an API key for OpenCage geocoding, register at https://geocoder.opencagedata.com/pricing. The free API key provides up to 2,500 calls a day. For ease of use, save your API key as an environment variable as described at http://stat545.com/bit003_api-key-env-var.html.

Both functions of the package will conveniently look for your API key using Sys.getenv("OPENCAGE_KEY") so if your API key is an environment variable called "OPENCAGE_KEY" you don't need to input it manually.

Geocoding

The OpenCage API supports forward and reverse geocoding. Sources of OpenCage are open geospatial data including OpenStreetMap, Yahoo! GeoPlanet, Natural Earth Data, Thematic Mapping, Ordnance Survey OpenSpace, Statistics New Zealand, Zillow, MaxMind, GeoNames, the US Census Bureau and Flickr's shapefiles plus a whole lot more besides. See this page for the full list of credits.

Both forward and reverse geocoding typically return multiple results. Regarding these multiple results, the API doc states, "In cases where the geocoder is able to find multiple matches, the geocoder will return multiple results. The confidence or coordinates for each result should be examined to determine whether each result from an ambiguous query is sufficiently high to warrant using a result or not. A good strategy to reduce ambiguity is to use the optional bounds parameter described below to limit the area searched." Multiple results might mean you get a result for the airport and a road when querying a city name, or results for cities with the same name in different countries.

Below are two simple examples.

Forward geocoding

Forward geocoding is from placename to latitude and longitude tuplet(s).

library("opencage")
output <- opencage_forward(placename = "Sarzeau")
print(output$time_stamp)
library("dplyr")
output$rate_info %>% knitr::kable()
output$results %>% knitr::kable()

Reverse geocoding

Reverse geocoding is from latitude and longitude to placename(s). T

output2 <- opencage_reverse(latitude = 51.5034070, 
                            longitude = -0.1275920)
print(output2$time_stamp)
output2$rate_info %>% knitr::kable()
output2$results %>% knitr::kable()

Output

For both opencage_forward and opencage_reverse functions, the package returns a list with a time stamp for the query, the total number of results, a data.frame (dplyr tbl_df) with information about the remaining calls to the API unless you have an unlimited account, and a data.frame (dplyr tbl_df) with the results corresponding to your query. You can find longitude and latitude for each results as geometry.lat and geometry.lng. Other information includes country and country information, time of sunset and sunrise, geohash (a geocoding system identifying a point with a single string, as explained in many more details here and here; for pure conversion between longitude/latitude and geohashes, see this package). Depending on the data available in the API for the results one gets different columns; there can be a lot to explore!

Parameters

Optional parameters of both opencage_forward and opencage_reverse can make the query more precise:

Below is an example of the use of bounds where the rectangle given in the second call does not include Europe so that we don't get results for Berlin in Germany.

results1 <- opencage_forward(placename = "Berlin")
results1$results %>% knitr::kable()
results2 <- opencage_forward(placename = "Berlin",
                             bounds = c(-90,38,0, 45))
results2$results %>% knitr::kable()
results3 <- opencage_forward(placename = "Berlin", country = "DE")
results3$results %>% knitr::kable()
results3$results %>% knitr::kable()
results4 <- opencage_forward(placename = "Berlin", country = "DE", language = "de")
results4$results %>% knitr::kable()

For more information about the output and the query parameters, see the package documentation, the API doc and OpenCage FAQ.

Caching

The underlying data at OpenCage is updated about once a day. Note that the package uses memoise with no timeout argument so that results are cached inside an active R session.

system.time(opencage_reverse(latitude = 10, longitude = 10))

system.time(opencage_reverse(latitude = 10, longitude = 10))

memoise::forget(opencage_reverse)
system.time(opencage_reverse(latitude = 10, longitude = 10))

Privacy

Both functions have a parameter no_record. It is FALSE by default.

Addresses

They also have an abbr parameter, FALSE by default. When it is TRUE the addresses are abbreviated in the results, see more details in this blog post.

Return query text

The OpenCage API includes an optional add_request parameter that when set to 1 the query text is added to the response. This argument is set to TRUE by default, which allows for easy merging of the response data and the orignal query text.



Try the opencage package in your browser

Any scripts or data that you put into this service are public.

opencage documentation built on Jan. 20, 2018, 9:20 a.m.