add sf option to geocode

[dpprdan]

This PR adds an boolean sf argument to the geocode() function. If TRUE, the default, an {sf} object is returned as before, if FALSE a data.frame with lng and lat columns.

Motivation: I often need the coordinates from geocoding as lat/lon columns instead of an sfc. Right now, one would have to convert the sfc back with st_coordinates and - at least for me - it would be helpful to get the lat/lon columns directly (and skip the sf roundtrip).

Let me know whether you feel this is within the scope of the package. If it is, I can also add a test and NEWS item.

Alternatively, one could add a remove option, as in sf::st_as_sf(remove = FALSE) to prohibit removing the lat/lng columns from the {sf} object. In my own workflow I would still have to delete the sfc column, though, and I cannot think of a sensible workflow where one would need both lat/lng and sfc columns simultaneously at the moment. That's why I chose the approach above.

[munterfinger]

Many thanks for contributing!

Tested and works perfectly fine:

library(hereR)
set_key("<API-KEY>")
set_verbose(TRUE)

# Address
addr <- c(
  "Schweighofstrasse 190, Zurich, Switzerland",
  "Hardstrasse 48, Zurich, Switzerland"
)

# Return data.frame
(df <- geocode(addr, sf = FALSE))
#> Sending 2 request(s) to: 'https://geocoder.ls.hereapi.com/6.2/geocode.json?...'
#> Received 2 response(s) with total size: 2.5 Kb
#>   id                                            address            street
#> 1  1 Schweighofstrasse 190, 8045 Zürich Zürich, Schweiz Schweighofstrasse
#> 2  2        Hardstrasse 48, 8004 Zürich Zürich, Schweiz       Hardstrasse
#>   houseNumber postalCode district   city county state country  type     lng
#> 1         190       8045  Kreis 3 Zürich Zürich    ZH     CHE point 8.50741
#> 2          48       8004  Kreis 4 Zürich Zürich    ZH     CHE point 8.51201
#>        lat
#> 1 47.35959
#> 2 47.37994
class(df)
#> [1] "data.frame"

# Return sf object
(sf <- geocode(addr))
#> Sending 2 request(s) to: 'https://geocoder.ls.hereapi.com/6.2/geocode.json?...'
#> Received 2 response(s) with total size: 2.5 Kb
#> Simple feature collection with 2 features and 11 fields
#> geometry type:  POINT
#> dimension:      XY
#> bbox:           xmin: 8.50741 ymin: 47.35959 xmax: 8.51201 ymax: 47.37994
#> CRS:            EPSG:4326
#>   id                                            address            street
#> 1  1 Schweighofstrasse 190, 8045 Zürich Zürich, Schweiz Schweighofstrasse
#> 2  2        Hardstrasse 48, 8004 Zürich Zürich, Schweiz       Hardstrasse
#>   houseNumber postalCode district   city county state country  type
#> 1         190       8045  Kreis 3 Zürich Zürich    ZH     CHE point
#> 2          48       8004  Kreis 4 Zürich Zürich    ZH     CHE point
#>                   geometry
#> 1 POINT (8.50741 47.35959)
#> 2 POINT (8.51201 47.37994)
class(sf)
#> [1] "sf"         "data.frame"

The package is explicitly designed as an {sf}-based interface. Therefore, {sf} objects should be returned by default. However, it makes sense to offer an option that directly returns the coordinates of the geocoded addresses without the forced “roundtrip” via {sf}. So I think this is a useful extension of the interface.

I would be happy if you could add the following:

• NEWS entry
• Check the new option in hereR/tests/testthat/test-geocode.R
• Change parameter order to: function(addresses, autocomplete = FALSE, sf = TRUE, url_only = FALSE)
• CI check fails due to missing function doc, running
  roxygen2::roxygenize() and also commit the man/geocode.Rd file
  should fix it.

Session info

devtools::session_info()
#> ─ Session info ───────────────────────────────────────────────────────────────
#>  setting  value                       
#>  version  R version 4.0.0 (2020-04-24)
#>  os       macOS Catalina 10.15.5      
#>  system   x86_64, darwin17.0          
#>  ui       X11                         
#>  language (EN)                        
#>  collate  en_US.UTF-8                 
#>  ctype    en_US.UTF-8                 
#>  tz       Europe/Zurich               
#>  date     2020-06-17                  
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────
#>  package     * version    date       lib source        
#>  assertthat    0.2.1      2019-03-21 [1] CRAN (R 4.0.0)
#>  backports     1.1.7      2020-05-13 [1] CRAN (R 4.0.0)
#>  callr         3.4.3      2020-03-28 [1] CRAN (R 4.0.0)
#>  class         7.3-17     2020-04-26 [1] CRAN (R 4.0.0)
#>  classInt      0.4-3      2020-04-07 [1] CRAN (R 4.0.0)
#>  cli           2.0.2      2020-02-28 [1] CRAN (R 4.0.0)
#>  crayon        1.3.4      2017-09-16 [1] CRAN (R 4.0.0)
#>  curl          4.3        2019-12-02 [1] CRAN (R 4.0.0)
#>  data.table    1.12.8     2019-12-09 [1] CRAN (R 4.0.0)
#>  DBI           1.1.0      2019-12-15 [1] CRAN (R 4.0.0)
#>  desc          1.2.0      2018-05-01 [1] CRAN (R 4.0.0)
#>  devtools      2.3.0      2020-04-10 [1] CRAN (R 4.0.0)
#>  digest        0.6.25     2020-02-23 [1] CRAN (R 4.0.0)
#>  e1071         1.7-3      2019-11-26 [1] CRAN (R 4.0.0)
#>  ellipsis      0.3.1      2020-05-15 [1] CRAN (R 4.0.0)
#>  evaluate      0.14       2019-05-28 [1] CRAN (R 4.0.0)
#>  fansi         0.4.1      2020-01-08 [1] CRAN (R 4.0.0)
#>  fs            1.4.1      2020-04-04 [1] CRAN (R 4.0.0)
#>  glue          1.4.1      2020-05-13 [1] CRAN (R 4.0.0)
#>  hereR       * 0.3.3.9000 2020-06-17 [1] local         
#>  htmltools     0.4.0      2019-10-04 [1] CRAN (R 4.0.0)
#>  jsonlite      1.6.1      2020-02-02 [1] CRAN (R 4.0.0)
#>  KernSmooth    2.23-17    2020-04-26 [1] CRAN (R 4.0.0)
#>  knitr         1.28       2020-02-06 [1] CRAN (R 4.0.0)
#>  magrittr      1.5        2014-11-22 [1] CRAN (R 4.0.0)
#>  memoise       1.1.0      2017-04-21 [1] CRAN (R 4.0.0)
#>  pkgbuild      1.0.8      2020-05-07 [1] CRAN (R 4.0.0)
#>  pkgload       1.0.2      2018-10-29 [1] CRAN (R 4.0.0)
#>  prettyunits   1.1.1      2020-01-24 [1] CRAN (R 4.0.0)
#>  processx      3.4.2      2020-02-09 [1] CRAN (R 4.0.0)
#>  ps            1.3.3      2020-05-08 [1] CRAN (R 4.0.0)
#>  R6            2.4.1      2019-11-12 [1] CRAN (R 4.0.0)
#>  Rcpp          1.0.4.6    2020-04-09 [1] CRAN (R 4.0.0)
#>  remotes       2.1.1      2020-02-15 [1] CRAN (R 4.0.0)
#>  rlang         0.4.6      2020-05-02 [1] CRAN (R 4.0.0)
#>  rmarkdown     2.2        2020-05-31 [1] CRAN (R 4.0.0)
#>  rprojroot     1.3-2      2018-01-03 [1] CRAN (R 4.0.0)
#>  sessioninfo   1.1.1      2018-11-05 [1] CRAN (R 4.0.0)
#>  sf            0.9-3      2020-05-04 [1] CRAN (R 4.0.0)
#>  stringi       1.4.6      2020-02-17 [1] CRAN (R 4.0.0)
#>  stringr       1.4.0      2019-02-10 [1] CRAN (R 4.0.0)
#>  testthat      2.3.2      2020-03-02 [1] CRAN (R 4.0.0)
#>  units         0.6-6      2020-03-16 [1] CRAN (R 4.0.0)
#>  usethis       1.6.1      2020-04-29 [1] CRAN (R 4.0.0)
#>  withr         2.2.0      2020-04-20 [1] CRAN (R 4.0.0)
#>  xfun          0.14       2020-05-20 [1] CRAN (R 4.0.0)
#>  yaml          2.2.1      2020-02-01 [1] CRAN (R 4.0.0)
#> 
#> [1] /Library/Frameworks/R.framework/Versions/4.0/Resources/library

[dpprdan]

Great, thanks! I am on it.

Quick question: I stumbled over this test line:

expect_equal(any(sf::st_geometry_type(geocoded) != "POINT"), FALSE)

I think this would be easier to read as

expect_true(all(sf::st_geometry_type(geocoded) == "POINT"))

Do you agree, or am I missing something?

[munterfinger]

Sounds sensible - feel free to replace it!

[dpprdan]

This ought to be it. There is still a note from R-CMD-check, but I don't think that it is caused by something I changed, since it also comes up in previous tests. Probably some address data with umlauts or something like that.

 ❯ checking data for non-ASCII characters ... NOTE
    Note: found 1 marked UTF-8 string

[munterfinger]

Perfect - thank you!

I assume that the non-ASCII character is somewhere in an example or the package data used in the vignettes. It is planned to move the examples and test data sets to an English-speaking country. In addition, intermodal routes (a new feature planned for the next CRAN release) are not yet available in the current test area in Switzerland.

[munterfinger]

@dpprdan Would you like to be mentioned as contributor in the DESCRIPTION of the package?

Authors@R: c(
    person("Merlin", "Unterfinger", email = "info@munterfinger.ch", role = c("aut", "cre")),
    person("Daniel", "Possenriede", role = "ctb", comment = "Geocode return options"))

The release of {hereR} v0.4.0 on CRAN is scheduled for the next days.

[dpprdan]

@munterfinger Of course, thanks! You could maybe also add my ORCID comment = c(ORCID = "0000-0002-6738-9845")?

[munterfinger]

Added you with ORCID in #50, cheers!