---
title: "Geocode Dutch addresses"
author: "Willy Tadema, Edwin de Jonge"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    df_print: "kable"
vignette: >
  %\VignetteIndexEntry{Geocode Dutch addresses with nl_geocode}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = " "
)
library(leaflet)
library(sf)
library(nlgeocoder)
```

`nl_geocode` provides a quick and easy way to geocode labels of locations in 
The Netherlands. It will return points or centroids with metadata, but no polylines or polygons.
`nl_geocode` uses the pdok webservice for geo location and is designed to be similar to ggmap: 
for each (address) label the most probable location (i.e. according to the pdok service) will be 
returned.

## Geocode addresses

By default, `nl_geocode` will search for addresses.    

```{r, df_print="default"}
library(nlgeocoder)

res <- nl_geocode("Martinikerkhof 3 Groningen")
print(res["weergavenaam"])
```
For addresses a lot of information is available:

```{r}
colnames(res)
```

You can also search for multiple addresses at once.

```{r}
locations <- c("Martinikerkhof 3", "st jansstr 4 groningen", "9726AE 4", "9711 ME 1")
res <- nl_geocode(locations)
data.frame(query = locations, result = res$weergavenaam)
```

As you can see, the address doesn't need to be an exact match. Uppercases are ignored.

## Search for different type of locations

Besides addresses, you can also search for places, municipalities, provinces, roads and many more. See the [LocatieServer API documentation](https://github.com/PDOK/locatieserver/wiki/API-Locatieserver) complete list of types you can choose from.

You can restrict the output of `nl_geocode` to municipalities only:

```{r}
res <- nl_geocode("Groningen", type = "gemeente") 
res[c("weergavenaam","type")] 
```

You can also restrict the output to places:

```{r}
res <- nl_geocode("Groningen", type = "woonplaats") 
res$weergavenaam
res$type
```

If you are only interested in results in a particular area (for instance a province or municipality) you can use the `fq` parameter.

```{r}
res <- nl_geocode("Hoofdstraat", fq = "provincienaam:Groningen") 
res$weergavenaam
res$provincienaam
```

## Return coordinates in a spatial dataframe with CRS WGS84 or RD_New

By default, `nl_geocode` will return a `sf` object with coordinates in the 
coordinate reference system WGS84 (EPSG:4326). 

```{r}
res <- nl_geocode("Martinikerkhof 3 Groningen") 
st_crs(res)["epsg"]
```

It also possible to specify that the coordinates should be in RD_New (EPSG:28992), the Dutch coordinate reference system.

```{r}
res <- nl_geocode("Martinikerkhof 3 Groningen", output = "rd") 
st_crs(res)["epsg"]
```

You can also use the `nl_geocode_rd` function instead:
```{r}
res <- nl_geocode_rd("Martinikerkhof 3 Groningen") 
st_crs(res)["epsg"]
```

## Return coordinates in a dataframe

You can use the parameter `output` to indicate that you only want the labels, and not the geometry.

```{r}
res <- nl_geocode("Martinikerkhof 3 Groningen", output = "data.frame") 
class(res)
```

## Plot the output on a map

Plotting the output on a map, because by default `nl_geocode` returns an `sf` object.
```{r}
data("addresses")
```
```{r, echo = FALSE}
knitr::kable(addresses)
```


```{r}
library(leaflet)
poi_geocoded <- nl_geocode(addresses$Address)

leaflet(width = "100%", height=600) %>% 
  addPdokTiles("gray") %>% 
  addCircleMarkers( data = poi_geocoded
                  , popup = paste("<b>",addresses$POI, "</b><br/>", poi_geocoded$weergavenaam)
                  )
```