Forward geocoding

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

library("opencage")
output <- opencage_forward(placename = "Sarzeau")
print(output$time_stamp)
#> [1] "2018-01-16 12:21:19 CET"
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)
#> [1] "2018-01-16 12:21:21 CET"
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:

• bounds: Provides the geocoder with a hint to the region that the query resides in. This value will restrict the possible results to the supplied region. The bounds parameter should be specified as 4 coordinate points forming the south-west and north-east corners of a bounding box. For example, bounds = c(-0.563160, 51.280430, 0.278970, 51.683979) (min long, min lat, max long, max lat).

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()

• countrycode: Restricts the results to the given country. The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. “GB” for the United Kingdom, “FR” for France, “US” for United States. See example below.

results3 <- opencage_forward(placename = "Berlin", country = "DE")
results3$results %>% knitr::kable()

• language: an IETF format language code (such as “es” for Spanish or “pt-BR” for Brazilian Portuguese). If no language is explicitly specified, we will look for an HTTP Accept-Language header like those sent by a brower and use the first language specified and if none are specified “en” (English) will be assumed. See example below.

results3$results %>% knitr::kable()

results4 <- opencage_forward(placename = "Berlin", country = "DE", language = "de")
results4$results %>% knitr::kable()

• limit: How many results should be returned (1-100). Default is 10.

• min_confidence: an integer from 1-10. Only results with at least this confidence will be returned.

• no_annotations: Logical (default FALSE), when TRUE the output will not contain annotations.

• no_dedupe: Logical (default FALSE), when TRUE the output will not be deduplicated.

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))
#>    user  system elapsed 
#>    0.13    0.00    0.29

system.time(opencage_reverse(latitude = 10, longitude = 10))
#>    user  system elapsed 
#>       0       0       0

memoise::forget(opencage_reverse)
#> [1] TRUE
system.time(opencage_reverse(latitude = 10, longitude = 10))
#>    user  system elapsed 
#>    0.03    0.00    0.19

Privacy

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

• When no_record is FALSE a log of the query is made by OpenCage. The company uses them to better generally understand how people are using its service (forward or reverse geocoding, what parts of the world are people most interested in, etc) and for debugging. The overwhelming majority (99.9999+% of queries) are never specifically looked at (sheer volume prevents that) and are automatically deleted after a few days. More information about privacy can be found here.

• When no_record is TRUE the actual query is replaced with FILTERED in OpenCage logs, so that the company has no chance to see what your request was.

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.