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