From 07134cea3fc2cac645215991d121dce6d207cb89 Mon Sep 17 00:00:00 2001 From: Daniel Possenriede Date: Mon, 13 Jan 2025 13:30:53 +0100 Subject: [PATCH] fix tests (#163) * use examples from Brest instead of Nantes, because some examples don't work anymore, cf. #160 * remove tests w.r.t. `min_confidence`, cf. #161, #162 * update {Roxygen} version * add ProjectId * update snapshots, presumably due to changes in {testthat} * make lintr happy * remove more tests w.r.t. `min_confidence` * some minor fixes, e.g. `q=Berlin, limit=5` returns only one result, making that example useless. also the hotel de ville in Nantes example isn't working anymore, see #160 * pre-compile vignettes and README --- .lintr | 5 +- DESCRIPTION | 2 +- README.md | 14 +- opencage.Rproj | 1 + tests/testthat/_snaps/deprecated.md | 2 +- tests/testthat/_snaps/oc_check_query.md | 30 ++- tests/testthat/helper-opencage.R | 26 +-- tests/testthat/test-deprecated.R | 3 - tests/testthat/test-oc_check_query.R | 10 - tests/testthat/test-oc_forward.R | 18 +- tests/testthat/test-oc_process.R | 11 - tests/testthat/test-oc_reverse.R | 18 +- vignettes/customise_query.Rmd | 288 ++++++++++++------------ vignettes/customise_query.Rmd.src | 31 +-- vignettes/opencage.Rmd | 67 +++--- vignettes/output_options.Rmd | 243 +++++++------------- 16 files changed, 332 insertions(+), 437 deletions(-) diff --git a/.lintr b/.lintr index 4da2e69a..c44f6a36 100644 --- a/.lintr +++ b/.lintr @@ -1 +1,4 @@ -linters: linters_with_tags(c("package_development", "default"), cyclocomp_linter = NULL) # .oc_check_query() +linters: linters_with_tags( + c("package_development", "default"), + cyclocomp_linter = NULL, # .oc_check_query() + indentation_linter = NULL) # https://github.com/r-lib/lintr/issues/2034, https://github.com/r-lib/lintr/issues/2535 diff --git a/DESCRIPTION b/DESCRIPTION index aeeeeaba..b66eb8a6 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -52,4 +52,4 @@ Encoding: UTF-8 Language: en-GB LazyData: TRUE Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.2 diff --git a/README.md b/README.md index 9be1d4f9..63539615 100644 --- a/README.md +++ b/README.md @@ -90,19 +90,27 @@ library(opencage) oc_forward_df(placename = "Sarzeau") ``` +
+ | placename | oc_lat | oc_lng | oc_formatted | |:----------|---------:|--------:|:----------------------| | Sarzeau | 47.52877 | -2.7642 | 56370 Sarzeau, France | +
+ Or turn a set of coordinates into the name and address of the location: ``` r oc_reverse_df(latitude = 51.5034070, longitude = -0.1275920) ``` -| latitude | longitude | oc_formatted | -|---------:|----------:|:----------------------------------------------------| -| 51.50341 | -0.127592 | 10 Downing Street, London, SW1A 2AA, United Kingdom | +
+ +| latitude | longitude | oc_formatted | +|---:|---:|:---| +| 51.50341 | -0.127592 | 10 Downing Street, Westminster, London, SW1A 2AA, United Kingdom | + +
But remember, the vignettes are really great! We have: diff --git a/opencage.Rproj b/opencage.Rproj index 270314b8..3319c1a6 100644 --- a/opencage.Rproj +++ b/opencage.Rproj @@ -1,4 +1,5 @@ Version: 1.0 +ProjectId: 3d5685ec-c81f-43a6-a376-4b6992e50ed3 RestoreWorkspace: Default SaveWorkspace: Default diff --git a/tests/testthat/_snaps/deprecated.md b/tests/testthat/_snaps/deprecated.md index daabf1ee..3ec4d648 100644 --- a/tests/testthat/_snaps/deprecated.md +++ b/tests/testthat/_snaps/deprecated.md @@ -2,6 +2,6 @@ Code opencage_key(quiet = FALSE) - Message + Message Using OpenCage API Key from envvar OPENCAGE_KEY diff --git a/tests/testthat/_snaps/oc_check_query.md b/tests/testthat/_snaps/oc_check_query.md index 9232ab49..b06b5c95 100644 --- a/tests/testthat/_snaps/oc_check_query.md +++ b/tests/testthat/_snaps/oc_check_query.md @@ -2,41 +2,47 @@ Code oc_check_between(symbol, 0, 10) - Error - Every `symbol` must be between 0 and 10. + Condition + Error: + ! Every `symbol` must be between 0 and 10. --- Code oc_check_between(symbol, 11.0001, 11.0002) - Error - Every `symbol` must be between 11.0001 and 11.0002. + Condition + Error: + ! Every `symbol` must be between 11.0001 and 11.0002. --- Code oc_check_between(symbol, 0L, 10L) - Error - Every `symbol` must be between 0 and 10. + Condition + Error: + ! Every `symbol` must be between 0 and 10. --- Code oc_check_between(symbol, 11.0001, 11.0002) - Error - Every `symbol` must be between 11.0001 and 11.0002. + Condition + Error: + ! Every `symbol` must be between 11.0001 and 11.0002. --- Code oc_check_between(symbol, 0, 11) - Error - Every `symbol` must be numeric. + Condition + Error: + ! Every `symbol` must be numeric. --- Code oc_check_between(symbol, 0, 11) - Error - Every `symbol` must be numeric. + Condition + Error: + ! Every `symbol` must be numeric. diff --git a/tests/testthat/helper-opencage.R b/tests/testthat/helper-opencage.R index af474e1e..61c94a4b 100644 --- a/tests/testthat/helper-opencage.R +++ b/tests/testthat/helper-opencage.R @@ -27,7 +27,7 @@ skip_if_no_key <- function() { ## forward ----------------------------------------------------------------- -oc_locs <- function() c("Nantes", "Flensburg", "Los Angeles") +oc_locs <- function() c("Brest", "Flensburg", "Los Angeles") oc_fw1 <- function() tibble::tibble(id = 1:3, loc = oc_locs()) @@ -35,19 +35,18 @@ oc_fw2 <- function() { tibble::add_column( oc_fw1(), bounds = oc_bbox( - xmin = c(-72, -98, -73), - ymin = c(45, 43, -38), - xmax = c(-70, -90, -71), - ymax = c(46, 49, -36) + xmin = c(17, -98, -73), + ymin = c(49, 43, -38), + xmax = c(18, -90, -71), + ymax = c(50, 49, -36) ), proximity = oc_points( - latitude = c(45.5, 46, -37), - longitude = c(-71, -95, -72) + latitude = c(49.3, 46, -37), + longitude = c(17.4, -95, -72) ), - countrycode = c("ca", "us", "cl"), + countrycode = c("cz", "us", "cl"), language = c("de", "fr", "ja"), limit = 1:3, - confidence = c(7, 9, 5), annotation = c(FALSE, TRUE, TRUE), abbrv = c(FALSE, FALSE, TRUE), address_only = c(TRUE, FALSE, FALSE) @@ -57,15 +56,15 @@ oc_fw2 <- function() { oc_fw3 <- function() { tibble::tibble( id = 1:3, - loc = c("Nantes", "Elbphilharmonie Hamburg", "Los Angeles City Hall"), + loc = c("Brest", "Elbphilharmonie Hamburg", "Los Angeles City Hall"), roadinfo = c(FALSE, TRUE, TRUE) ) } ## reverse ----------------------------------------------------------------- -oc_lat1 <- function() c(47.21864, 53.55034, 34.05369) -oc_lng1 <- function() c(-1.554136, 10.000654, -118.242767) +oc_lat1 <- function() c(47.21947, 53.55034, 34.05369) +oc_lng1 <- function() c(-1.54754, 10.000654, -118.242767) oc_rev1 <- function() tibble::tibble(id = 1:3, lat = oc_lat1(), lng = oc_lng1()) @@ -73,7 +72,6 @@ oc_rev2 <- function() { tibble::add_column( oc_rev1(), language = c("en", "fr", "ja"), - confidence = rep(1L, 3L), annotation = c(FALSE, TRUE, TRUE), roadinfo = c(FALSE, TRUE, TRUE), abbrv = c(FALSE, FALSE, TRUE), @@ -82,5 +80,5 @@ oc_rev2 <- function() { } oc_rev3 <- function() { - tibble::add_row(oc_rev2(), id = 4, lat = 25, lng = 36, confidence = 5) + tibble::add_row(oc_rev2(), id = 4, lat = 25, lng = 36) } diff --git a/tests/testthat/test-deprecated.R b/tests/testthat/test-deprecated.R index c1adc714..87c7b5e8 100644 --- a/tests/testthat/test-deprecated.R +++ b/tests/testthat/test-deprecated.R @@ -28,7 +28,6 @@ test_that("opencage_forward/opencage_reverse return what they should results <- opencage_forward( placename = "Paris", limit = 2, - min_confidence = 5, language = "fr", no_annotations = TRUE ) @@ -44,7 +43,6 @@ test_that("opencage_forward/opencage_reverse return what they should results <- opencage_reverse( latitude = 44, longitude = 44, - min_confidence = 5, language = "pt-BR", no_annotations = TRUE ) @@ -68,7 +66,6 @@ test_that("opencage_forward deals well with results being NULL", { placename = "NOWHERE-INTERESTING", key = Sys.getenv("OPENCAGE_KEY"), limit = 2, - min_confidence = 5, language = "pt-BR", no_annotations = TRUE ) diff --git a/tests/testthat/test-oc_check_query.R b/tests/testthat/test-oc_check_query.R index 589885d3..95c7f7ef 100644 --- a/tests/testthat/test-oc_check_query.R +++ b/tests/testthat/test-oc_check_query.R @@ -152,16 +152,6 @@ test_that("oc_check_query checks limit", { ) }) -test_that("oc_check_query checks min_confidence", { - expect_error( - oc_check_query( - placename = "Sarzeau", - min_confidence = 20 - ), - "`min_confidence` must be an integer between 1 and 10." - ) -}) - test_that("oc_check_query checks no_annotations", { expect_error( oc_check_query( diff --git a/tests/testthat/test-oc_forward.R b/tests/testthat/test-oc_forward.R index cf089d56..d4c73bce 100644 --- a/tests/testthat/test-oc_forward.R +++ b/tests/testthat/test-oc_forward.R @@ -188,7 +188,8 @@ test_that("tidyeval works for arguments", { ## bounds, proximity and countrycode bounds <- oc_forward_df(oc_fw2(), loc, bounds = bounds, bind_cols = FALSE) prx <- oc_forward_df(oc_fw2(), loc, proximity = proximity, bind_cols = FALSE) - cc <- oc_forward_df(oc_fw2(), loc, countrycode = countrycode, bind_cols = FALSE) + cc <- + oc_forward_df(oc_fw2(), loc, countrycode = countrycode, bind_cols = FALSE) expect_false(identical(bounds, noarg)) expect_false(identical(prx, noarg)) expect_false(identical(cc, noarg)) @@ -207,21 +208,6 @@ test_that("tidyeval works for arguments", { expect_identical(nrow(limit), 6L) expect_identical(limit$id, c(1L, 2L, 2L, 3L, 3L, 3L)) - # min_confidence - confidence <- oc_forward_df( - oc_fw2(), - loc, - min_confidence = confidence, - bind_cols = FALSE - ) - - # make sure we get actual results, not only NA - expect_false(anyNA(confidence$oc_formatted)) - - expect_false(identical(confidence[1, ], noarg[1, ])) - expect_false(identical(confidence[2, ], noarg[2, ])) - expect_false(identical(confidence[3, ], noarg[3, ])) - # no_annotations ann <- oc_forward_df( diff --git a/tests/testthat/test-oc_process.R b/tests/testthat/test-oc_process.R index 00ea72c4..e3663259 100644 --- a/tests/testthat/test-oc_process.R +++ b/tests/testthat/test-oc_process.R @@ -226,7 +226,6 @@ test_that("oc_process handles various other arguments.", { placename = "Hamburg", return = "url_only", limit = 1L, - min_confidence = NULL, no_annotations = FALSE, roadinfo = FALSE, no_dedupe = FALSE, @@ -235,7 +234,6 @@ test_that("oc_process handles various other arguments.", { add_request = FALSE ) expect_match(res1[[1]], "&limit=1", fixed = TRUE) - expect_false(grepl(pattern = "min_confidence", x = res1[[1]], fixed = TRUE)) expect_match(res1[[1]], "&no_annotations=0", fixed = TRUE) expect_match(res1[[1]], "&roadinfo=0", fixed = TRUE) expect_match(res1[[1]], "&no_dedupe=0", fixed = TRUE) @@ -247,7 +245,6 @@ test_that("oc_process handles various other arguments.", { placename = "Hamburg", return = "url_only", limit = 10, - min_confidence = 8, no_annotations = TRUE, roadinfo = TRUE, no_dedupe = TRUE, @@ -256,7 +253,6 @@ test_that("oc_process handles various other arguments.", { add_request = TRUE ) expect_match(res2[[1]], "&limit=10", fixed = TRUE) - expect_match(res2[[1]], "&min_confidence=8", fixed = TRUE) expect_match(res2[[1]], "&no_annotations=1", fixed = TRUE) expect_match(res2[[1]], "&roadinfo=1", fixed = TRUE) expect_match(res2[[1]], "&no_dedupe=1", fixed = TRUE) @@ -268,7 +264,6 @@ test_that("oc_process handles various other arguments.", { placename = c("Hamburg", "Hamburg"), return = "url_only", limit = c(10L, 5L), - min_confidence = c(8L, 5L), no_annotations = c(TRUE, FALSE), roadinfo = c(TRUE, FALSE), no_dedupe = c(TRUE, FALSE), @@ -278,8 +273,6 @@ test_that("oc_process handles various other arguments.", { ) expect_match(res3[[1]], "&limit=10", fixed = TRUE) expect_match(res3[[2]], "&limit=5", fixed = TRUE) - expect_match(res3[[1]], "&min_confidence=8", fixed = TRUE) - expect_match(res3[[2]], "&min_confidence=5", fixed = TRUE) expect_match(res3[[1]], "&no_annotations=1", fixed = TRUE) expect_match(res3[[2]], "&no_annotations=0", fixed = TRUE) expect_match(res3[[1]], "&roadinfo=1", fixed = TRUE) @@ -304,7 +297,6 @@ test_that("arguments that are NULL or NA don't show up in url.", { proximity = NULL, language = NULL, countrycode = NULL, - min_confidence = NULL, roadinfo = NULL, no_annotations = NULL, no_dedupe = NULL, @@ -318,7 +310,6 @@ test_that("arguments that are NULL or NA don't show up in url.", { expect_match(res_null[[1]], "^((?!proximity=).)*$", perl = TRUE) expect_match(res_null[[1]], "^((?!language=).)*$", perl = TRUE) expect_match(res_null[[1]], "^((?!countrycode=).)*$", perl = TRUE) - expect_match(res_null[[1]], "^((?!min_confidence=).)*$", perl = TRUE) expect_match(res_null[[1]], "^((?!no_annotations=).)*$", perl = TRUE) expect_match(res_null[[1]], "^((?!roadinfo=).)*$", perl = TRUE) expect_match(res_null[[1]], "^((?!no_dedupe=).)*$", perl = TRUE) @@ -334,7 +325,6 @@ test_that("arguments that are NULL or NA don't show up in url.", { proximity = list(), language = NA_character_, countrycode = NA_character_, - min_confidence = NA, no_annotations = NA, roadinfo = NA, no_dedupe = NA, @@ -348,7 +338,6 @@ test_that("arguments that are NULL or NA don't show up in url.", { expect_match(res_na[[1]], "^((?!proximity=).)*$", perl = TRUE) expect_match(res_na[[1]], "^((?!language=).)*$", perl = TRUE) expect_match(res_na[[1]], "^((?!countrycode=).)*$", perl = TRUE) - expect_match(res_na[[1]], "^((?!min_confidence=).)*$", perl = TRUE) expect_match(res_na[[1]], "^((?!no_annotations=).)*$", perl = TRUE) expect_match(res_na[[1]], "^((?!roadinfo=).)*$", perl = TRUE) expect_match(res_na[[1]], "^((?!no_dedupe=).)*$", perl = TRUE) diff --git a/tests/testthat/test-oc_reverse.R b/tests/testthat/test-oc_reverse.R index fc4b6ee0..652cb5a2 100644 --- a/tests/testthat/test-oc_reverse.R +++ b/tests/testthat/test-oc_reverse.R @@ -181,21 +181,10 @@ test_that("tidyeval works for arguments", { noarg <- oc_reverse_df(oc_rev2(), lat, lng) # language - lang <- oc_reverse_df(oc_rev2(), lat, lng, language = language, output = "all") + lang <- + oc_reverse_df(oc_rev2(), lat, lng, language = language, output = "all") expect_identical(lang$oc_country, c("France", "Allemagne", "アメリカ合衆国")) - # min_confidence - confidence <- oc_reverse_df(oc_rev3(), lat, lng, min_confidence = confidence) - no_con <- oc_reverse_df(oc_rev3(), lat, lng) - - expect_identical(confidence[1, ], no_con[1, ]) - expect_identical(confidence[2, ], no_con[2, ]) - expect_identical(confidence[3, ], no_con[3, ]) - expect_false(identical( - confidence[[4, "oc_formatted"]], - no_con[[4, "oc_formatted"]] - )) - # no_annotations ann <- oc_reverse_df( @@ -228,7 +217,8 @@ test_that("tidyeval works for arguments", { )) # address_only - address_only <- oc_reverse_df(oc_rev2(), lat, lng, address_only = address_only) + address_only <- + oc_reverse_df(oc_rev2(), lat, lng, address_only = address_only) expect_false(identical( address_only["oc_formatted"], noarg["oc_formatted"] diff --git a/vignettes/customise_query.Rmd b/vignettes/customise_query.Rmd index 0a5ea07e..51576191 100644 --- a/vignettes/customise_query.Rmd +++ b/vignettes/customise_query.Rmd @@ -2,7 +2,7 @@ title: "Customise your query" subtitle: "Get more and better results from OpenCage" author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon" -date: "2023-01-10" +date: "2024-12-31" description: > "The OpenCage API supports about a dozen parameters to customise a query and here we will explain how to use them." output: @@ -31,24 +31,21 @@ To receive more results, modify the `limit` argument, which specifies the maximu Integer values between 1 and 100 are allowed. -```r -oc_forward_df("Berlin") +``` r +oc_forward_df("Paris") #> # A tibble: 1 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Berlin 52.5 13.4 Berlin, Germany +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Paris 48.9 2.32 Paris, France ``` -```r -oc_forward_df("Berlin", limit = 5) -#> # A tibble: 5 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Berlin 52.5 13.4 Berlin, Germany -#> 2 Berlin 44.5 -71.2 Berlin, NH 03570, United States of America -#> 3 Berlin 52.5 13.4 Berlin Ostbahnhof, Mitteltunnel, 10243 Berlin, Germany -#> 4 Berlin 39.8 -89.9 Berlin, Sangamon County, Illinois, United States of America -#> 5 Berlin 41.6 -72.7 Berlin, Connecticut, United States of America +``` r +oc_forward_df("Paris", limit = 5) +#> # A tibble: 2 × 4 +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Paris 48.9 2.35 Paris, France +#> 2 Paris 33.7 -95.6 Paris, Texas, United States of America ``` @@ -58,18 +55,19 @@ Therefore, `oc_reverse_df()` does not support the `limit` argument. OpenCage may sometimes have more than one record of one place. Duplicated records are not returned by default. If you set the `no_dedupe` argument to `TRUE`, you will receive duplicated results when available. - - -```r -oc_forward_df("Berlin", limit = 5, no_dedupe = TRUE) -#> # A tibble: 5 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Berlin 52.5 13.4 Berlin, Germany -#> 2 Berlin 44.5 -71.2 Berlin, NH 03570, United States of America -#> 3 Berlin 52.5 13.4 Berlin Ostbahnhof, Mitteltunnel, 10243 Berlin, Germany -#> 4 Berlin 39.8 -89.9 Berlin, Sangamon County, Illinois, United States of America -#> 5 Berlin 41.6 -72.7 Berlin, Connecticut, United States of America +(Yes, inverted argument names are confusing, but we just follow [OpenCage's lead](https://opencagedata.com/api#optional-params) here. +So, `no_dedupe = TRUE` means that you want duplicates.) + + +``` r +oc_forward_df("Paris", limit = 5, no_dedupe = TRUE) +#> # A tibble: 4 × 4 +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Paris 48.9 2.35 Paris, France +#> 2 Paris 48.9 2.32 Paris, France +#> 3 Paris 33.7 -95.6 Paris, Texas, United States of America +#> 4 Paris 48.9 2.32 Paris, France ``` ## Better targeted results @@ -87,38 +85,39 @@ The country code is a two letter code as defined by the [ISO 3166-1 Alpha 2](htt E.g. "AR" for Argentina, "FR" for France, and "NZ" for the New Zealand. -```r +``` r oc_forward_df(placename = "Paris", countrycode = "US", limit = 5) #> # A tibble: 5 × 4 #> placename oc_lat oc_lng oc_formatted #> #> 1 Paris 33.7 -95.6 Paris, Texas, United States of America -#> 2 Paris 38.2 -84.3 Paris, KY 40361, United States of America +#> 2 Paris 38.2 -84.3 Paris, Kentucky, United States of America #> 3 Paris 36.3 -88.3 Paris, Tennessee, United States of America -#> 4 Paris 39.6 -87.7 Paris, IL 61944, United States of America -#> 5 Paris 44.3 -70.5 Paris, 04281, United States of America +#> 4 Paris 44.2 -70.5 Paris, ME 04281, United States of America +#> 5 Paris 35.3 -93.7 Paris, Arkansas, United States of America ``` + Multiple countrycodes per `placename` must be wrapped in a list. Here is an example with places called "Paris" in Italy and Portugal. -```r +``` r oc_forward_df(placename = "Paris", countrycode = list(c("IT", "PT")), limit = 5) #> # A tibble: 5 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Paris 44.6 7.28 Brossasco, Cuneo, Italy -#> 2 Paris 46.5 10.4 23030 Valfurva SO, Italy -#> 3 Paris 37.4 -8.79 8670-320 São Teotónio, Portugal -#> 4 Paris 43.5 12.1 Paris, 52035 Monterchi AR, Italy -#> 5 Paris 43.8 11.3 Paris, Via dei Banchi, 50123 Florence FI, Italy +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Paris 46.5 10.4 23030 Valfurva SO, Italy +#> 2 Paris 44.6 7.28 Brossasco, Cuneo, Italy +#> 3 Paris 43.5 12.1 Paris, 52035 Monterchi AR, Italy +#> 4 Paris 37.4 -8.79 Paris, 7630-581 Odemira, Portugal +#> 5 Paris 45.7 13.1 Paris, Via dei Pini 22, 33054 Lignano Sabbiadoro Udine, Italy ``` Despite the name, country codes also exist for territories that are not independent states, e.g. Gibraltar ("GI"), Greenland ("GL"), Guadaloupe ("GP"), or Guam ("GU"). You can look up specific country codes with the {[ISOcodes](https://cran.r-project.org/package=ISOcodes)} or {[countrycodes](https://vincentarelbundock.github.io/countrycode/)} packages or on the [ISO](https://www.iso.org/obp/ui/#search/code/) or [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1) webpages. In fact, you can also look up country codes via OpenCage as well. If you were interested in the country code of Curaçao for example, you could run: -```r +``` r oc_forward_df("Curaçao", no_annotations = FALSE)["oc_iso_3166_1_alpha_2"] #> # A tibble: 1 × 1 #> oc_iso_3166_1_alpha_2 @@ -136,23 +135,23 @@ OpenCage provides a '[bounds-finder](https://opencagedata.com/bounds-finder)' to Below is an example of the use of `bounds` where the bounding box specifies the the South American continent. -```r +``` r oc_forward_df(placename = "Paris", bounds = oc_bbox(-97, -56, -32, 12), limit = 5) #> # A tibble: 5 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Paris 8.05 -80.6 Paris, Distrito Parita, Panama -#> 2 Paris -6.71 -69.9 Eirunepé, Região Geográfica Intermediária de Tefé, Brazil -#> 3 Paris -3.99 -79.2 110105, Loja, Ecuador -#> 4 Paris -13.5 -62.5 Canton Motegua, Municipio Baures, Provincia de Iténez, Bolivia -#> 5 Paris -23.5 -47.5 Paris, Jardim Santa Fé, Sorocaba - SP, Brazil +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Paris 8.05 -80.6 Paris, Distrito de Parita, Panama +#> 2 Paris -3.99 -79.2 110107, Loja, Ecuador +#> 3 Paris -6.71 -69.9 Eirunepé, Região Geográfica Intermediária de Tefé, Brazil +#> 4 Paris -13.5 -62.5 Canton Motegua, Municipio Baures, Provincia de Iténez, Bolivia +#> 5 Paris -23.5 -47.5 Jardim Santa Fé, Sorocaba, Região Metropolitana de Sorocaba, Brazil ``` Again, you can also use {opencage} to determine a bounding box for subsequent queries. If you wanted to see how many Plaça d'Espanya there are on the Balearic Islands, for example, you could find the appropriate bounding box and then search for the squares: -```r +``` r hi <- oc_forward_df(placename = "Balearic Islands", no_annotations = FALSE) hi_bbox <- @@ -164,28 +163,30 @@ hi_bbox <- ) oc_forward_df(placename = "Plaça d'Espanya", bounds = hi_bbox, limit = 20) -#> # A tibble: 16 × 4 +#> # A tibble: 18 × 4 #> placename oc_lat oc_lng oc_formatted #> -#> 1 Plaça d'Espanya 39.6 2.65 Plaça d'Espanya, Carrer d'Eusebi Estada, 07005 Palma, Spain +#> 1 Plaça d'Espanya 39.6 2.65 Plaça d'Espanya, Carrer d'Eusebi Estada, 07003 Palma, Spain #> 2 Plaça d'Espanya 39.6 2.65 Plaça d'Espanya, Canavall, Palma, Balearic Islands, Spain -#> 3 Plaça d'Espanya 39.0 1.53 Plaça d'Espanya, Santa Eulària des Riu, Balearic Islands, Spain +#> 3 Plaça d'Espanya 39.5 2.89 Plaça d'Espanya, 07620 Llucmajor, Spain #> 4 Plaça d'Espanya 39.0 1.30 Plaça d'Espanya, 07820 Sant Antoni de Portmany, Spain -#> 5 Plaça d'Espanya 39.9 4.27 Plaça d'Espanya, Maó, Spain -#> 6 Plaça d'Espanya 39.5 3.15 Plaça d'Espanya, 07200 Felanich, Spain -#> 7 Plaça d'Espanya 39.0 1.53 Plaça d'Espanya, 07840 Santa Eulària des Riu, Spain -#> 8 Plaça d'Espanya 39.6 2.65 Plaça d'Espanya, 07002 Palma, Spain -#> 9 Plaça d'Espanya 39.9 4.27 Plaça d'Espanya, 07701 Maó, Spain -#> 10 Plaça d'Espanya 38.9 1.44 Plaça d'Espanya, Ibiza, Spain -#> 11 Plaça d'Espanya 39.8 2.72 Plaça d'Espanya, Sóller, Spain -#> 12 Plaça d'Espanya 39.7 2.91 Plaça d'Espanya, Inca, Spain -#> 13 Plaça d'Espanya 39.6 2.42 plaça d'Espanya, Andratx, Spain -#> 14 Plaça d'Espanya 39.6 2.75 Plaça d'Espanya, Marratxí, Spain -#> 15 Plaça d'Espanya 39.6 2.90 Plaça d'Espanya, 07140 Sencelles, Spain -#> 16 Plaça d'Espanya 39.8 2.74 Plaça d'Espanya, Fornalutx, Spain +#> 5 Plaça d'Espanya 39.0 1.53 Plaça d'Espanya, Santa Eulària des Riu, Balearic Islands, Spain +#> 6 Plaça d'Espanya 38.9 1.44 Plaça d'Espanya, 07800 Ibiza, Spain +#> 7 Plaça d'Espanya 39.9 4.27 Plaça d'Espanya, Maó, Spain +#> 8 Plaça d'Espanya 39.1 1.51 Plaça d'Espanya, Sant Joan de Labritja, Spain +#> 9 Plaça d'Espanya 39.6 2.65 Plaça d'Espanya, 07002 Palma, Spain +#> 10 Plaça d'Espanya 39.8 2.72 Plaça d'Espanya, 07100 Sóller, Spain +#> 11 Plaça d'Espanya 39.6 2.90 Plaça d'Espanya, 07140 Sencelles, Spain +#> 12 Plaça d'Espanya 39.6 2.75 Plaça d'Espanya, 07141 Marratxí, Spain +#> 13 Plaça d'Espanya 39.7 2.91 Plaça d'Espanya, 07300 Inca, Spain +#> 14 Plaça d'Espanya 39.8 2.74 Plaça d'Espanya, 07109 Fornalutx, Spain +#> 15 Plaça d'Espanya 39.5 3.15 Plaça d'Espanya, 07200 Felanitx, Spain +#> 16 Plaça d'Espanya 39.6 2.42 plaça d'Espanya, 07150 Andratx, Spain +#> 17 Plaça d'Espanya 39.5 2.58 Plaça d'Espanya, 07181 Bendinat, Spain +#> 18 Plaça d'Espanya 39.0 1.53 Plaça d'Espanya, 07840 Santa Eulària des Riu, Spain ``` -Note that OpenCage does not support point-of-interest or feature search, like "show me all bus stops in this area". +Note that OpenCage does not support point-of-interest or feature search, like "show me all bus stops in this area". If you are more interested in these kind of features, you might want to take a look at the {[osmdata](https://docs.ropensci.org/osmdata/)} package. ### `proximity` @@ -198,21 +199,19 @@ For example, `proximity = oc_point(38.0, -84.5)`, if you happen to already know If not, you can also look them up with {opencage}, of course: -```r +``` r lx <- oc_forward_df("Lexington, Kentucky") lx_point <- oc_points(lx$oc_lat, lx$oc_lng) oc_forward_df(placename = "Paris", proximity = lx_point, limit = 5) -#> # A tibble: 5 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Paris 38.2 -84.3 Paris, KY 40361, United States of America -#> 2 Paris 48.9 2.32 Paris, Ile-de-France, France -#> 3 Paris 39.6 -87.7 Paris, IL 61944, United States of America -#> 4 Paris 38.8 -85.6 Paris, Jennings County, IN 47230, United States of America -#> 5 Paris 33.7 -95.6 Paris, Texas, United States of America +#> # A tibble: 2 × 4 +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Paris 38.2 -84.3 Paris, Kentucky, United States of America +#> 2 Paris 48.9 2.35 Paris, France ``` + Note that the French capital is listed before other places in the US, which are closer to the point provided. This illustrates how `proximity` is only one of many factors influencing the ranking of results. @@ -223,16 +222,12 @@ When you specify `min_confidence`, only results with at least the requested conf Thus, in the following example, the French capital is too large to be returned. -```r +``` r oc_forward_df(placename = "Paris", min_confidence = 7, limit = 5) -#> # A tibble: 5 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Paris 38.2 -84.3 Paris, KY 40361, United States of America -#> 2 Paris 36.3 -88.3 Paris, Tennessee, United States of America -#> 3 Paris 39.6 -87.7 Paris, IL 61944, United States of America -#> 4 Paris 35.3 -93.7 Paris, Logan County, AR 72855, United States of America -#> 5 Paris 43.0 -75.3 Paris, Oneida County, New York, United States of America +#> # A tibble: 1 × 4 +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Paris NA NA ``` Note that confidence is not used for the [ranking of results](https://opencagedata.com/api#ranking). @@ -249,7 +244,7 @@ If you would like to get your results in a specific language, you can pass an [I OpenCage will attempt to return results in that language. -```r +``` r oc_forward_df(placename = "Munich", language = "tr") #> # A tibble: 1 × 4 #> placename oc_lat oc_lng oc_formatted @@ -261,7 +256,7 @@ Alternatively, you can specify the "native" tag, in which case OpenCage will att Keep in mind, however, that some countries have more than one official language or that the official language may not be the one actually used day-to-day. -```r +``` r oc_forward_df(placename = "Munich", language = "native") #> # A tibble: 1 × 4 #> placename oc_lat oc_lng oc_formatted @@ -272,7 +267,7 @@ oc_forward_df(placename = "Munich", language = "native") If the `language` parameter is set to `NULL` (which is the default), the tag is not recognized, or OpenCage does not have a record in that language, the results will be returned in English. -```r +``` r oc_forward_df(placename = "München") #> # A tibble: 1 × 4 #> placename oc_lat oc_lng oc_formatted @@ -296,24 +291,38 @@ Some annotations, like the [Irish Transverse Mercator](https://en.wikipedia.org/ Whether the annotations are shown, is controlled by the `no_annotations` argument. It is `TRUE` by default, which means that the output will _not_ contain annotations. -(Yes, inverted argument names are confusing, but we just follow OpenCage's lead here.) When you set `no_annotations` to `FALSE`, all columns are returned (i.e. `output` is implicitly set to `"all"`). -This leads to a result with a lot of columns. - - -```r -oc_forward_df("Dublin", no_annotations = FALSE) -#> # A tibble: 1 × 70 -#> placen…¹ oc_lat oc_lng oc_co…² oc_fo…³ oc_mgrs oc_ma…⁴ oc_ca…⁵ oc_flag oc_ge…⁶ oc_qi…⁷ oc_wi…⁸ oc_dm…⁹ oc_dm…˟ oc_it…˟ oc_it…˟ -#> -#> 1 Dublin 53.3 -6.26 5 Dublin… 29UPV8… IO63ui… 353 "\U000… gc7x98… 114. Q1761 53° 20… 6° 15'… 715826… 734697… -#> # … with 54 more variables: oc_mercator_x , oc_mercator_y , oc_osm_edit_url , oc_osm_note_url , -#> # oc_osm_url , oc_un_m49_statistical_groupings , oc_un_m49_regions_europe , oc_un_m49_regions_ie , -#> # oc_un_m49_regions_northern_europe , oc_un_m49_regions_world , oc_currency_alternate_symbols , -#> # oc_currency_decimal_mark , oc_currency_html_entity , oc_currency_iso_code , oc_currency_iso_numeric , -#> # oc_currency_name , oc_currency_smallest_denomination , oc_currency_subunit , -#> # oc_currency_subunit_to_unit , oc_currency_symbol , oc_currency_symbol_first , -#> # oc_currency_thousands_separator , oc_roadinfo_drive_on , oc_roadinfo_speed_in , … +This leads to a result with a _lot_ of columns. + + +``` r +oc_forward_df("Dublin", no_annotations = FALSE) |> colnames() +#> [1] "placename" "oc_lat" "oc_lng" +#> [4] "oc_confidence" "oc_formatted" "oc_mgrs" +#> [7] "oc_maidenhead" "oc_callingcode" "oc_flag" +#> [10] "oc_geohash" "oc_qibla" "oc_wikidata" +#> [13] "oc_dms_lat" "oc_dms_lng" "oc_itm_easting" +#> [16] "oc_itm_northing" "oc_mercator_x" "oc_mercator_y" +#> [19] "oc_nuts_nuts0_code" "oc_nuts_nuts1_code" "oc_nuts_nuts2_code" +#> [22] "oc_nuts_nuts3_code" "oc_osm_edit_url" "oc_osm_note_url" +#> [25] "oc_osm_url" "oc_un_m49_statistical_groupings" "oc_un_m49_regions_europe" +#> [28] "oc_un_m49_regions_ie" "oc_un_m49_regions_northern_europe" "oc_un_m49_regions_world" +#> [31] "oc_currency_alternate_symbols" "oc_currency_decimal_mark" "oc_currency_html_entity" +#> [34] "oc_currency_iso_code" "oc_currency_iso_numeric" "oc_currency_name" +#> [37] "oc_currency_smallest_denomination" "oc_currency_subunit" "oc_currency_subunit_to_unit" +#> [40] "oc_currency_symbol" "oc_currency_symbol_first" "oc_currency_thousands_separator" +#> [43] "oc_roadinfo_drive_on" "oc_roadinfo_speed_in" "oc_sun_rise_apparent" +#> [46] "oc_sun_rise_astronomical" "oc_sun_rise_civil" "oc_sun_rise_nautical" +#> [49] "oc_sun_set_apparent" "oc_sun_set_astronomical" "oc_sun_set_civil" +#> [52] "oc_sun_set_nautical" "oc_timezone_name" "oc_timezone_now_in_dst" +#> [55] "oc_timezone_offset_sec" "oc_timezone_offset_string" "oc_timezone_short_name" +#> [58] "oc_what3words_words" "oc_northeast_lat" "oc_northeast_lng" +#> [61] "oc_southwest_lat" "oc_southwest_lng" "oc_iso_3166_1_alpha_2" +#> [64] "oc_iso_3166_1_alpha_3" "oc_iso_3166_2" "oc_category" +#> [67] "oc_normalized_city" "oc_type" "oc_city" +#> [70] "oc_continent" "oc_country" "oc_country_code" +#> [73] "oc_county" "oc_county_code" "oc_political_union" +#> [76] "oc_region" ``` ### `roadinfo` @@ -323,19 +332,16 @@ It is `FALSE` by default, which means OpenCage will not attempt to match the nea Some road and driving information is nevertheless provided as part of the annotations (see above), even when `roadinfo` is set to `FALSE`. -```r -oc_forward_df(placename = c("Europa Advance Rd", "Bovoni Rd"), roadinfo = TRUE) -#> # A tibble: 2 × 30 -#> placen…¹ oc_lat oc_lng oc_co…² oc_fo…³ oc_ro…⁴ oc_ro…⁵ oc_ro…⁶ oc_ro…⁷ oc_ro…⁸ oc_ro…⁹ oc_no…˟ oc_no…˟ oc_so…˟ oc_so…˟ oc_is…˟ -#> -#> 1 Europa … 36.1 -5.34 9 Europa… right yes Europa… second… km/h asphalt 36.1 -5.34 36.1 -5.35 GI -#> 2 Bovoni … 18.3 -64.9 8 Bovoni… left Bovoni… primary mph 18.3 -64.9 18.3 -64.9 VI -#> # … with 14 more variables: oc_iso_3166_1_alpha_3 , oc_category , oc_type , oc_city , oc_continent , -#> # oc_country , oc_country_code , oc_postcode , oc_road , oc_road_type , oc_iso_3166_2 , -#> # oc_county , oc_state , oc_state_code , and abbreviated variable names ¹​placename, ²​oc_confidence, -#> # ³​oc_formatted, ⁴​oc_roadinfo_drive_on, ⁵​oc_roadinfo_oneway, ⁶​oc_roadinfo_road, ⁷​oc_roadinfo_road_type, -#> # ⁸​oc_roadinfo_speed_in, ⁹​oc_roadinfo_surface, ˟​oc_northeast_lat, ˟​oc_northeast_lng, ˟​oc_southwest_lat, ˟​oc_southwest_lng, -#> # ˟​oc_iso_3166_1_alpha_2 +``` r +library(dplyr, warn.conflicts = FALSE) +oc_forward_df(placename = c("Europa Advance Rd", "Bovoni Rd"), roadinfo = TRUE) |> +select(placename, contains("roadinfo")) +#> # A tibble: 2 × 8 +#> placename oc_roadinfo_drive_on oc_roadinfo_lanes oc_roadinfo_oneway oc_roadinfo_road oc_roadinfo_road_type +#> +#> 1 Europa Advance Rd right 1 yes Europa Advance Road secondary +#> 2 Bovoni Rd left NA Bovoni Bay Trail residential +#> # ℹ 2 more variables: oc_roadinfo_speed_in , oc_roadinfo_surface ``` A [blog post](https://blog.opencagedata.com/post/new-optional-parameter-roadinfo) provides more details. @@ -346,7 +352,7 @@ The geocoding functions also have an `abbr` parameter, which is `FALSE` by defau When it is `TRUE`, the addresses in the `formatted` field of the results are abbreviated (e.g. "Main St." instead of "Main Street"). -```r +``` r oc_forward_df("Wall Street") #> # A tibble: 1 × 4 #> placename oc_lat oc_lng oc_formatted @@ -363,21 +369,21 @@ See [this blog post](https://blog.opencagedata.com/post/160294347883/shrtr-pls) ### `address_only` -When `address_only` is set to `TRUE` (by default `FALSE`), OpenCage will attempt to exclude names of points-of-interests from the `formatted` field of the results. +When `address_only` is set to `TRUE` (by default `FALSE`), OpenCage will attempt to exclude names of points-of-interests from the `formatted` field of the results. In the following example, the POI "Hôtel de ville de Nantes" (town hall of Nantes) is removed from the `oc_formatted` column with `address_only = TRUE`. -```r -oc_reverse_df(47.21864, -1.55413) +``` r +oc_reverse_df(47.21947, -1.54754) #> # A tibble: 1 × 3 -#> latitude longitude oc_formatted -#> -#> 1 47.2 -1.55 Hôtel de ville de Nantes, Place de l'Hôtel de Ville, 44000 Nantes, France -oc_reverse_df(47.21864, -1.55413, address_only = TRUE) +#> latitude longitude oc_formatted +#> +#> 1 47.2 -1.55 Le Palais, 37 Rue Gambetta, 44013 Nantes, France +oc_reverse_df(47.21947, -1.54754, address_only = TRUE) #> # A tibble: 1 × 3 -#> latitude longitude oc_formatted -#> -#> 1 47.2 -1.55 Place de l'Hôtel de Ville, 44000 Nantes, France +#> latitude longitude oc_formatted +#> +#> 1 47.2 -1.55 37 Rue Gambetta, 44013 Nantes, France ``` ## Vectorised arguments @@ -385,7 +391,7 @@ oc_reverse_df(47.21864, -1.55413, address_only = TRUE) All of the function arguments mentioned above are vectorised, so you can send queries like this: -```r +``` r oc_forward_df( placename = c("New York", "Rio", "Tokyo"), language = c("es", "de", "fr") @@ -401,7 +407,7 @@ oc_forward_df( Or geocode place names with country codes in a data frame: -```r +``` r for_df <- data.frame( location = c("Golden Gate Bridge", "Buckingham Palace", "Eiffel Tower"), @@ -410,29 +416,29 @@ for_df <- oc_forward_df(for_df, placename = location, countrycode = ccode) #> # A tibble: 3 × 5 -#> location ccode oc_lat oc_lng oc_formatted -#> -#> 1 Golden Gate Bridge at 47.6 15.8 Wiesenbauer, Martin's Golden Gate Bridge, 8684 Gemeinde Spital am Semmering, Austria -#> 2 Buckingham Palace cg -4.80 11.8 Buckingham Palace, Boulevard du Général Charles de Gaulle, Pointe-Noire, Congo-Brazzav… +#> location ccode oc_lat oc_lng oc_formatted +#> +#> 1 Golden Gate Bridge at 47.6 15.8 Wiesenbauer, Martin's Golden Gate Bridge, 8684 Steinhaus am Semmering, Austria +#> 2 Buckingham Palace cg -4.80 11.8 Buckingham Palace, Boulevard du Général Charles de Gaulle, Pointe-Noire, Congo-… #> 3 Eiffel Tower be 50.9 4.34 Eiffel Tower, Avenue de Bouchout - Boechoutlaan, 1020 Brussels, Belgium ``` This also works with `oc_reverse_df()`, of course. -```r +``` r rev_df <- data.frame( - lat = c(51.952659, 41.401372), - lon = c(7.632473, 2.128685) + lat = c(52.38772, 41.40137), + lon = c(9.73336, 2.12868) ) oc_reverse_df(rev_df, lat, lon, language = "native") #> # A tibble: 2 × 3 -#> lat lon oc_formatted -#> -#> 1 52.0 7.63 Friedrich-Ebert-Straße 7, 48153 Münster, Deutschland -#> 2 41.4 2.13 Carrer de Calatrava, 68, 08017 Barcelona, España +#> lat lon oc_formatted +#> +#> 1 52.4 9.73 Philipsbornstraße 2, 30165 Hannover, Deutschland +#> 2 41.4 2.13 Carrer de Calatrava, 64, 08017 Barcelona, España ``` ## Further information diff --git a/vignettes/customise_query.Rmd.src b/vignettes/customise_query.Rmd.src index 49f8127e..c02cf3d2 100644 --- a/vignettes/customise_query.Rmd.src +++ b/vignettes/customise_query.Rmd.src @@ -39,10 +39,10 @@ To receive more results, modify the `limit` argument, which specifies the maximu Integer values between 1 and 100 are allowed. ```{r limit1} -oc_forward_df("Berlin") +oc_forward_df("Paris") ``` ```{r limit2} -oc_forward_df("Berlin", limit = 5) +oc_forward_df("Paris", limit = 5) ``` @@ -52,9 +52,11 @@ Therefore, `oc_reverse_df()` does not support the `limit` argument. OpenCage may sometimes have more than one record of one place. Duplicated records are not returned by default. If you set the `no_dedupe` argument to `TRUE`, you will receive duplicated results when available. +(Yes, inverted argument names are confusing, but we just follow [OpenCage's lead](https://opencagedata.com/api#optional-params) here. +So, `no_dedupe = TRUE` means that you want duplicates.) ```{r dedupe} -oc_forward_df("Berlin", limit = 5, no_dedupe = TRUE) +oc_forward_df("Paris", limit = 5, no_dedupe = TRUE) ``` ## Better targeted results @@ -74,6 +76,7 @@ E.g. "AR" for Argentina, "FR" for France, and "NZ" for the New Zealand. ```{r countrycode} oc_forward_df(placename = "Paris", countrycode = "US", limit = 5) ``` + Multiple countrycodes per `placename` must be wrapped in a list. Here is an example with places called "Paris" in Italy and Portugal. @@ -119,7 +122,7 @@ oc_forward_df(placename = "Plaça d'Espanya", bounds = hi_bbox, limit = 20) ``` -Note that OpenCage does not support point-of-interest or feature search, like "show me all bus stops in this area". +Note that OpenCage does not support point-of-interest or feature search, like "show me all bus stops in this area". If you are more interested in these kind of features, you might want to take a look at the {[osmdata](https://docs.ropensci.org/osmdata/)} package. ### `proximity` @@ -138,6 +141,7 @@ lx_point <- oc_points(lx$oc_lat, lx$oc_lng) oc_forward_df(placename = "Paris", proximity = lx_point, limit = 5) ``` + Note that the French capital is listed before other places in the US, which are closer to the point provided. This illustrates how `proximity` is only one of many factors influencing the ranking of results. @@ -197,12 +201,11 @@ Some annotations, like the [Irish Transverse Mercator](https://en.wikipedia.org/ Whether the annotations are shown, is controlled by the `no_annotations` argument. It is `TRUE` by default, which means that the output will _not_ contain annotations. -(Yes, inverted argument names are confusing, but we just follow OpenCage's lead here.) When you set `no_annotations` to `FALSE`, all columns are returned (i.e. `output` is implicitly set to `"all"`). -This leads to a result with a lot of columns. +This leads to a result with a _lot_ of columns. ```{r annotations} -oc_forward_df("Dublin", no_annotations = FALSE) +oc_forward_df("Dublin", no_annotations = FALSE) |> colnames() ``` ### `roadinfo` @@ -212,7 +215,9 @@ It is `FALSE` by default, which means OpenCage will not attempt to match the nea Some road and driving information is nevertheless provided as part of the annotations (see above), even when `roadinfo` is set to `FALSE`. ```{r roadinfo} -oc_forward_df(placename = c("Europa Advance Rd", "Bovoni Rd"), roadinfo = TRUE) +library(dplyr, warn.conflicts = FALSE) +oc_forward_df(placename = c("Europa Advance Rd", "Bovoni Rd"), roadinfo = TRUE) |> +select(placename, contains("roadinfo")) ``` A [blog post](https://blog.opencagedata.com/post/new-optional-parameter-roadinfo) provides more details. @@ -231,12 +236,12 @@ See [this blog post](https://blog.opencagedata.com/post/160294347883/shrtr-pls) ### `address_only` -When `address_only` is set to `TRUE` (by default `FALSE`), OpenCage will attempt to exclude names of points-of-interests from the `formatted` field of the results. +When `address_only` is set to `TRUE` (by default `FALSE`), OpenCage will attempt to exclude names of points-of-interests from the `formatted` field of the results. In the following example, the POI "Hôtel de ville de Nantes" (town hall of Nantes) is removed from the `oc_formatted` column with `address_only = TRUE`. ```{r address-only} -oc_reverse_df(47.21864, -1.55413) -oc_reverse_df(47.21864, -1.55413, address_only = TRUE) +oc_reverse_df(47.21947, -1.54754) +oc_reverse_df(47.21947, -1.54754, address_only = TRUE) ``` ## Vectorised arguments @@ -267,8 +272,8 @@ This also works with `oc_reverse_df()`, of course. ```{r rev_df} rev_df <- data.frame( - lat = c(51.952659, 41.401372), - lon = c(7.632473, 2.128685) + lat = c(52.38772, 41.40137), + lon = c(9.73336, 2.12868) ) oc_reverse_df(rev_df, lat, lon, language = "native") diff --git a/vignettes/opencage.Rmd b/vignettes/opencage.Rmd index 6224becf..2a2c024d 100644 --- a/vignettes/opencage.Rmd +++ b/vignettes/opencage.Rmd @@ -2,7 +2,7 @@ title: "Introduction to opencage" subtitle: "Forward and Reverse Geocoding" author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon" -date: "2022-09-05" +date: "2024-12-31" description: > "Get started with the opencage R package to 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)." output: @@ -95,7 +95,7 @@ For now suffice it to say that your OpenCage API key will not be shown in any {o In sum, if you want to set your API key with {keyring}, set the rate limit to 10 (only do this if you have a paid account, please!), and do not want OpenCage to have records of your queries, you would configure {opencage} for the active session like this: -```r +``` r library("opencage") oc_config( key = keyring::key_get("opencage"), @@ -109,7 +109,7 @@ oc_config( Now you can start to geocode. Forward geocoding is from location name(s) to latitude and longitude tuple(s). -```r +``` r oc_forward_df(placename = "Sarzeau") #> # A tibble: 1 × 4 #> placename oc_lat oc_lng oc_formatted @@ -121,14 +121,14 @@ All geocoding functions are vectorised, i.e. you can geocode multiple locations Note that behind the scenes the requests are still sent to the API one-by-one. -```r +``` r opera <- c("Palacio de Bellas Artes", "Scala", "Sydney Opera House") oc_forward_df(placename = opera) #> # A tibble: 3 × 4 -#> placename oc_lat oc_lng oc_formatted -#> -#> 1 Palacio de Bellas Artes 19.4 -99.1 Palacio de Bellas Artes, Avenida Juárez, Centro Urbano, 06050, CMX, Mexico -#> 2 Scala 40.7 14.6 Scala, Salerno, Italy +#> placename oc_lat oc_lng oc_formatted +#> +#> 1 Palacio de Bellas Artes 19.4 -99.1 Palacio de Bellas Artes, Avenida Juárez, Barrio Chino, 06050 Mexico City, CMX, M… +#> 2 Scala 40.7 14.6 84010 Scala SA, Italy #> 3 Sydney Opera House -33.9 151. Sydney Opera House, 2 Macquarie Street, Sydney NSW 2000, Australia ``` @@ -138,20 +138,19 @@ If you specify `oc_forward_df(output = all)`, you will receive all result column Which columns you receive exactly depends on the information OpenCage returns for each specific request. -```r +``` r oc_forward_df(placename = opera, output = "all") -#> # A tibble: 3 × 31 -#> placename oc_lat oc_lng oc_co…¹ oc_fo…² oc_no…³ oc_no…⁴ oc_so…⁵ oc_so…⁶ oc_is…⁷ oc_is…⁸ oc_is…⁹ oc_ca…˟ oc_type oc_co…˟ -#> -#> 1 Palacio de B… 19.4 -99.1 9 Palaci… 19.4 -99.1 19.4 -99.1 MX MEX outdoo… museum North … -#> 2 Scala 40.7 14.6 7 Scala,… 40.7 14.6 40.6 14.6 IT ITA place city Europe -#> 3 Sydney Opera… -33.9 151. 9 Sydney… -33.9 151. -33.9 151. AU AUS outdoo… arts_c… Oceania -#> # … with 16 more variables: oc_country , oc_country_code , oc_museum , oc_neighbourhood , -#> # oc_postcode , oc_road , oc_state , oc_state_code , oc_city , oc_county , -#> # oc_county_code , oc_political_union , oc_arts_centre , oc_house_number , oc_municipality , -#> # oc_suburb , and abbreviated variable names ¹​oc_confidence, ²​oc_formatted, ³​oc_northeast_lat, ⁴​oc_northeast_lng, -#> # ⁵​oc_southwest_lat, ⁶​oc_southwest_lng, ⁷​oc_iso_3166_1_alpha_2, ⁸​oc_iso_3166_1_alpha_3, ⁹​oc_iso_3166_2, ˟​oc_category, -#> # ˟​oc_continent +#> # A tibble: 3 × 34 +#> placename oc_lat oc_lng oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng +#> +#> 1 Palacio d… 19.4 -99.1 9 Palacio de … 19.4 -99.1 19.4 -99.1 +#> 2 Scala 40.7 14.6 7 84010 Scala… 40.7 14.6 40.6 14.6 +#> 3 Sydney Op… -33.9 151. 9 Sydney Oper… -33.9 151. -33.9 151. +#> # ℹ 25 more variables: oc_iso_3166_1_alpha_2 , oc_iso_3166_1_alpha_3 , oc_iso_3166_2 , +#> # oc_category , oc_normalized_city , oc_type , oc_borough , oc_city , oc_continent , +#> # oc_country , oc_country_code , oc_museum , oc_neighbourhood , oc_postcode , oc_road , +#> # oc_state , oc_state_code , oc_county , oc_county_code , oc_political_union , +#> # oc_village , oc_attraction , oc_house_number , oc_municipality , oc_suburb ``` You can also pass a data frame to `oc_forward_df()`. @@ -159,7 +158,7 @@ By default the results columns are added to the input data frame, which is usefu If you want a data frame with only the geocoding results, set `bind_cols = FALSE`. -```r +``` r concert_df <- data.frame(location = c("Elbphilharmonie", "Concertgebouw", "Suntory Hall")) oc_forward_df(data = concert_df, placename = location) @@ -168,13 +167,13 @@ oc_forward_df(data = concert_df, placename = location) #> #> 1 Elbphilharmonie 53.5 9.98 Elbe Philharmonic Hall, Platz der Deutschen Einheit 1, 20457 Hamburg, Germany #> 2 Concertgebouw 52.4 4.88 Concertgebouw, Concertgebouwplein 2, 1071 LN Amsterdam, Netherlands -#> 3 Suntory Hall 35.7 140. Suntory Hall, Karayan Plaza, Azabu, Minato, 107-6090, Japan +#> 3 Suntory Hall 35.7 140. Suntory Hall, Karayan Plaza, Akasaka 1-chome, Minato, 107-6090, Japan ``` You can use it in a piped workflow as well. -```r +``` r library(dplyr, warn.conflicts = FALSE) concert_df %>% oc_forward_df(location) #> # A tibble: 3 × 4 @@ -182,7 +181,7 @@ concert_df %>% oc_forward_df(location) #> #> 1 Elbphilharmonie 53.5 9.98 Elbe Philharmonic Hall, Platz der Deutschen Einheit 1, 20457 Hamburg, Germany #> 2 Concertgebouw 52.4 4.88 Concertgebouw, Concertgebouwplein 2, 1071 LN Amsterdam, Netherlands -#> 3 Suntory Hall 35.7 140. Suntory Hall, Karayan Plaza, Azabu, Minato, 107-6090, Japan +#> 3 Suntory Hall 35.7 140. Suntory Hall, Karayan Plaza, Akasaka 1-chome, Minato, 107-6090, Japan ``` ## Reverse geocoding @@ -190,12 +189,12 @@ concert_df %>% oc_forward_df(location) Reverse geocoding works in the opposite direction of forward geocoding: from a pair of coordinates to the name and address most appropriate for the coordinates. -```r +``` r oc_reverse_df(latitude = 51.5034070, longitude = -0.1275920) #> # A tibble: 1 × 3 -#> latitude longitude oc_formatted -#> -#> 1 51.5 -0.128 10 Downing Street, London, SW1A 2AA, United Kingdom +#> latitude longitude oc_formatted +#> +#> 1 51.5 -0.128 10 Downing Street, Westminster, London, SW1A 2AA, United Kingdom ``` Note that all coordinates sent to the OpenCage API must adhere to the [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System) (also known as [EPSG:4326](https://epsg.io/4326)) [coordinate reference system](https://en.wikipedia.org/wiki/Spatial_reference_system) in decimal format. @@ -215,26 +214,26 @@ To minimize the number of requests sent to the API {opencage} uses {[memoise](ht -```r +``` r system.time(oc_reverse(latitude = 10, longitude = 10)) #> user system elapsed -#> 0.00 0.00 0.96 +#> 0.01 0.00 1.03 system.time(oc_reverse(latitude = 10, longitude = 10)) #> user system elapsed -#> 0.01 0.00 0.02 +#> 0.02 0.00 0.02 ``` To clear the cache of all results either start a new R session or call `oc_clear_cache()`. -```r +``` r oc_clear_cache() #> [1] TRUE system.time(oc_reverse(latitude = 10, longitude = 10)) #> user system elapsed -#> 0.01 0.00 0.91 +#> 0.01 0.00 1.11 ``` As you probably know, cache invalidation is one of the harder things to do in computer science. diff --git a/vignettes/output_options.Rmd b/vignettes/output_options.Rmd index 149cb5af..cf4315fd 100644 --- a/vignettes/output_options.Rmd +++ b/vignettes/output_options.Rmd @@ -2,7 +2,7 @@ title: "Output options" subtitle: "Get different kinds of output from OpenCage" author: "Daniel Possenriede, Jesse Sadler, Maëlle Salmon" -date: "2021-02-18" +date: "2024-12-31" description: > "`oc_forward()`/`oc_reverse()` return lists of various type, namely data frames, JSON, GeoJSON or URLs, depending on the `return` value you specify. The possible `return` values are `df_list`, `json_list`, `geojson_list` and `url_only`." output: @@ -32,31 +32,31 @@ The default return value is `df_list`. It returns a list of tibbles. -```r +``` r stations <- c("Casey Station", "McMurdo Station") oc_forward(stations, return = "df_list") #> [[1]] -#> # A tibble: 2 x 18 -#> oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_category oc_type oc_continent oc_hamlet -#> -#> 1 9 Casey Stati~ -66.3 111. -66.3 111. commerce office Antarctica Casey St~ -#> 2 9 Casey Stati~ NA NA NA NA travel/tou~ point_~ Antarctica -#> # ... with 8 more variables: oc_office , oc_iso_3166_1_alpha_2 , oc_iso_3166_1_alpha_3 , oc_country , -#> # oc_country_code , oc_point_of_interest , oc_lat , oc_lng +#> # A tibble: 1 × 15 +#> oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_iso_3166_1_alpha_2 +#> +#> 1 7 Casey Station,… -66.3 111. -66.3 111. AQ +#> # ℹ 8 more variables: oc_category , oc_normalized_city , oc_type , oc_continent , +#> # oc_country_code , oc_hamlet , oc_lat , oc_lng #> #> [[2]] -#> # A tibble: 1 x 12 -#> oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_category oc_type oc_continent oc_town -#> -#> 1 7 McMurdo Sta~ -77.8 167. -77.9 167. place city Antarctica McMurd~ -#> # ... with 2 more variables: oc_lat , oc_lng +#> # A tibble: 1 × 15 +#> oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_iso_3166_1_alpha_2 +#> +#> 1 7 McMurdo Statio… -77.8 167. -77.9 167. AQ +#> # ℹ 8 more variables: oc_category , oc_normalized_city , oc_type , oc_continent , +#> # oc_country_code , oc_town , oc_lat , oc_lng ``` The `df_list` type drives the `oc_forward_df()`/`oc_reverse_df()` functions. You can use the `df_list` output in a `dplyr::mutate()` chain to replicate the functionality of `oc_forward_df()`: -```r +``` r library(dplyr, warn.conflicts = FALSE) oc_data <- @@ -64,28 +64,27 @@ oc_data <- mutate(oc_result = oc_forward(place)) oc_data -#> # A tibble: 2 x 2 +#> # A tibble: 2 × 2 #> place oc_result #> -#> 1 Casey Station -#> 2 McMurdo Station +#> 1 Casey Station +#> 2 McMurdo Station ``` This creates a list column `oc_result`, which can be easily unnested with `tidyr::unnest()`: -```r +``` r library(tidyr, warn.conflicts = FALSE) oc_data %>% unnest(oc_result) -#> # A tibble: 3 x 20 -#> place oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng oc_category oc_type oc_continent -#> -#> 1 Case~ 9 Casey Stati~ -66.3 111. -66.3 111. commerce office Antarctica -#> 2 Case~ 9 Casey Stati~ NA NA NA NA travel/tou~ point_~ Antarctica -#> 3 McMu~ 7 McMurdo Sta~ -77.8 167. -77.9 167. place city Antarctica -#> # ... with 10 more variables: oc_hamlet , oc_office , oc_iso_3166_1_alpha_2 , oc_iso_3166_1_alpha_3 , -#> # oc_country , oc_country_code , oc_point_of_interest , oc_lat , oc_lng , oc_town +#> # A tibble: 2 × 17 +#> place oc_confidence oc_formatted oc_northeast_lat oc_northeast_lng oc_southwest_lat oc_southwest_lng +#> +#> 1 Casey Station 7 Casey Station, Antar… -66.3 111. -66.3 111. +#> 2 McMurdo Station 7 McMurdo Station, Ant… -77.8 167. -77.9 167. +#> # ℹ 10 more variables: oc_iso_3166_1_alpha_2 , oc_category , oc_normalized_city , oc_type , +#> # oc_continent , oc_country_code , oc_hamlet , oc_lat , oc_lng , oc_town ``` ## `json_list` @@ -93,7 +92,7 @@ oc_data %>% unnest(oc_result) OpenCage's main output format is JSON. When you specify `json_list` as the return type, you get the JSON as an R `list()`. -```r +``` r oc_forward("Casey Station", return = "json_list") #> [[1]] #> [[1]]$documentation @@ -114,92 +113,56 @@ oc_forward("Casey Station", return = "json_list") #> [[1]]$results[[1]]$bounds #> [[1]]$results[[1]]$bounds$northeast #> [[1]]$results[[1]]$bounds$northeast$lat -#> [1] -66.28255 +#> [1] -66.26209 #> #> [[1]]$results[[1]]$bounds$northeast$lng -#> [1] 110.5267 +#> [1] 110.5441 #> #> #> [[1]]$results[[1]]$bounds$southwest #> [[1]]$results[[1]]$bounds$southwest$lat -#> [1] -66.28265 +#> [1] -66.30209 #> #> [[1]]$results[[1]]$bounds$southwest$lng -#> [1] 110.5266 +#> [1] 110.5041 #> #> #> #> [[1]]$results[[1]]$components +#> [[1]]$results[[1]]$components$`ISO_3166-1_alpha-2` +#> [1] "AQ" +#> #> [[1]]$results[[1]]$components$`_category` -#> [1] "commerce" +#> [1] "place" +#> +#> [[1]]$results[[1]]$components$`_normalized_city` +#> [1] "Casey Station" #> #> [[1]]$results[[1]]$components$`_type` -#> [1] "office" +#> [1] "hamlet" #> #> [[1]]$results[[1]]$components$continent #> [1] "Antarctica" #> -#> [[1]]$results[[1]]$components$hamlet -#> [1] "Casey Station" +#> [[1]]$results[[1]]$components$country_code +#> [1] "aq" #> -#> [[1]]$results[[1]]$components$office +#> [[1]]$results[[1]]$components$hamlet #> [1] "Casey Station" #> #> #> [[1]]$results[[1]]$confidence -#> [1] 9 +#> [1] 7 #> #> [[1]]$results[[1]]$formatted -#> [1] "Casey Station" +#> [1] "Casey Station, Antarctica" #> #> [[1]]$results[[1]]$geometry #> [[1]]$results[[1]]$geometry$lat -#> [1] -66.2826 +#> [1] -66.28209 #> #> [[1]]$results[[1]]$geometry$lng -#> [1] 110.5266 -#> -#> -#> -#> [[1]]$results[[2]] -#> [[1]]$results[[2]]$components -#> [[1]]$results[[2]]$components$`ISO_3166-1_alpha-2` -#> [1] "AQ" -#> -#> [[1]]$results[[2]]$components$`ISO_3166-1_alpha-3` -#> [1] "ATA" -#> -#> [[1]]$results[[2]]$components$`_category` -#> [1] "travel/tourism" -#> -#> [[1]]$results[[2]]$components$`_type` -#> [1] "point_of_interest" -#> -#> [[1]]$results[[2]]$components$continent -#> [1] "Antarctica" -#> -#> [[1]]$results[[2]]$components$country -#> [1] "Antarctica" -#> -#> [[1]]$results[[2]]$components$country_code -#> [1] "aq" -#> -#> [[1]]$results[[2]]$components$point_of_interest -#> [1] "Casey Station" -#> -#> -#> [[1]]$results[[2]]$confidence -#> [1] 9 -#> -#> [[1]]$results[[2]]$formatted -#> [1] "Casey Station, Antarctica" -#> -#> [[1]]$results[[2]]$geometry -#> [[1]]$results[[2]]$geometry$lat -#> [1] -66.28225 -#> -#> [[1]]$results[[2]]$geometry$lng -#> [1] 110.5278 +#> [1] 110.5241 #> #> #> @@ -216,8 +179,8 @@ oc_forward("Casey Station", return = "json_list") #> [[1]]$stay_informed$blog #> [1] "https://blog.opencagedata.com" #> -#> [[1]]$stay_informed$twitter -#> [1] "https://twitter.com/OpenCage" +#> [[1]]$stay_informed$mastodon +#> [1] "https://en.osm.town/@opencage" #> #> #> [[1]]$thanks @@ -225,14 +188,14 @@ oc_forward("Casey Station", return = "json_list") #> #> [[1]]$timestamp #> [[1]]$timestamp$created_http -#> [1] "Thu, 18 Feb 2021 19:02:13 GMT" +#> [1] "Tue, 31 Dec 2024 10:46:25 GMT" #> #> [[1]]$timestamp$created_unix -#> [1] 1613674933 +#> [1] 1735641985 #> #> #> [[1]]$total_results -#> [1] 2 +#> [1] 1 ``` ## `geojson_list` @@ -240,7 +203,7 @@ oc_forward("Casey Station", return = "json_list") When you choose `geojson_list` as the return type, the geocoder response will be returned as GeoJSON specified as an R `list()`. -```r +``` r gjsn_lst <- oc_forward("Casey Station", return = "geojson_list") gjsn_lst #> [[1]] @@ -252,10 +215,10 @@ gjsn_lst #> $features[[1]]$geometry #> $features[[1]]$geometry$coordinates #> $features[[1]]$geometry$coordinates[[1]] -#> [1] 110.5266 +#> [1] 110.5241 #> #> $features[[1]]$geometry$coordinates[[2]] -#> [1] -66.2826 +#> [1] -66.28209 #> #> #> $features[[1]]$geometry$type @@ -266,98 +229,52 @@ gjsn_lst #> $features[[1]]$properties$bounds #> $features[[1]]$properties$bounds$northeast #> $features[[1]]$properties$bounds$northeast$lat -#> [1] -66.28255 +#> [1] -66.26209 #> #> $features[[1]]$properties$bounds$northeast$lng -#> [1] 110.5267 +#> [1] 110.5441 #> #> #> $features[[1]]$properties$bounds$southwest #> $features[[1]]$properties$bounds$southwest$lat -#> [1] -66.28265 +#> [1] -66.30209 #> #> $features[[1]]$properties$bounds$southwest$lng -#> [1] 110.5266 +#> [1] 110.5041 #> #> #> #> $features[[1]]$properties$components +#> $features[[1]]$properties$components$`ISO_3166-1_alpha-2` +#> [1] "AQ" +#> #> $features[[1]]$properties$components$`_category` -#> [1] "commerce" +#> [1] "place" +#> +#> $features[[1]]$properties$components$`_normalized_city` +#> [1] "Casey Station" #> #> $features[[1]]$properties$components$`_type` -#> [1] "office" +#> [1] "hamlet" #> #> $features[[1]]$properties$components$continent #> [1] "Antarctica" #> -#> $features[[1]]$properties$components$hamlet -#> [1] "Casey Station" +#> $features[[1]]$properties$components$country_code +#> [1] "aq" #> -#> $features[[1]]$properties$components$office +#> $features[[1]]$properties$components$hamlet #> [1] "Casey Station" #> #> #> $features[[1]]$properties$confidence -#> [1] 9 +#> [1] 7 #> #> $features[[1]]$properties$formatted -#> [1] "Casey Station" -#> -#> -#> $features[[1]]$type -#> [1] "Feature" -#> -#> -#> $features[[2]] -#> $features[[2]]$geometry -#> $features[[2]]$geometry$coordinates -#> $features[[2]]$geometry$coordinates[[1]] -#> [1] 110.5278 -#> -#> $features[[2]]$geometry$coordinates[[2]] -#> [1] -66.28225 -#> -#> -#> $features[[2]]$geometry$type -#> [1] "Point" -#> -#> -#> $features[[2]]$properties -#> $features[[2]]$properties$components -#> $features[[2]]$properties$components$`ISO_3166-1_alpha-2` -#> [1] "AQ" -#> -#> $features[[2]]$properties$components$`ISO_3166-1_alpha-3` -#> [1] "ATA" -#> -#> $features[[2]]$properties$components$`_category` -#> [1] "travel/tourism" -#> -#> $features[[2]]$properties$components$`_type` -#> [1] "point_of_interest" -#> -#> $features[[2]]$properties$components$continent -#> [1] "Antarctica" -#> -#> $features[[2]]$properties$components$country -#> [1] "Antarctica" -#> -#> $features[[2]]$properties$components$country_code -#> [1] "aq" -#> -#> $features[[2]]$properties$components$point_of_interest -#> [1] "Casey Station" -#> -#> -#> $features[[2]]$properties$confidence -#> [1] 9 -#> -#> $features[[2]]$properties$formatted #> [1] "Casey Station, Antarctica" #> #> -#> $features[[2]]$type +#> $features[[1]]$type #> [1] "Feature" #> #> @@ -387,8 +304,8 @@ gjsn_lst #> $stay_informed$blog #> [1] "https://blog.opencagedata.com" #> -#> $stay_informed$twitter -#> [1] "https://twitter.com/OpenCage" +#> $stay_informed$mastodon +#> [1] "https://en.osm.town/@opencage" #> #> #> $thanks @@ -396,14 +313,14 @@ gjsn_lst #> #> $timestamp #> $timestamp$created_http -#> [1] "Thu, 18 Feb 2021 19:02:15 GMT" +#> [1] "Tue, 31 Dec 2024 10:46:28 GMT" #> #> $timestamp$created_unix -#> [1] 1613674935 +#> [1] 1735641988 #> #> #> $total_results -#> [1] 2 +#> [1] 1 #> #> $type #> [1] "FeatureCollection" @@ -415,7 +332,7 @@ gjsn_lst In fact, {opencage} returns a list of results in `geo_list` format, which should be compatible with the {[geojsonio](https://docs.ropensci.org/geojsonio/)} package. -```r +``` r class(gjsn_lst[[1]]) #> [1] "geo_list" ``` @@ -425,17 +342,17 @@ class(gjsn_lst[[1]]) `url_only` returns the OpenCage URL for debugging purposes. -```r +``` r oc_forward("Casey Station", return = "url_only") #> [[1]] -#> [1] "https://api.opencagedata.com/geocode/v1/json?q=Casey%20Station&limit=10&no_annotations=1&roadinfo=0&no_dedupe=0&no_record=1&abbrv=0&add_request=0&key=OPENCAGE_KEY" +#> [1] "https://api.opencagedata.com/geocode/v1/json?q=Casey%20Station&limit=10&no_annotations=1&roadinfo=0&no_dedupe=0&no_record=1&abbrv=0&address_only=0&add_request=0&key=OPENCAGE_KEY" ``` Your OpenCage API key is masked with the `OPENCAGE_KEY` string, by default. If you really want {opencage} to display your API key with the URL, set the `show_key` argument in `oc_config()` to `TRUE`. -```r +``` r oc_config(show_key = TRUE) ```