Retrieves all suggestions for the supplied 3 word address string, given at least 2 and the first letter of the third. In addition, providing a language is mandatory for the autosuggest endpoint. 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.autosuggest("home.index.r", "en")
{:ok, [
  %What3Words.Suggestion{
    distance: 1,
    rank: 1,
    words: "no.options.request",
    score: 1,
    place: "King's College, Cambridge",
    country: "gb",
    geometry: %{
      lng: 1.000000,
      lat: 1.000000
    }
  }
]}

The clip and focus options work a little bit differently, just to spare you from creating the wanted string yourself. Here’s examples for both:

#
# radius in km around lat and lng
iex> {lat, lng, km} = {1, 1, 10}
iex> opts = %{clip: %{radius: {lat, lng, km}}}
iex> What3Words.autosuggest("home.index.r", "en", opts)
{:ok, [
  %What3Words.Suggestion{
    distance: 1,
    rank: 1,
    words: "clip.radius.request",
    score: 1,
    place: "King's College, Cambridge",
    country: "gb",
    geometry: %{
      lng: 1.000000,
      lat: 1.000000
    }
  }
]}

#
# bounding box between north east and south west points
iex> {nelat, nelng, swlat, swlng} = {1, 1, -1, -1}
iex> opts = %{clip: %{bbox: {nelat, nelng, swlat, swlng}}}
iex> What3Words.autosuggest("home.index.r", "en", opts)
{:ok, [
  %What3Words.Suggestion{
    distance: 1,
    rank: 1,
    words: "clip.bbox.request",
    score: 1,
    place: "King's College, Cambridge",
    country: "gb",
    geometry: %{
      lng: 1.000000,
      lat: 1.000000
    }
  }
]}

#
# clip around focus point by km
iex> {focus_lat, focus_lng, km} = {1, 1, 10}
iex> opts = %{clip: %{focus: km}, focus: {focus_lat, focus_lng}}
iex> What3Words.autosuggest("home.index.r", "en", opts)
{:ok, [
  %What3Words.Suggestion{
    distance: 1,
    rank: 1,
    words: "clip.focus.request",
    score: 1,
    place: "King's College, Cambridge",
    country: "gb",
    geometry: %{
      lng: 1.000000,
      lat: 1.000000
    }
  }
]}

#
# focus around lat and lng for better results
iex> {focus_lat, focus_lng} = {1, 1}
iex> opts = %{focus: {focus_lat, focus_lng}}
iex> What3Words.autosuggest("home.index.r", "en", opts)
{:ok, [
  %What3Words.Suggestion{
    distance: 1,
    rank: 1,
    words: "focus.option.request",
    score: 1,
    place: "King's College, Cambridge",
    country: "gb",
    geometry: %{
      lng: 1.000000,
      lat: 1.000000
    }
  }
]}

If you don’t like fiddling with those options, good old strings are still supported for the clip and focus options. If binary strings are detected, the transformations will just be skipped.

Translates a string or 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 will be proxied; furthermore, a :raw option is supported, for retrieving the whole response from the API.

iex> What3Words.forward("home.index.raft")
{:ok, %{lat: 40.723008, lng: -74.199598}}

iex> What3Words.forward({"home", "index", "raft"})
{:ok, %{lat: 40.723008, lng: -74.199598}}

iex> What3Words.forward({"home", "index", "raft"}, raw: true)
{:ok, %{language: "en", geometry: %{"lat" => 40.723008, "lng" => -74.199598}, words: "home.index.raft"}}

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

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"}]}}

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.

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

iex> What3Words.reverse({40.723008, -74.199598}, raw: true)
{:ok, %{language: "en", geometry: %{"lat" => 40.723008, "lng" => -74.199598}, words: "home.index.raft"}}

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