Skip to main content

W3W

Latest Version: 1.0.1

What Three Words (W3W) is a navigation service which aims to make geographical locations more manageable — for humans, at least. The World has been segmented into a grid of 3m x 3m squares, each one represented by a unique combination of three words. For example, the Statue of Liberty is located within the square referenced by the words chief.ramp.songs.

Multiple languages are supported for the geo-reference words.

You can view the library’s source code on GitHub.

To include this library in your project, add #require "w3w.agent.lib.nut:1.0.1" at the top of your agent code

Library Usage

The W3W library is implemented as a Squirrel table. As such, it has no constructor, but you will need to call its init() function in order to set both your W3W API key and the callback through which the library communicates with your application. You must call init() before calling any other W3W function.

The Callback

W3W uses a single callback for all notifications to the host application, whether returning data or reporting errors. You can use a single handler function for both, as shown in the example below. The handler will always receive a table.

When location data is returned via the callback, it contains the same information, whether you requested words from a set of co-ordinates, or vice versa. In either case, the returned table contains the following keys:

Key Value Type Description
words String The three words for the specified location
coords Table The co-ordinates of the specified location. Contains the keys latitude and longitude
rawdata Table All the data returned by W3W — see the W3W API documentation

An error report will contain the following keys:

Key Value Type Description
error String The W3W error message
code Integer The W3W error message
statuscode Integer The HTTP response status code

Example

#require "w3w.agent.lib.nut:1.0.1"

// Set the API key
const W3W_API_KEY = "<YOUR_W3W_API_KEY>";

// Define the notification handler
function cb(result) {
    if ("error" in result) {
        server.error(result.error + ", code: " + result.errcode);
    } else {
        server.log(result.words);
    }
}

// Make library settings choices
local settings = {
    "callback": cb,
    "apiKey": W3W_API_KEY
};

// Initialize and use library
W3W.init(settings);
W3W.getCoords(savedWords);

Library Functions

init(settings)

Configure the library. You must call this before making use of the library’s other functions, including values for apiKey and callback.

Parameters

Parameter Type Required? Description
apiKey String Yes Your W3W API key
callback Function Yes The library’s notification callback. See The Callback for details
language String No Your preferred language. Supply an ISO 639-1 two-letter code. Default: en

Returns

Nothing.

getWords(coordinates[, getGeoJson])

Find the three-word representation of the supplied latitude and longitude co-ordinates in WGS84 format. The co-ordinates can be passed in a string, an array of strings, or an array of floats. Take care with the latter: because of the rounding implicit in Squirrel’s conversion of floats to strings (required for transmission to W3W) you may lose precision and so may not receive the three words you expect.

Optionally, request the results are returned in GeoJson format rather than W3W’s JSON format.

Returned data or errors are posted via the callback. Returned data is in the form of a table with the following keys:

Key Type Description
words String The three words as single, period-separated string
coords Table The original co-ordinates via keys lat and lng
rawdata Table All the data sent by W3W

Parameters

Parameter Type Required? Description
coordinates String or array of strings, floats or integers Yes Latitude and Longitude co-ordinates

Returns

Nothing.

Examples

W3W.getWords("51.551208,-0.1348044");
W3W.getWords(["51.551208", "-0.1348044"]);
W3W.getWords([51.551208, -0.1348044]);

getCoords(words[, getGeoJson])

Get the latitude and longitude co-ordinates of the supplied three words. Optionally, request the results are returned in GeoJson format rather than W3W’s JSON format.

Returned data or errors are posted via the callback. Returned data is in the form of a table with the keys listed above under getWords()

Parameters

Parameter Type Required? Description
words String or array of strings Yes The supplied three words, eg. no.address.here

Returns

Nothing.

Examples

W3W.getCoords("chief.ramp.songs");
W3W.getCoords(["chief", "ramp", "songs"]);