March 18, 2015 at 19:05

Introducing the what3words API: basic procedures and samples



Our main task was to give addresses to every place on the planet, and today this task has been completed. The grid of what3words squares covers the entire globe, and each square has a unique address. It's time to give everyone the opportunity to use three-word addresses, and make it convenient. It will be convenient when each map, navigation application and other geolocation services will support what3words. For this, our API was created, which we want to talk about in detail.

We tried to make the interface as simple as possible, and made every effort to save the time and nerves of the developers. The interface performs two basic procedures: converting 3 words to a location, and converting a location to 3 words. The third additional procedure is to request a list of the available languages ​​of the three words. In most cases, all communication with the API comes down to simple GET requests. Responses are provided in JSON.

1. Convert 3 words to location



The procedure turns 3 words into a pair of latitude / longitude coordinates. What3words addresses are given by 3 x 3 meter squares, and the resulting coordinates are the coordinates of the center of such a square. Together with the coordinates, the response contains the requested three words, to which all corrections are applied.

Additional parameters

For this procedure, an additional language parameter (lang) is provided, using which the language of the returned 3 words is changed in accordance with the specified parameter. Since the API can automatically recognize the language of sent words, the parameter is useful only if you want to get the address in a response in a language other than that used in the request.

If you want to get the coordinates of the corners of the square in the answer, you can use the corresponding additional parameter (corners = true). Together with the coordinates of the center of the square in the answer you will receive the coordinates of its southeast and northwest corners.

When composing your interface, it may be useful to know the lengths of the elements. The length of each word in what3words is 3 to 18 characters, and the vast majority of words describing objects on land are 4 to 12 characters long. Thus, the length of an address of 3 words is from 14 (3x4 letters + 2 points) to 38 (3x12 letters + 2 points) characters.

URL
http://api.what3words.com/w3w

Required GET Parameters
keyyour API key
stringword 1. word 2. word 3

Advanced GET Options
langadditional language code
corners“True” or “false”

Answer

{
	"type": "3 words",
	"words": ["prom", "cape", "pump"],
	"position": [51.484463, -0.195405],
	"language": "en"
}


Code Samples

GET example
http://api.what3words.com/w3w?key=YOURAPIKEY&lang=en&string=index.home.raft


Php
 'YOURAPIKEY',
		'string' => 'prom.cape.pump'
);
curl_setopt ($ ch, CURLOPT_POST, count ($ fields));
curl_setopt ($ ch, CURLOPT_POSTFIELDS, http_build_query ($ fields));
curl_setopt ($ ch, CURLOPT_HEADER, false);
curl_setopt ($ ch, CURLOPT_RETURNTRANSFER, true);
$ return = curl_exec ($ ch);
$ return = json_decode ($ return, true);
curl_close ($ ch);


Linux Curl
curl --data "key = YOURAPIKEY & string = prom.cape.pump" http://api.what3words.com/w3w


JQuery
data = {
	'key': 'YOURAPIKEY',
	'string': 'prom.cape.pump'
};
$ .post ('http://api.what3words.com/w3w', data, function (response) {
	console.log (response);
});



Regular expressions
/^\p{Lasket+\.\p{L►+\.\p{L►+$/u


2. Convert location to 3 words



Each set of latitude / longitude coordinates falls into one of the squares of the what3words global grid and has an address of 3 words corresponding to it. The coordinates describing the location within the same square have the same address. This procedure returns the coordinates of the center of the square and its address of 3 words.

An additional language parameter (lang) can be used to select the language in which you will receive an address of 3 words. By default, the interface uses addresses in English. You can also request the coordinates of the corners of the square using the parameter (corners = true). As in the first procedure, the answer will contain the coordinates of the southwest and northeast corners of the square.

URL
http://api.what3words.com/position

GET Options
key (required)your API key
position (required)lat, lng (in degrees)
langadditional language code
corners“True” or “false”

Answer
{
	"words": ["prom", "cape", "pump"],
	"position": [51.484463, -0.195405],
	"language": "en"
}

Code Samples

GET example
http://api.what3words.com/position?key=YOURAPIKEY&lang=en&position=51.521251,-0.203586


Php
 'YOURAPIKEY',
		'position' => '51 .484463, -0.195405 '
);
curl_setopt ($ ch, CURLOPT_POST, count ($ fields));
curl_setopt ($ ch, CURLOPT_POSTFIELDS, http_build_query ($ fields));
curl_setopt ($ ch, CURLOPT_HEADER, false);
curl_setopt ($ ch, CURLOPT_RETURNTRANSFER, true);
$ return = curl_exec ($ ch);
$ return = json_decode ($ return, true);
curl_close ($ ch);


Linux Curl
curl --data "key = YOURAPIKEY & position = 51.484463, -0.195405" http://api.what3words.com/position


JQuery
data = {
	'key': 'YOURAPIKEY',
	'position': '51 .484463, -0.195405 '
};
$ .post ('http://api.what3words.com/position', data, function (response) {
	console.log (response);
});



3. Getting a list of available what3words address languages



URL
http://api.what3words.com/get-languages

Required GET Parameters
keyyour API key

Answer
{
	"languages": {
					{"code": "en",
					  "name": "English"},
					{..}
	}
}

Code Samples

GET example
http://api.what3words.com/get-languages?key=YOURAPIKEY&lang=en&position=51.521251,-0.203586
http://api.what3words.com/get-langauges?key=YOURAPIKEY&lang=en&strong=index.home.raft


Php
 'YOURAPIKEY'
);
curl_setopt ($ ch, CURLOPT_POST, count ($ fields));
curl_setopt ($ ch, CURLOPT_POSTFIELDS, http_build_query ($ fields));
curl_setopt ($ ch, CURLOPT_HEADER, false);
curl_setopt ($ ch, CURLOPT_RETURNTRANSFER, true);
$ return = curl_exec ($ ch);
$ return = json_decode ($ return, true);
curl_close ($ ch);


Linux Curl
curl --data "key = YOURAPIKEY & position = 51.484463, -0.195405" http://api.what3words.com/position


JQuery
data = {
	'key': 'YOURAPIKEY',
	'position': '51 .484463, -0.195405 '
};
$ .post ('http://api.what3words.com/position', data, function (response) {
	console.log (response);
});



You can get acquainted with the API now. Register at this link , indicating at the bottom that you are registering to receive an API key. Later, we will tell you in detail about our libraries, SDKs and other tools for developers.
Tags:

Also popular now: