Using whatthreewords

In whatthreewords: Work with the 'what3words' API for Easy Location Referencing

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

The whatthreewords package supports working with the what3words 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.

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...

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.

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

Sys.setenv(WTW_API_KEY = "MYKEY")

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.

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.

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.

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...

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.

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.

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:

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 two letter code to language.

words_from_coords(lat = 48.70913, 
                  lon = 9.001062, 
                  language = "de")

Supported languages can be determined by get_available_languages.

get_available_languages() |> 
  head()

whatthreewords documentation built on Oct. 2, 2023, 5:09 p.m.