Title: | Geocode with the OpenCage API |
---|---|
Description: | Geocode with the OpenCage API, either from place name to longitude and latitude (forward geocoding) or from longitude and latitude to the name and address of a location (reverse geocoding), see <https://opencagedata.com>. |
Authors: | Daniel Possenriede [aut, cre] , Jesse Sadler [aut] , Maƫlle Salmon [aut] , Noam Ross [ctb], Jake Russ [ctb], Julia Silge [rev] (Julia Silge reviewed {opencage} (v. 0.1.0) for rOpenSci, see <https://github.com/ropensci/onboarding/issues/36>.) |
Maintainer: | Daniel Possenriede <[email protected]> |
License: | GPL (>= 2) |
Version: | 0.2.2.9000 |
Built: | 2024-10-28 06:06:51 UTC |
Source: | https://github.com/ropensci/opencage |
Country codes
All possible ISO 3166-1 Alpha 2 standard country codes.
data("countrycodes")
data("countrycodes")
Create a list of bounding boxes for OpenCage queries.
oc_bbox(...) ## S3 method for class 'numeric' oc_bbox(xmin, ymin, xmax, ymax, ...) ## S3 method for class 'data.frame' oc_bbox(data, xmin, ymin, xmax, ymax, ...) ## S3 method for class 'bbox' oc_bbox(bbox, ...)
oc_bbox(...) ## S3 method for class 'numeric' oc_bbox(xmin, ymin, xmax, ymax, ...) ## S3 method for class 'data.frame' oc_bbox(data, xmin, ymin, xmax, ymax, ...) ## S3 method for class 'bbox' oc_bbox(bbox, ...)
... |
Ignored. |
xmin |
Minimum longitude (also known as |
ymin |
Minimum latitude (also known as |
xmax |
Maximum longitude (also known as |
ymax |
Maximum latitude (also known as |
data |
A |
bbox |
A |
A list of bounding boxes, each of class bbox
.
oc_bbox(-5.63160, 51.280430, 0.278970, 51.683979) xdf <- data.frame( place = c("Hamburg", "Hamburg"), northeast_lat = c(54.0276817, 42.7397729), northeast_lng = c(10.3252805, -78.812825), southwest_lat = c(53.3951118, 42.7091669), southwest_lng = c(8.1053284, -78.860521) ) oc_bbox( xdf, southwest_lng, southwest_lat, northeast_lng, northeast_lat ) # create bbox list column with dplyr library(dplyr) xdf %>% mutate( bbox = oc_bbox( southwest_lng, southwest_lat, northeast_lng, northeast_lat ) ) # create bbox list from a simple features bbox if (requireNamespace("sf", quietly = TRUE)) { library(sf) bbox <- st_bbox(c(xmin = 16.1, xmax = 16.6, ymax = 48.6, ymin = 47.9), crs = 4326 ) oc_bbox(bbox) }
oc_bbox(-5.63160, 51.280430, 0.278970, 51.683979) xdf <- data.frame( place = c("Hamburg", "Hamburg"), northeast_lat = c(54.0276817, 42.7397729), northeast_lng = c(10.3252805, -78.812825), southwest_lat = c(53.3951118, 42.7091669), southwest_lng = c(8.1053284, -78.860521) ) oc_bbox( xdf, southwest_lng, southwest_lat, northeast_lng, northeast_lat ) # create bbox list column with dplyr library(dplyr) xdf %>% mutate( bbox = oc_bbox( southwest_lng, southwest_lat, northeast_lng, northeast_lat ) ) # create bbox list from a simple features bbox if (requireNamespace("sf", quietly = TRUE)) { library(sf) bbox <- st_bbox(c(xmin = 16.1, xmax = 16.6, ymax = 48.6, ymin = 47.9), crs = 4326 ) oc_bbox(bbox) }
Forget past results and reset the opencage cache.
oc_clear_cache()
oc_clear_cache()
system.time(oc_reverse(latitude = 10, longitude = 10)) system.time(oc_reverse(latitude = 10, longitude = 10)) oc_clear_cache() system.time(oc_reverse(latitude = 10, longitude = 10))
system.time(oc_reverse(latitude = 10, longitude = 10)) system.time(oc_reverse(latitude = 10, longitude = 10)) oc_clear_cache() system.time(oc_reverse(latitude = 10, longitude = 10))
Configure session settings for opencage.
oc_config( key = Sys.getenv("OPENCAGE_KEY"), rate_sec = getOption("oc_rate_sec", default = 1L), no_record = getOption("oc_no_record", default = TRUE), show_key = getOption("oc_show_key", default = FALSE), ... )
oc_config( key = Sys.getenv("OPENCAGE_KEY"), rate_sec = getOption("oc_rate_sec", default = 1L), no_record = getOption("oc_no_record", default = TRUE), show_key = getOption("oc_show_key", default = FALSE), ... )
key |
Your OpenCage API key as a character vector of length one. Do not pass the key directly as a parameter, though. See details. |
rate_sec |
Numeric vector of length one. Sets the maximum number of
requests sent to the OpenCage API per second. Defaults to the value set in
the |
no_record |
Logical vector of length one. When |
show_key |
Logical vector of length one. This is only relevant when
debugging |
... |
Ignored. |
opencage will conveniently retrieve your API key if it is saved in the
environment variable "OPENCAGE_KEY"
. oc_config()
will help to set that
environment variable. Do not pass the key directly as a parameter to the
function, though, as you risk exposing it via your script or your history.
There are three safer ways to set your API key instead:
Save your API key as an environment variable in
.Renviron
as described in What They Forgot to Teach You About R or Efficient R Programming.
From there it will be fetched by all functions that call the OpenCage API.
You do not even have to call oc_config()
to set your key; you can start
geocoding right away. If you have the usethis package installed, you
can edit your .Renviron
with usethis::edit_r_environ()
.
We strongly recommend storing your API key in the user-level .Renviron, as
opposed to the project-level. This makes it less likely you will share
sensitive information by mistake.
If you use a package like keyring to store your credentials, you can
safely pass your key in a script with a function call like this
oc_config(key = keyring::key_get("opencage"))
.
If you call oc_config()
in an base::interactive()
session and the
OPENCAGE_KEY
environment variable is not set, it will prompt you to enter
the key in the console.
The rate limit allowed by the API depends on the OpenCage plan you purchased
and ranges from 1 request/sec for the "Free Trial" plan to 15 requests/sec
for the "Medium" or "Large" plans, see https://opencagedata.com/pricing for
details and up-to-date information. You can set the rate limit persistently
across sessions by setting an oc_rate_sec
option in your
.Rprofile
. If you have the usethis package
installed, you can edit your .Rprofile
with
usethis::edit_r_profile()
.
By default, OpenCage will store your queries in its server logs and will cache the forward geocoding requests on their side. They do this in order to speed up response times and to be able to debug errors and improve their service. Logs are automatically deleted after six months according to OpenCage's page on data protection and GDPR.
If you set no_record
to TRUE
, the query contents are not logged nor
cached. OpenCage still records that you made a request, but not the specific
query you made. oc_config(no_record = TRUE)
sets the oc_no_record
option for the active R session, so it will be used for all
subsequent OpenCage queries. You can set the oc_no_record
option persistently across sessions in your
.Rprofile
.
For increased privacy opencage sets no_record
to TRUE
, by default.
Please note, however, that opencage always caches the data it receives
from the OpenCage API locally, but only for as long as your R session is
alive.
For more information on OpenCage's policies on privacy and data protection
see their FAQs, their GDPR page, and, for the no_record
parameter, see
the relevant blog post.
Forward geocoding from a character vector of location names to latitude and longitude tuples.
oc_forward( placename, return = c("df_list", "json_list", "geojson_list", "url_only"), bounds = NULL, proximity = NULL, countrycode = NULL, language = NULL, limit = 10L, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, add_request = FALSE, ... )
oc_forward( placename, return = c("df_list", "json_list", "geojson_list", "url_only"), bounds = NULL, proximity = NULL, countrycode = NULL, language = NULL, limit = 10L, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, add_request = FALSE, ... )
placename |
A character vector with the location names or addresses to be geocoded. If the locations are addresses, see OpenCage's instructions on how to format addresses for best forward geocoding results. |
return |
A character vector of length one indicating the return value of
the function, either a list of tibbles ( |
bounds |
A list of bounding boxes of length one or |
proximity |
A list of points of length one or |
countrycode |
A two letter code as defined by the ISO 3166-1 Alpha 2 standard that restricts the
results to the given country or countries. E.g. "AR" for Argentina, "FR"
for France, "NZ" for the New Zealand. Multiple countrycodes per |
language |
An IETF BCP 47 language tag (such as "es" for
Spanish or "pt-BR" for Brazilian Portuguese). OpenCage will attempt to
return results in that language. Alternatively you can specify the "native"
tag, in which case OpenCage will attempt to return the response in the
"official" language(s). In case the |
limit |
Numeric vector of integer values to determine the maximum number
of results returned for each |
min_confidence |
Numeric vector of integer values between 0 and 10
indicating the precision of the returned result as defined by its
geographical extent, (i.e. by the extent of the result's bounding box). See
the API documentation for
details. Only results with at least the requested confidence will be
returned. Default is |
no_annotations |
Logical vector indicating whether additional
information about the result location should be returned. |
roadinfo |
Logical vector indicating whether the geocoder should attempt
to match the nearest road (rather than an address) and provide additional
road and driving information. Default is |
no_dedupe |
Logical vector (default |
abbrv |
Logical vector (default |
address_only |
Logical vector (default |
add_request |
Logical vector (default |
... |
Ignored. |
Depending on the return
argument, oc_forward
returns a list with
either
the results as tibbles ("df_list"
, the default),
the results as JSON specified as a list ("json_list"
),
the results as GeoJSON specified as a list ("geojson_list"
),
or
the URL of the OpenCage API call for debugging purposes
("url_only"
).
When the results are returned as (a list of) tibbles, the column names
coming from the OpenCage API are prefixed with "oc_"
.
oc_forward_df()
for inputs as a data frame, or oc_reverse()
and
oc_reverse_df()
for reverse geocoding. For more information about the API
and the various parameters, see the OpenCage API documentation.
# Geocode a single location, an address in this case oc_forward(placename = "Triererstr 15, 99432, Weimar, Deutschland") # Geocode multiple locations locations <- c("Nantes", "Hamburg", "Los Angeles") oc_forward(placename = locations) # Use bounding box to help return accurate results # for each placename bounds <- oc_bbox( xmin = c(-2, 9, -119), ymin = c(47, 53, 34), xmax = c(0, 10, -117), ymax = c(48, 54, 35) ) oc_forward(placename = locations, bounds = bounds) # Another way to help specify the desired results # is with country codes. oc_forward( placename = locations, countrycode = c("ca", "us", "co") ) # With multiple countrycodes per placename oc_forward( placename = locations, countrycode = list(c("fr", "ca"), c("de", "us"), c("us", "co")) ) # Return results in a preferred language if possible oc_forward( placename = c("Brugge", "Mechelen", "Antwerp"), language = "fr" ) # Limit the number of results per placename and return json_list oc_forward( placename = locations, bounds = bounds, limit = 1, return = "json_list" )
# Geocode a single location, an address in this case oc_forward(placename = "Triererstr 15, 99432, Weimar, Deutschland") # Geocode multiple locations locations <- c("Nantes", "Hamburg", "Los Angeles") oc_forward(placename = locations) # Use bounding box to help return accurate results # for each placename bounds <- oc_bbox( xmin = c(-2, 9, -119), ymin = c(47, 53, 34), xmax = c(0, 10, -117), ymax = c(48, 54, 35) ) oc_forward(placename = locations, bounds = bounds) # Another way to help specify the desired results # is with country codes. oc_forward( placename = locations, countrycode = c("ca", "us", "co") ) # With multiple countrycodes per placename oc_forward( placename = locations, countrycode = list(c("fr", "ca"), c("de", "us"), c("us", "co")) ) # Return results in a preferred language if possible oc_forward( placename = c("Brugge", "Mechelen", "Antwerp"), language = "fr" ) # Limit the number of results per placename and return json_list oc_forward( placename = locations, bounds = bounds, limit = 1, return = "json_list" )
Forward geocoding from a column or vector of location names to latitude and longitude tuples.
oc_forward_df(...) ## S3 method for class 'data.frame' oc_forward_df( data, placename, bind_cols = TRUE, output = c("short", "all"), bounds = NULL, proximity = NULL, countrycode = NULL, language = NULL, limit = 1L, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... ) ## S3 method for class 'character' oc_forward_df( placename, output = c("short", "all"), bounds = NULL, proximity = NULL, countrycode = NULL, language = NULL, limit = 1L, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... )
oc_forward_df(...) ## S3 method for class 'data.frame' oc_forward_df( data, placename, bind_cols = TRUE, output = c("short", "all"), bounds = NULL, proximity = NULL, countrycode = NULL, language = NULL, limit = 1L, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... ) ## S3 method for class 'character' oc_forward_df( placename, output = c("short", "all"), bounds = NULL, proximity = NULL, countrycode = NULL, language = NULL, limit = 1L, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... )
... |
Ignored. |
data |
A data frame. |
placename |
An unquoted variable name of a character column or vector with the location names or addresses to be geocoded. If the locations are addresses, see OpenCage's instructions on how to format addresses for best forward geocoding results. |
bind_cols |
When |
output |
A character vector of length one indicating whether only
latitude, longitude, and formatted address variables ( |
bounds |
A list of length one, or an unquoted variable name of a list
column of bounding boxes. Bounding boxes are named numeric vectors, each
with 4 coordinates forming the south-west and north-east corners of the
bounding box: |
proximity |
A list of length one, or an unquoted variable name of a list
column of points. Points are named numeric vectors with latitude, longitude
coordinate pairs in decimal format. |
countrycode |
Character vector, or an unquoted variable name of such a
vector, of two-letter codes as defined by the ISO 3166-1 Alpha 2 standard that restricts the
results to the given country or countries. E.g. "AR" for Argentina, "FR"
for France, "NZ" for the New Zealand. Multiple countrycodes per |
language |
Character vector, or an unquoted variable name of such a
vector, of IETF BCP 47 language tags (such as "es" for
Spanish or "pt-BR" for Brazilian Portuguese). OpenCage will attempt to
return results in that language. Alternatively you can specify the "native"
tag, in which case OpenCage will attempt to return the response in the
"official" language(s). In case the |
limit |
Numeric vector of integer values, or an unquoted variable name
of such a vector, to determine the maximum number of results returned for
each |
min_confidence |
Numeric vector of integer values, or an unquoted
variable name of such a vector, between 0 and 10 indicating the precision
of the returned result as defined by its geographical extent, (i.e. by the
extent of the result's bounding box). See the API documentation for details. Only
results with at least the requested confidence will be returned. Default is
|
no_annotations |
Logical vector, or an unquoted variable name of such a
vector, indicating whether additional information about the result location
should be returned. |
roadinfo |
Logical vector, or an unquoted variable name of such a
vector, indicating whether the geocoder should attempt to match the nearest
road (rather than an address) and provide additional road and driving
information. Default is |
no_dedupe |
Logical vector, or an unquoted variable name of such a
vector. Default is |
abbrv |
Logical vector, or an unquoted variable name of such a vector.
Default is |
address_only |
Logical vector, or an unquoted variable name of such a
vector. Default is |
A tibble. Column names coming from the OpenCage API are prefixed with
"oc_"
.
oc_forward()
for inputs as vectors, or oc_reverse()
and
oc_reverse_df()
for reverse geocoding. For more information about the API
and the various parameters, see the OpenCage API documentation.
library(tibble) df <- tibble( id = 1:3, locations = c("Nantes", "Hamburg", "Los Angeles") ) # Return lat, lng, and formatted address oc_forward_df(df, placename = locations) # Return more detailed information about the locations oc_forward_df(df, placename = locations, output = "all") # Do not column bind results to input data frame oc_forward_df(df, placename = locations, bind_cols = FALSE) # Add more results by changing the limit from the default of 1. oc_forward_df(df, placename = locations, limit = 5) # Restrict results to a given bounding box oc_forward_df(df, placename = locations, bounds = oc_bbox(-5, 45, 15, 55) ) # oc_forward_df accepts unquoted column names for all # arguments except bind_cols and output. # This makes it possible to build up more detailed queries # through the data frame passed to the data argument. df2 <- add_column(df, bounds = oc_bbox( xmin = c(-2, 9, -119), ymin = c(47, 53, 34), xmax = c(0, 10, -117), ymax = c(48, 54, 35) ), limit = 1:3, countrycode = c("ca", "us", "co"), language = c("fr", "de", "en") ) # Use the bounds column to help return accurate results and # language column to specify preferred language of results oc_forward_df(df2, placename = locations, bounds = bounds, language = language ) # Different limit of results for each placename oc_forward_df(df2, placename = locations, limit = limit ) # Specify the desired results by the countrycode column oc_forward_df(df2, placename = locations, countrycode = countrycode )
library(tibble) df <- tibble( id = 1:3, locations = c("Nantes", "Hamburg", "Los Angeles") ) # Return lat, lng, and formatted address oc_forward_df(df, placename = locations) # Return more detailed information about the locations oc_forward_df(df, placename = locations, output = "all") # Do not column bind results to input data frame oc_forward_df(df, placename = locations, bind_cols = FALSE) # Add more results by changing the limit from the default of 1. oc_forward_df(df, placename = locations, limit = 5) # Restrict results to a given bounding box oc_forward_df(df, placename = locations, bounds = oc_bbox(-5, 45, 15, 55) ) # oc_forward_df accepts unquoted column names for all # arguments except bind_cols and output. # This makes it possible to build up more detailed queries # through the data frame passed to the data argument. df2 <- add_column(df, bounds = oc_bbox( xmin = c(-2, 9, -119), ymin = c(47, 53, 34), xmax = c(0, 10, -117), ymax = c(48, 54, 35) ), limit = 1:3, countrycode = c("ca", "us", "co"), language = c("fr", "de", "en") ) # Use the bounds column to help return accurate results and # language column to specify preferred language of results oc_forward_df(df2, placename = locations, bounds = bounds, language = language ) # Different limit of results for each placename oc_forward_df(df2, placename = locations, limit = limit ) # Specify the desired results by the countrycode column oc_forward_df(df2, placename = locations, countrycode = countrycode )
Create a list of points (latitude/longitude coordinate pairs) for OpenCage queries.
oc_points(...) ## S3 method for class 'numeric' oc_points(latitude, longitude, ...) ## S3 method for class 'data.frame' oc_points(data, latitude, longitude, ...)
oc_points(...) ## S3 method for class 'numeric' oc_points(latitude, longitude, ...) ## S3 method for class 'data.frame' oc_points(data, latitude, longitude, ...)
... |
Ignored. |
latitude , longitude
|
Numeric vectors of latitude and longitude values. |
data |
A |
A list of points. Each point is a named vector of length 2 containing a latitude/longitude coordinate pair.
oc_points(-21.01404, 55.26077) xdf <- data.frame( place = c("Hamburg", "Los Angeles"), lat = c(53.5503, 34.0536), lon = c(10.0006, -118.2427) ) oc_points( data = xdf, latitude = lat, longitude = lon ) # create a list column with points with dplyr library(dplyr) xdf %>% mutate( points = oc_points( lat, lon ) )
oc_points(-21.01404, 55.26077) xdf <- data.frame( place = c("Hamburg", "Los Angeles"), lat = c(53.5503, 34.0536), lon = c(10.0006, -118.2427) ) oc_points( data = xdf, latitude = lat, longitude = lon ) # create a list column with points with dplyr library(dplyr) xdf %>% mutate( points = oc_points( lat, lon ) )
Reverse geocoding from numeric vectors of latitude and longitude pairs to the names and addresses of a location.
oc_reverse( latitude, longitude, return = c("df_list", "json_list", "geojson_list", "url_only"), language = NULL, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, add_request = FALSE, ... )
oc_reverse( latitude, longitude, return = c("df_list", "json_list", "geojson_list", "url_only"), language = NULL, min_confidence = NULL, no_annotations = TRUE, roadinfo = FALSE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, add_request = FALSE, ... )
latitude , longitude
|
Numeric vectors of latitude and longitude values. |
return |
A character vector of length one indicating the return value of
the function, either a list of tibbles ( |
language |
An IETF BCP 47 language tag (such as "es" for
Spanish or "pt-BR" for Brazilian Portuguese). OpenCage will attempt to
return results in that language. Alternatively you can specify the "native"
tag, in which case OpenCage will attempt to return the response in the
"official" language(s). In case the |
min_confidence |
Numeric vector of integer values between 0 and 10
indicating the precision of the returned result as defined by its
geographical extent, (i.e. by the extent of the result's bounding box). See
the API documentation for
details. Only results with at least the requested confidence will be
returned. Default is |
no_annotations |
Logical vector indicating whether additional
information about the result location should be returned. |
roadinfo |
Logical vector indicating whether the geocoder should attempt
to match the nearest road (rather than an address) and provide additional
road and driving information. Default is |
no_dedupe |
Logical vector (default |
abbrv |
Logical vector (default |
address_only |
Logical vector (default |
add_request |
Logical vector (default |
... |
Ignored. |
Depending on the return
argument, oc_reverse
returns a list with
either
the results as tibbles ("df_list"
, the default),
the results as JSON specified as a list ("json_list"
),
the results as GeoJSON specified as a list ("geojson_list"
),
or
the URL of the OpenCage API call for debugging purposes
("url_only"
).
When the results are returned as (a list of) tibbles, the column names
coming from the OpenCage API are prefixed with "oc_"
.
oc_reverse_df()
for inputs as a data frame, or oc_forward()
and
oc_forward()
for forward geocoding. For more information about the API
and the various parameters, see the OpenCage API documentation.
# Reverse geocode a single location oc_reverse(latitude = -36.85007, longitude = 174.7706) # Reverse geocode multiple locations lat <- c(47.21864, 53.55034, 34.05369) lng <- c(-1.554136, 10.000654, -118.242767) oc_reverse(latitude = lat, longitude = lng) # Return results in a preferred language if possible oc_reverse( latitude = lat, longitude = lng, language = "fr" ) # Return results as a json list oc_reverse( latitude = lat, longitude = lng, return = "json_list" )
# Reverse geocode a single location oc_reverse(latitude = -36.85007, longitude = 174.7706) # Reverse geocode multiple locations lat <- c(47.21864, 53.55034, 34.05369) lng <- c(-1.554136, 10.000654, -118.242767) oc_reverse(latitude = lat, longitude = lng) # Return results in a preferred language if possible oc_reverse( latitude = lat, longitude = lng, language = "fr" ) # Return results as a json list oc_reverse( latitude = lat, longitude = lng, return = "json_list" )
Reverse geocoding from latitude and longitude pairs to the names and addresses of a location.
oc_reverse_df(...) ## S3 method for class 'data.frame' oc_reverse_df( data, latitude, longitude, bind_cols = TRUE, output = c("short", "all"), language = NULL, min_confidence = NULL, roadinfo = FALSE, no_annotations = TRUE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... ) ## S3 method for class 'numeric' oc_reverse_df( latitude, longitude, output = c("short", "all"), language = NULL, min_confidence = NULL, no_annotations = TRUE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... )
oc_reverse_df(...) ## S3 method for class 'data.frame' oc_reverse_df( data, latitude, longitude, bind_cols = TRUE, output = c("short", "all"), language = NULL, min_confidence = NULL, roadinfo = FALSE, no_annotations = TRUE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... ) ## S3 method for class 'numeric' oc_reverse_df( latitude, longitude, output = c("short", "all"), language = NULL, min_confidence = NULL, no_annotations = TRUE, no_dedupe = FALSE, abbrv = FALSE, address_only = FALSE, ... )
... |
Ignored. |
data |
A data frame. |
latitude , longitude
|
Unquoted variable names of numeric columns or vectors of latitude and longitude values. |
bind_cols |
When |
output |
A character vector of length one indicating whether only the
formatted address ( |
language |
Character vector, or an unquoted variable name of such a
vector, of IETF BCP 47 language tags (such as "es" for
Spanish or "pt-BR" for Brazilian Portuguese). OpenCage will attempt to
return results in that language. Alternatively you can specify the "native"
tag, in which case OpenCage will attempt to return the response in the
"official" language(s). In case the |
min_confidence |
Numeric vector of integer values, or an unquoted
variable name of such a vector, between 0 and 10 indicating the precision
of the returned result as defined by its geographical extent, (i.e. by the
extent of the result's bounding box). See the API documentation for details. Only
results with at least the requested confidence will be returned. Default is
|
roadinfo |
Logical vector, or an unquoted variable name of such a
vector, indicating whether the geocoder should attempt to match the nearest
road (rather than an address) and provide additional road and driving
information. Default is |
no_annotations |
Logical vector, or an unquoted variable name of such a
vector, indicating whether additional information about the result location
should be returned. |
no_dedupe |
Logical vector, or an unquoted variable name of such a
vector. Default is |
abbrv |
Logical vector, or an unquoted variable name of such a vector.
Default is |
address_only |
Logical vector, or an unquoted variable name of such a
vector. Default is |
A tibble. Column names coming from the OpenCage API are prefixed with
"oc_"
.
oc_reverse()
for inputs as vectors, or oc_forward()
and
oc_forward()
for forward geocoding. For more information about the API
and the various parameters, see the OpenCage API documentation.
library(tibble) df <- tibble( id = 1:4, lat = c(-36.85007, 47.21864, 53.55034, 34.05369), lng = c(174.7706, -1.554136, 10.000654, -118.242767) ) # Return formatted address of lat/lng values oc_reverse_df(df, latitude = lat, longitude = lng) # Return more detailed information about the locations oc_reverse_df(df, latitude = lat, longitude = lng, output = "all" ) # Return results in a preferred language if possible oc_reverse_df(df, latitude = lat, longitude = lng, language = "fr" ) # oc_reverse_df accepts unquoted column names for all # arguments except bind_cols and output. # This makes it possible to build up more detailed queries # through the data frame passed to the data argument. df2 <- add_column(df, language = c("en", "fr", "de", "en"), confidence = c(8, 10, 10, 10) ) # Use language column to specify preferred language of results # and confidence column to allow different confidence levels oc_reverse_df(df2, latitude = lat, longitude = lng, language = language, min_confidence = confidence )
library(tibble) df <- tibble( id = 1:4, lat = c(-36.85007, 47.21864, 53.55034, 34.05369), lng = c(174.7706, -1.554136, 10.000654, -118.242767) ) # Return formatted address of lat/lng values oc_reverse_df(df, latitude = lat, longitude = lng) # Return more detailed information about the locations oc_reverse_df(df, latitude = lat, longitude = lng, output = "all" ) # Return results in a preferred language if possible oc_reverse_df(df, latitude = lat, longitude = lng, language = "fr" ) # oc_reverse_df accepts unquoted column names for all # arguments except bind_cols and output. # This makes it possible to build up more detailed queries # through the data frame passed to the data argument. df2 <- add_column(df, language = c("en", "fr", "de", "en"), confidence = c(8, 10, 10, 10) ) # Use language column to specify preferred language of results # and confidence column to allow different confidence levels oc_reverse_df(df2, latitude = lat, longitude = lng, language = language, min_confidence = confidence )
Deprecated: use oc_forward
or oc_forward_df
for forward geocoding.
opencage_forward( placename, key = opencage_key(), bounds = NULL, countrycode = NULL, language = NULL, limit = 10L, min_confidence = NULL, no_annotations = FALSE, no_dedupe = FALSE, no_record = FALSE, abbrv = FALSE, add_request = TRUE )
opencage_forward( placename, key = opencage_key(), bounds = NULL, countrycode = NULL, language = NULL, limit = 10L, min_confidence = NULL, no_annotations = FALSE, no_dedupe = FALSE, no_record = FALSE, abbrv = FALSE, add_request = TRUE )
placename |
A character vector with the location names or addresses to be geocoded. If the locations are addresses, see OpenCage's instructions on how to format addresses for best forward geocoding results. |
key |
Your OpenCage API key as a character vector of length one. By
default, |
bounds |
A list of bounding boxes of length one or |
countrycode |
A two letter code as defined by the ISO 3166-1 Alpha 2 standard that restricts the
results to the given country or countries. E.g. "AR" for Argentina, "FR"
for France, "NZ" for the New Zealand. Multiple countrycodes per |
language |
An IETF BCP 47 language tag (such as "es" for
Spanish or "pt-BR" for Brazilian Portuguese). OpenCage will attempt to
return results in that language. Alternatively you can specify the "native"
tag, in which case OpenCage will attempt to return the response in the
"official" language(s). In case the |
limit |
Numeric vector of integer values to determine the maximum number
of results returned for each |
min_confidence |
Numeric vector of integer values between 0 and 10
indicating the precision of the returned result as defined by its
geographical extent, (i.e. by the extent of the result's bounding box). See
the API documentation for
details. Only results with at least the requested confidence will be
returned. Default is |
no_annotations |
Logical vector indicating whether additional
information about the result location should be returned. |
no_dedupe |
Logical vector (default |
no_record |
Logical vector of length one (default |
abbrv |
Logical vector (default |
add_request |
Logical vector (default |
A list with
results as a tibble with one line per result,
the number of results as an integer,
the timestamp as a POSIXct object,
rate_info tibble/data.frame with the maximal number of API calls per day for the used key, the number of remaining calls for the day and the time at which the number of remaining calls will be reset.
opencage_forward(placename = "Sarzeau") opencage_forward(placename = "Islington, London") opencage_forward(placename = "Triererstr 15, Weimar 99423, Deutschland")
opencage_forward(placename = "Sarzeau") opencage_forward(placename = "Islington, London") opencage_forward(placename = "Triererstr 15, Weimar 99423, Deutschland")
Deprecated: use oc_reverse
or oc_reverse_df
for reverse geocoding.
opencage_reverse( latitude, longitude, key = opencage_key(), bounds = NULL, countrycode = NULL, language = NULL, limit = 10, min_confidence = NULL, no_annotations = FALSE, no_dedupe = FALSE, no_record = FALSE, abbrv = FALSE, add_request = TRUE )
opencage_reverse( latitude, longitude, key = opencage_key(), bounds = NULL, countrycode = NULL, language = NULL, limit = 10, min_confidence = NULL, no_annotations = FALSE, no_dedupe = FALSE, no_record = FALSE, abbrv = FALSE, add_request = TRUE )
latitude , longitude
|
Numeric vectors of latitude and longitude values. |
key |
Your OpenCage API key as a character vector of length one. By
default, |
bounds |
Bounding box, ignored for reverse geocoding. |
countrycode |
Country code, ignored for reverse geocoding. |
language |
An IETF BCP 47 language tag (such as "es" for
Spanish or "pt-BR" for Brazilian Portuguese). OpenCage will attempt to
return results in that language. Alternatively you can specify the "native"
tag, in which case OpenCage will attempt to return the response in the
"official" language(s). In case the |
limit |
How many results should be returned (1-100), ignored for reverse geocoding. |
min_confidence |
Numeric vector of integer values between 0 and 10
indicating the precision of the returned result as defined by its
geographical extent, (i.e. by the extent of the result's bounding box). See
the API documentation for
details. Only results with at least the requested confidence will be
returned. Default is |
no_annotations |
Logical vector indicating whether additional
information about the result location should be returned. |
no_dedupe |
Logical vector (default |
no_record |
Logical vector of length one (default |
abbrv |
Logical vector (default |
add_request |
Logical vector (default |
A list with
results as a tibble with one line per result,
the number of results as an integer,
the timestamp as a POSIXct object,
rate_info tibble/data.frame with the maximal number of API calls per day for the used key, the number of remaining calls for the day and the time at which the number of remaining calls will be reset.
opencage_reverse( latitude = 0, longitude = 0, limit = 2 )
opencage_reverse( latitude = 0, longitude = 0, limit = 2 )
These functions still work but will be removed (defunct) in the next version.