What3Words v1.0.0 What3Words

What3Words is the main module to interact with the w3w API. It includes calls to the three current endpoints: words_to_position/2, position_to_words/2 and languages/1.

To use the What3Words API, be sure to have your API key set up in your config.exs:

config :what3words, key: "yourkey"

Summary

Functions

Retrieves all available languages from the w3w API. An optional opts keyword argument can be passed: the opts cited in the w3w API documentation are supported, plus a :raw option is supported, for retrieving the whole response from the API

Same as languages/1, but returns the naked values (instead of {:ok, value}). Raises a MatchError if words are not found

Translates a tuple {lat, lng} into a tuple of 3 words. An optional opts keyword argument can be passed: the opts cited in the w3w API documentation are supported, plus a :raw option is supported, for retrieving the whole response from the API

Same as position_to_words/2, but returns the naked values (instead of {:ok, value}). Raises a MatchError if words are not found

Translates a tuple of 3 words into a {lat, lng} tuple. An optional opts keyword argument can be passed: the opts cited in the w3w API documentation are supported, plus a :raw option is supported, for retrieving the whole response from the API

Same as words_to_position/2, but returns the naked values (instead of {:ok, value}). Raises a MatchError if words are not found

Types

coords :: {lat, lng}
lat :: float
lng :: float

Functions

languages(opts \\ [])

Specs

languages(Keyword.t) :: [String.t]

Retrieves all available languages from the w3w API. An optional opts keyword argument can be passed: the opts cited in the w3w API documentation are supported, plus a :raw option is supported, for retrieving the whole response from the API.

iex> What3Words.languages
{:ok, ["en", "fr"]}

iex> What3Words.languages(raw: true)
{:ok, %{languages: [%{"code" => "en", "name_display" => "English"}, %{"code" => "fr", "name_display" => "French"}]}}
languages!(opts \\ [])

Specs

languages!(Keyword.t) :: [String.t]

Same as languages/1, but returns the naked values (instead of {:ok, value}). Raises a MatchError if words are not found.

position_to_words(coords, opts \\ [])

Specs

position_to_words(coords, Keyword.t) :: w3w

Translates a tuple {lat, lng} into a tuple of 3 words. An optional opts keyword argument can be passed: the opts cited in the w3w API documentation are supported, plus a :raw option is supported, for retrieving the whole response from the API.

iex> What3Words.position_to_words({40.723008, -74.199598})
{:ok, {"home", "index", "raft"}}

iex> What3Words.position_to_words({40.723008, -74.199598}, raw: true)
{:ok, %{language: "en", position: [40.723008, -74.199598], words: ["home", "index", "raft"]}}
position_to_words!(words, opts \\ [])

Specs

position_to_words!(coords, Keyword.t) :: w3w

Same as position_to_words/2, but returns the naked values (instead of {:ok, value}). Raises a MatchError if words are not found.

words_to_position(words, opts \\ [])

Specs

words_to_position(w3w, Keyword.t) :: coords

Translates a tuple of 3 words into a {lat, lng} tuple. An optional opts keyword argument can be passed: the opts cited in the w3w API documentation are supported, plus a :raw option is supported, for retrieving the whole response from the API.

iex> What3Words.words_to_position({"home", "index", "raft"})
{:ok, {40.723008, -74.199598}}

iex> What3Words.words_to_position({"home", "index", "raft"}, raw: true)
{:ok, %{language: "en", position: [40.723008, -74.199598], type: "3 words", words: ["home", "index", "raft"]}}
words_to_position!(words, opts \\ [])

Specs

words_to_position!(w3w, Keyword.t) :: coords

Same as words_to_position/2, but returns the naked values (instead of {:ok, value}). Raises a MatchError if words are not found.