---
title: "Using whatthreewords"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using whatthreewords}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The whatthreewords package supports working with the [what3words](https://what3words.com/) API. what3words has partitioned the surface of the earth into 3m x 3m squares, each of which can be identified by three words. These are conventionally styled with three slashes at the beginning. For example, the peak of the Great Pyramid of Giza is located by the three words [///ballots.height.silks](https://what3words.com/ballots.height.silks).

You can use the package to determine the three word address for any coordinates, or return the coordinates for any valid three word combination. 

# Load the package

First, load the package...

```{r setup}
library(whatthreewords)
```

# Set environment variable

The what3words API requires a key for authentication. You can register for a key at [https://developer.what3words.com/public-api](https://developer.what3words.com/public-api).

You must then set the `WTW_API_KEY` environment variable to hold your key. For example...

``` r
Sys.setenv(WTW_API_KEY = "MYKEY")
```

```{r include=FALSE}
key_present <- tryCatch({
  whatthreewords::get_api_key()
  TRUE
}, 
error = function(e) FALSE)
```


You are now ready to use the package.

# Get a what3words address from coordinates

Use `words_from_coords` to get a what3words location for a given latitude and longitude.

```{r eval=key_present}
words_from_coords(lat = 51.5095, 
                  lon = -0.1266)
```

## Full details

By default, `words_from_coords` returns only the three words which represent the location. However, it's possible to return more information about the location by submitting `full_details = TRUE`.

```{r eval=key_present}
words_from_coords(lat = 51.5095, 
                  lon = -0.1266, 
                  full_details = TRUE)
```

## Multiple locations

`words_from_coords` is vectorised over the coordinates so you can return multiple locations with one call. For example, take the following data frame.

```{r eval=key_present}
locations <- data.frame(name = c("Sheffield United", "Sheffield Wednesday", "Sheffield Club"), 
                        lat = c(53.3703, 53.41145, 53.3096), 
                        lon = c(-1.47119, -1.500204, -1.478715))
locations
```

We can add the what3words for each row like this...

```{r eval=key_present}

locations$words <- words_from_coords(lat = locations$lat, 
                                     lon = locations$lon)

locations
```


# Get coordinates from a what3words location

`coords_from_words` returns the coordinates for a what3words location.

```{r eval=key_present}
coords_from_words("hours.flesh.petal")
```
By default, coordinates are returned as a matrix with as many rows as the length of the vector submitted to the `words` argument.

## Full details

You can also return the full details of the location as a list.

```{r eval=key_present}
coords_from_words("hours.flesh.petal", full_details = TRUE)
```

## Multiple locations

`coords_from_words` is vectorised over words. You can return multiple 
coordinates like this:

```{r eval=key_present}
coords_from_words(c("laughs.remind.fact", 
                    "hotdog.jumping.frog", 
                    "dream.helps.forget"))
```

# Different languages

what3words support a range of languages. You can work in different languages by submitting a supported [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) two letter code to `language`.

```{r eval=key_present}
words_from_coords(lat = 48.70913, 
                  lon = 9.001062, 
                  language = "de")
```

Supported languages can be determined by `get_available_languages`.

```{r eval=key_present}
get_available_languages() |> 
  head()
```