18 March 2015

Знакомство с API what3words: основные процедуры и сэмплы

what3words corporate blogWebsite developmentAPIGeoinformation services


Нашей главной задачей было дать адреса каждому месту на планете, и сегодня эта задача выполнена. Сетка квадратов what3words покрывает весь земной шар, и у каждого квадрата есть уникальный адрес. Самое время дать возможность каждому использовать адреса из трех слов, и сделать это удобным. Удобно будет, когда каждая карта, навигационное приложение и другие геолокационные сервисы будут поддерживать what3words. Для этого и был создан наш API, о котором мы хотим рассказать подробно.

Мы постарались сделать интерфейс максимально простым, и приложили максимум усилий для того, чтобы сохранить время и нервы разработчиков. Интерфейс выполняет две основных процедуры: преобразование 3 слов в местоположение, и преобразование местоположения в 3 слова. Третья дополнительная процедура — это запрос перечня доступных языков трех слов. В большинстве случаев все общение с API сводится к простым GET-запросам. Ответы предоставляются в JSON.

1. Преобразование 3 слов в местоположение



Процедура превращает 3 слова в пару координат широта/долгота. Адреса what3words даются квадратам размером 3 x 3 метра, а получаемые координаты являются координатами центра такого квадрата. Вместе с координатами в ответе содержатся запрашиваемые три слова, к которым применены все исправления.

Дополнительные параметры

Для этой процедуры предусмотрен дополнительный языковой параметр (lang), при использовании которого изменяется язык возвращаемых 3 слов в соответствии с заданным параметром. Поскольку API умеет автоматически распознавать язык отправляемых слов, параметр пригодится только в том случае, если вы хотите получить в ответе адрес на другом языке, отличном от использованного в запросе.

Если вы хотите получить в ответе координаты углов квадрата, вы можете воспользоваться соответствующим дополнительным параметром (corners=true). Вместе с координатами центра квадрата в ответе вы получите координаты его юго-восточного и северо-западного углов.

При компоновке своего интерфейса может быть полезным знать длины элементов. Длина каждого слова, входящего в адрес what3words составляет от 3 до 18 символов, а подавляющее большинство слов, описывающих объекты на суше имеют длину от 4 до 12 символов. Таким образом длина адреса из 3 слов составляет от 14 (3x4 букв + 2 точки) до 38 (3x12 букв + 2 точки) символов.

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

Обязательные параметры GET
key ваш API-ключ
string слово1.слово2.слово3

Дополнительные параметры GET
lang дополнительный языковой код
corners “true” или “false”

Ответ

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


Сэмплы кода

Пример GET
http://api.what3words.com/w3w?key=YOURAPIKEY&lang=en&string=index.home.raft


PHP
<?php

$ch = curl_init('http://api.what3words.com/w3w');

$fields = array(
		'key' => '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);
});



Регулярные выражения
/^\p{L}+\.\p{L}+\.\p{L}+$/u


2. Преобразование местоположения в 3 слова



Каждый набор координат широта/долгота попадает в один из квадратов глобальной сетки what3words и имеет соответствующий ему адрес из 3 слов. Координаты, описывающие местоположение внутри одного квадрата имеют один и тот же адрес. Данная процедура возвращает координаты центра квадрата и его адрес из 3 слов.

Дополнительный языковой параметр (lang) можно использовать для выбора языка, на котором вы получите адрес из 3 слов. По умолчанию интерфейс использует адреса на английском языке. Вы также можете запросить координаты углов квадрата с помощью параметра (corners=true). Как и в первой процедуре, ответ будет содержать в себе координаты юго-западного и северо-восточного углов квадрата.

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

Параметры GET
key (обязательно) ваш API-ключ
position (обязательно) lat, lng (в градусах)
lang дополнительный языковой код
corners “true” или “false”

Ответ
{
	"words": 	["prom", "cape", "pump"],
	"position": 	[51.484463, -0.195405],
	"language": 	"en"
}

Сэмплы кода

Пример GET
http://api.what3words.com/position?key=YOURAPIKEY&lang=en&position=51.521251,-0.203586


PHP
<?php

$ch = curl_init('http://api.what3words.com/position');

$fields = array(
		'key' => '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. Получение перечня доступных языков адресов what3words



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

Обязательные параметры GET
key ваш API-ключ

Ответ
{
	"languages": {
					{ "code":	"en",
					  "name":	"English" },
					{ .. }
	}
}

Сэмплы кода

Пример GET
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
<?php

$ch = curl_init('http://api.what3words.com/get-languages');

$fields = array(
		'key' => '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);
});



Познакомиться с API можно уже сейчас. Зарегистрируйтесь по этой ссылке, указав в самом низу, что вы регистрируетесь для получения ключа к API. Позднее мы обязательно подробно расскажем о наших библиотеках, SDK и других инструментах для разработчиков.
Tags:what3wordsapiкоординатыадресапроцедуры.
Hubs: what3words corporate blog Website development API Geoinformation services
-1
3.1k 13
Comments 33
Top of the last 24 hours