Adding geocode_csv() and geocode_csv_reverse() function

.Rbuildignore

@@ -11,3 +11,5 @@
 ^CRAN-RELEASE$
 ^\.github$
 ^revdep$
+^vignettes/reverse\.csv$
+^vignettes/search\.csv$

DESCRIPTION

@@ -24,7 +24,7 @@ Suggests:
     testthat,
     knitr,
     rmarkdown
-RoxygenNote: 7.1.0
+RoxygenNote: 7.1.1
 Encoding: UTF-8
 URL: http://joelgombin.github.io/banR/, http://github.com/joelgombin/banR/
 BugReports: http://github.com/joelgombin/banR/issues

NAMESPACE

@@ -2,6 +2,8 @@
 
 export("%>%")
 export(geocode)
+export(geocode_csv)
+export(geocode_csv_reverse)
 export(geocode_tbl)
 export(reverse_geocode)
 export(reverse_geocode_tbl)

R/geocode_csv.R

@@ -0,0 +1,44 @@
+
+
+#' Geocode French addresses using a CSV file
+#'
+#' @param file the path of the csv file containing the addresses.
+#' @param ... additional arguments provided by the API.
+#'
+#' @return a tibble with geocoded addresses among other related information
+#' @export
+#'
+#' @examples
+#'
+#' # Downloading the example csv file provided in the API website
+#'
+#' download.file("https://adresse.data.gouv.fr/exemples/search.csv", "search.csv")
+#'
+#' # using this csv file
+#'
+#' geocode_csv("search.csv")
+#'
+#'
+#'
+
+geocode_csv <- function(file, ...){
+
+  api_url <- "https://api-adresse.data.gouv.fr/search/csv/"
+
+  resp <- httr::POST(
+    url = api_url,
+    body = list(
+      data = httr::upload_file(file, type = "csv"),
+      ...
+    ),
+
+    encode = "multipart"
+  )
+
+  return(httr::content(resp, "parsed"))
+
+
+
+
+}
+

R/geocode_csv_reverse.R

@@ -0,0 +1,46 @@
+
+
+#' Inverse geocoding geographical coordinates using a csv file
+#'
+#' @param file the path of the csv file containing the coordinates
+#' @param ... additional arguments provided by the API.
+#'
+#' @return a tibble with reverse geocoded coordinates among other related information
+#'
+#' @export
+#'
+#' @examples
+#'
+#' # Downloading the example csv file provided in the API website
+#'
+#' download.file("https://adresse.data.gouv.fr/exemples/reverse.csv", "reverse.csv")
+#'
+#' # using this csv file
+#'
+#' geocode_csv_reverse("reverse.csv")
+#'
+
+
+
+geocode_csv_reverse <- function(file, ...){
+
+  api_url <- "https://api-adresse.data.gouv.fr/reverse/csv/"
+
+  resp <- httr::POST(
+    url = api_url,
+    body = list(
+      data = httr::upload_file(file, type = "csv"),
+      encoding = "UTF-8",
+      ...
+    ),
+
+    encode = "multipart"
+  )
+
+  return(httr::content(resp, "parsed"))
+
+
+}
+
+
+

vignettes/geocode.Rmd

@@ -93,4 +93,94 @@ test_df %>%
   reverse_geocode_tbl(lon, lat) %>% 
   glimpse
 
+```
+
+
+### Geocode from a CSV file: 
+
+
+`geocode_csv()` allows you, from a csv file, to geocode a massive amount of addresses. __The API can handle a csv file up to 50Mo__. In order to use the function, you'll need a local CSV file. 
+
+In this example we'll work with the CSV file provided by the API DOC website, available here: __https://adresse.data.gouv.fr/exemples/search.csv__
+
+```{r}
+
+# 1.first download the csv file 
+
+download.file("https://adresse.data.gouv.fr/exemples/search.csv", 
+              "search.csv")
+
+# 2. geocode the addresses 
+
+geocode_csv(file = "search.csv")
+
+
+```
+
+__By default `geocode_csv()` will concatenate all the columns in order to formulate the addresses to be geocoded and it will return a tibble containing the geocoded addresses among other related information.__
+
+
+You can also tune your geocoding by providing additional parameters to the `...` argument of the `geocode_csv()` function. For example, it's possible to select the columns that will be used for our geocoding: 
+
+
+```{r}
+
+
+geocode_csv(file = "search.csv", 
+            columns = "postcode", 
+            columns = "adresse")
+
+
+```
+
+In case you've a large CSV file and you want to speed up the process, you can indicate the needed resulting columns this way: 
+
+
+```{r}
+
+geocode_csv(file = "search.csv", 
+            columns = "postcode", 
+            columns = "adresse", 
+            result_columns = "latitude", 
+            result_columns = "longitude")
+
+
+```
+
+Finally, it's possible to indicate the column that contains the __INSEE code__ or the __Postal code__. The example CSV file that we're using doesn't contain these kind of columns but you'd implement it this way:
+
+```{r, eval=FALSE}
+
+# DO NOT RUN. THIS IS HYPOTHETICAL 
+
+geocode_csv(file = "YOUR_CSV_FILE", 
+            postcode = "COLUMN_WITH_POSTCODE", 
+            citycode = "COLUMN_WITH_INSEECODE")
+
+```
+
+## 4. Reverse Geocode from a CSV file: `geocode_csv_reverse()`
+
+
+`geocode_csv_reverse()` works the way as `geocode_csv()` except that it does the inverse. It transforms longitude and latitude information into addresses. __Note also that API tolerates CSV files up to 6Mo for this kind of operation.__ 
+
+##### Important 🐱 The csv file must contain columns named _latitude (or lat)__ and _longitude (or lon or lng)_
+
+
+In order to illustrate this function, we'll work on the CSV file provided by the API DOC and available here: __https://adresse.data.gouv.fr/exemples/reverse.csv__
+
+
+
+```{r}
+
+# 1.first download the csv file 
+
+download.file("https://adresse.data.gouv.fr/exemples/reverse.csv", 
+              "reverse.csv")
+
+# 2. geocode the addresses 
+
+geocode_csv_reverse(file = "reverse.csv")
+
+
 ```

vignettes/reverse.csv

@@ -0,0 +1,5 @@
+lat,lon,name
+48.670333,6.1468826,École Claude Déruet
+48.6495464,6.1521676,École Gilberte Monne
+48.6470103,6.2075765,École maternelle Victor Hugo
+48.7277223,6.1578988,École maternelle Buffon

vignettes/search.csv

@@ -0,0 +1,5 @@
+nom,adresse,postcode,city
+École Claude Déruet,6 Rue Albert 1er,54600,Villers-lès-Nancy
+École Gilberte Monne,6 Rue d'Aquitaine,54500,Vandœuvre-lès-Nancy
+École maternelle Victor Hugo,31 Rue d'Arbois,54180,Heillecourt
+École maternelle Buffon,1 bis Rue de la Papeterie,54250,Champigneulles