What3Words Data Connector

The What3Words Data Connector provides access to the what3words API. This Data Connector can be used to convert between 3 word addresses and coordinates.

Constructor

What3Words(key) → {object}

We recommend that you create a Data Connector Configuration called "What3Words" via the Verj.io Runtime Environment's Administration Application.

A What3Words Data Connector is then available at connectors.verjio.what3words using that configuration.

If you are unable to do that, you may use this constructor to create a new What3Words Data Connector.

This constructor accepts an API key.

Parameters:

Name	Type	Description
key	`string`	what3words API key.

Returns:

object

The What3Words Data Connector.

Functions

autoSuggest(words, paramsopt, languageopt) → {Array.<What3Words.PlaceSuggestions>}

Suggests 3 word addresses in response to an incomplete address.

Parameters:

Name	Type	Attributes	Default	Description
words	`string`			Partial 3 word address. The first two words must be complete and there must be at least one letter from the third word.
params	`object`	<optional>		Additional parameters such as focus coordinates and bounding shapes.
language	`string`	<optional>	en	Optional language or locale.

See:

https://developer.what3words.com/public-api/docs#autosuggest

Returns:

Array.<What3Words.PlaceSuggestions>

Array of one or more suggestions.

Examples:

// Fetch suggestions using default options
const suggestions = connectors.verjio.what3words.autoSuggest('filled.count.s');

// Store the suggestions in a table for display
tables.suggestions.resetTable();

suggestions.forEach(suggestion => {
  tables.suggestions.insertRow();
  tables.suggestions.address.value = suggestion.nearestPlace;
  tables.suggestions.country.value = suggestion.country;
  tables.suggestions.words.value = suggestion.words;
});

// Focus suggestions on a particular coordinate
connectors.verjio.what3words.autoSuggest('filled.count.s', { focus: '51.521251,-0.203586' });

// Only return suggestions in a specified country or countries
// In this case, the United Kingdom and Belgium
connectors.verjio.what3words.autoSuggest('filled.count.s', { 'clip-to-country': 'GB,BE' });

// Restrict suggestions to a bounding box, circle or polygon
connectors.verjio.what3words.autoSuggest('filled.count.s', { 'clip-to-bounding-box': '51.521,-0.343,52.6,2.3324' });

// Show more suggestions in the ocean
connectors.verjio.what3words.autoSuggest('filled.count.s', { 'prefer-land': false });

fromCoordinates(lat, lng, languageopt) → {What3Words.PlaceDetails}

Converts a coordinate pair to a 3 word address.

Parameters:

Name	Type	Attributes	Default	Description
lat	`float`			Coordinate latitude
lng	`float`			Coordinate longitude
language	`string`	<optional>	en	Optional language or locale.

See:

https://developer.what3words.com/public-api/docs#convert-to-3wa

Returns:

What3Words.PlaceDetails

API response object.

gridlines(south, west, north, east, languageopt) → {Array.<What3Words.GridLine>}

Returns gridlines to draw showing the 3x3m grid within a specified bounding box.

The bounding box should not exceed 4km from corner to corner.

Parameters:

Name	Type	Attributes	Default	Description
south	`number`			Latitude coordinate for southern point of bounding box.
west	`number`			Longitude coordinate for western point of bounding box.
north	`number`			Latitude coordinate for northern point of bounding box.
east	`number`			Longitude coordinate for eastern point of bounding box.
language	`string`	<optional>	en	Optional language or locale.

See:

https://developer.what3words.com/public-api/docs#grid-section

Returns:

Array.<What3Words.GridLine>

Array of gridlines in specified bounding box.

handleError(response)

Checks an API response for errors. If an error is encountered, the appropriate Error is thrown.

Parameters:

Name	Type	Description
response	`object`	The response from a `services.rest` request.

See:

https://developer.what3words.com/public-api/docs#error-handling

Throws:

HttpAuthorisationError

Thrown when an incorrect API key is specified or the request exceeds rate limiting.
HttpNotFoundError

Thrown when the vehicle registration number is not recognised.
HttpServerError

Thrown when the API responsed with a server error (HTTP 502 and HTTP 504)
HttpRequestError

Thrown when the server could not process the request. Details are available in the error message.

toCoordinates(words, languageopt) → {What3Words.PlaceDetails}

Converts a 3 word address to a coordinate pair.

Parameters:

Name	Type	Attributes	Default	Description
words	`string`			3 word address
language	`string`	<optional>	en	Optional language or locale.

See:

https://developer.what3words.com/public-api/docs#convert-to-coords

Returns:

What3Words.PlaceDetails

API response object.

Type definitions

BoundingBox

Bounding box defining a grid square or a map area.

Properties:

Name	Type	Description
southwest	`What3Words.CoordinatePair`	Southwest coordinate pair.
northeast	`What3Words.CoordinatePair`	Northeast coordinate pair.

CoordinatePair

Latitude and longitude coordinate pair.

Properties:

Name	Type	Description
lng	`number`	Longitude coordinate.
lat	`number`	Latitude coordinate.

GridLine

Object containing a definition of a partial line.

Properties:

Name	Type	Description
start	`What3Words.CoordinatePair`	Coordinate pair defining the start of the line.
stop	`What3Words.CoordinatePair`	Coordinate pair defining the end of the line.

PlaceDetails

Object containing details of a place as returned by the API.

Properties:

Name	Type	Attributes	Default	Description
country	`string`			Country as a 2-letter ISO (3166-1 alpha-2) code.
square	`What3Words.BoundingBox`			Bounds of the 3 meter grid square, as coordinate pairs.
nearestPlace	`string`			The nearest town or named place and country.
coordinates	`What3Words.CoordinatePair`			The latitude and longitude coordinate pair for the place.
words	`string`			The 3 word address representing the place.
language	`string`	<optional>	en	The response language as a 2-letter ISO (639-1) code.
locale	`string`	<nullable>		Language locale, if applicable.
map	`string`			URL of a map indicating the place on the What3Words website.

PlaceSuggestions

Object containing place suggestions as returned by the API.

Properties:

Name	Type	Attributes	Default	Description
country	`string`			Country as a 2-letter ISO (3166-1 alpha-2) code.
nearestPlace	`string`			The nearest town or named place.
words	`string`			The 3 word address representing the suggested place.
distanceToFocusKm	`number`			The distance from the suggested place to the focus or search centre.
rank	`integer`			The rank of the suggestion. A rank of 1 is the highest and therefore most likely to be the correct suggestion.
language	`string`	<optional>	en	The response language as a 2-letter ISO (639-1) code.
locale	`string`	<nullable>		Language locale, if applicable.