Нашей главной задачей было дать адреса каждому месту на планете, и сегодня эта задача выполнена. Сетка квадратов 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 и других инструментах для разработчиков.
