Using whatthreewords • whatthreewords

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")

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)
#> [1] "lamp.inner.dent"

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)
#> $country
#> [1] "GB"
#> 
#> $square
#> $square$southwest
#> $square$southwest$lng
#> [1] -0.126604
#> 
#> $square$southwest$lat
#> [1] 51.50949
#> 
#> 
#> $square$northeast
#> $square$northeast$lng
#> [1] -0.126561
#> 
#> $square$northeast$lat
#> [1] 51.50951
#> 
#> 
#> 
#> $nearestPlace
#> [1] "London"
#> 
#> $coordinates
#> $coordinates$lng
#> [1] -0.126583
#> 
#> $coordinates$lat
#> [1] 51.5095
#> 
#> 
#> $words
#> [1] "lamp.inner.dent"
#> 
#> $language
#> [1] "en"
#> 
#> $map
#> [1] "https://w3w.co/lamp.inner.dent"

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
#>                  name      lat       lon
#> 1    Sheffield United 53.37030 -1.471190
#> 2 Sheffield Wednesday 53.41145 -1.500204
#> 3      Sheffield Club 53.30960 -1.478715

We can add the what3words for each row like this…


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

locations
#>                  name      lat       lon             words
#> 1    Sheffield United 53.37030 -1.471190 elite.icon.levels
#> 2 Sheffield Wednesday 53.41145 -1.500204 weep.stands.shack
#> 3      Sheffield Club 53.30960 -1.478715    soon.belt.owls

Get coordinates from a what3words location

coords_from_words returns the coordinates for a what3words location.

coords_from_words("hours.flesh.petal")
#>           lat       lon
#> [1,] 51.50955 -0.126799

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)
#> $hours.flesh.petal
#> $hours.flesh.petal$country
#> [1] "GB"
#> 
#> $hours.flesh.petal$square
#> $hours.flesh.petal$square$southwest
#> $hours.flesh.petal$square$southwest$lng
#> [1] -0.126821
#> 
#> $hours.flesh.petal$square$southwest$lat
#> [1] 51.50954
#> 
#> 
#> $hours.flesh.petal$square$northeast
#> $hours.flesh.petal$square$northeast$lng
#> [1] -0.126778
#> 
#> $hours.flesh.petal$square$northeast$lat
#> [1] 51.50957
#> 
#> 
#> 
#> $hours.flesh.petal$nearestPlace
#> [1] "London"
#> 
#> $hours.flesh.petal$coordinates
#> $hours.flesh.petal$coordinates$lng
#> [1] -0.126799
#> 
#> $hours.flesh.petal$coordinates$lat
#> [1] 51.50955
#> 
#> 
#> $hours.flesh.petal$words
#> [1] "hours.flesh.petal"
#> 
#> $hours.flesh.petal$language
#> [1] "en"
#> 
#> $hours.flesh.petal$map
#> [1] "https://w3w.co/hours.flesh.petal"

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"))
#>           lat       lon
#> [1,] 10.06928 -61.41211
#> [2,] 43.89240 -91.75357
#> [3,] 40.84782 -74.30676

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")
#> [1] "entlang.erdkunde.richter"

Supported languages can be determined by get_available_languages.

get_available_languages() |> 
  head()
#>   nativeName code       name locales.nativeName locales.name locales.code
#> 1    Deutsch   de     German               <NA>         <NA>         <NA>
#> 2      हिन्दी   hi      Hindi               <NA>         <NA>         <NA>
#> 3        ລາວ   lo        Lao               <NA>         <NA>         <NA>
#> 4  Português   pt Portuguese               <NA>         <NA>         <NA>
#> 5     Magyar   hu  Hungarian               <NA>         <NA>         <NA>
#> 6 Українська   uk  Ukrainian               <NA>         <NA>         <NA>
#>   locales.nativeName.1 locales.name.1 locales.code.1
#> 1                 <NA>           <NA>           <NA>
#> 2                 <NA>           <NA>           <NA>
#> 3                 <NA>           <NA>           <NA>
#> 4                 <NA>           <NA>           <NA>
#> 5                 <NA>           <NA>           <NA>
#> 6                 <NA>           <NA>           <NA>