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



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

Подробнее
Реклама

Комментарии 33

    +6
    Простите, но вы не ответили на мой комментарий (http://habrahabr.ru/company/what3words/blog/250561/#comment_8313971) к вашей прошлой блогозаписи, поэтому я привожу его снова:

    Всё равно, хоть убей не понимаю, чем это лучше, чем разбиение мира на [нумерованные] квадраты, а квадратов на [нумерованные] квадраты, а квадратов на [нумерованные] квадраты, пока не получится сетка 3х3 метра.

    Общая площадь суши планеты Земля 148 939 063,133 км2, это примерно 23x23x23x23x23x23 км2, то есть ВОСЕМЬЮ БУКВАМИ можно закодировать всю сушу с точностью до 2 м2.

    Хочется мнемоники и помехоустойчивости? Окей, генерируем 4 слова, в каждом из которых значащие только первая и последняя буква.

    Бонусы: соседство букв может означать соседство квадратов, а возможность записать любой мусор в середину слов даёт свободу самовыражения.
      +3
      Простой пример.

      Допустим, мы используем 26 букв и у нас есть такая схема соответствия:

      0123456789 0123456789 012345
      ABCDEFGHIJ KLMNOPQRST UVWXYZ

      Тогда «WhaT ThE HelL, GuyS» = WTTE x HLGS = (((22*26+19)*26+19)*26+4) x (((7*26+11)*26+6)*26+18) = 400014 х 130642
      Эта фраза кодирует зону площадью в несколько квадратных метров, про которую известно, что «WhaT ThE ForK, MaN» значительно восточнее.
        +1
        Ещё одно преимущество, если игнорировать буквы внутри слов, опираясь только на крайние буквы — это возможность творчески подойти к своему адресу.

        Что лучше, жить всю жизнь с адресом «крокодил.замена.самовар» (реальный адрес реального дома в вашей системе) или иметь возможность самому подобрать любые слова в формате «К… Л З… А С… Р»?
          –1
          Мы сделали адреса what3words запоминаемыми и универсальными. Вот почему мы не стали использовать 4 слова или буквенно-цифровые обозначения. Альтернативы показали себя не с лучшей стороны. yadi.sk/i/BJmJywkpfLwBx
            +3
            Навязывать людям адреса вроде what3words.com/грех+предатель+страх тоже не здорово.
              +5
              Потыкался ещё в квадратики того же дома и получил среди прочего:
              пессимизм.саронг.живчик
              уродец.частник.сегодняшний
              каталуфа.воротила.гнойничок
              простатит.эволюционный.двадцатый
              бедненький.пастообразный.коррозийный
              нищенски.щекотать.снобизм
              Ни одним из этих адресов я не захотел бы делиться, если бы это был мой адрес и я хотел бы заказать пиццу.

              Помимо неприятных слов есть ещё и редкие и/или непонятные, которые сложно диктовать и запоминать из-за этого:
              дама.септический.гиппокамп
              факторинг.остеопатический.пчеловод
              табулировать.шрам.клинчер
              откусывать.смерить.констриктор
              брокколи.денарий.криогенный
              ржать.репетиция.эпикуреец
              комфорт.аттрактант.ошибочность
              непонятный.кишеть.индикативный
              муар.мониторировать.растоптать
              скротальный.одышка.пентхаус

              И это я всё ещё тыкаю в окрестности несчастного дома с адресом грех.предатель.страх
                –1
                В реальном мире адреса гораздо хуже maps.geotastic.org/rude/
                0
                В вашем графике нет предложенного ruikarikun метода. Так что это не аргумент.
                  0
                  Вы можете разместить указанный метод на графике, все данные для этого есть. yadi.sk/d/p7Wy1r_6fMu78
                –2
                А если говорить о «творческом подходе», он не совсем подходит, когда вам нужно быстро сообщить местоположение чего-либо. Попробуйте составить слова из «К… Л З… А С… Р», отличные от «крокодил.замена.самовар», и посмотрите — сколько времени это у вас займет.
                  0
                  Эээ… по крайней мере это можно сделать в уме. Как ваши три заветных слова составить в уме?
                    0
                    Мы используем совершенно другой подход. Мы даем людям адреса, а не заставляем их придумывать себе адреса самостоятельно.
                      0
                      Так и в предложенном варианте никто не заставляет.

                      Хочешь используй то, что выдаст API преобразования адресов/координат. Если будет стандарт, будет много реализаций таких API. Причем, одни API смогут выдавать слова из словаря IT-шника, другие пригодые для детей дошкольного возраста и т.п. — выбирай какой использовать. Кстати, не думаю что ваши «септические гиппокампы» смогут запомнить и использовать дети.

                      Хочешь придумай себе слова сам, только чтоб были в нежном формате. Можешь придумать что-то семантичное, запоминаемое, что особенно хорошо для коммерческого использования, рекламы.

                      Хочешь вообще не используй слова, а только буквы. В SMS и в Твиттере самое то, да и вообще удобный машиночитакмый вариант.

                      Какие ваши преимущества над этим?

                      Более того, если провести однозначное соответсвтие букв одного языка буквам другого, то получим легкую сквозную интернационализацию, а не как у вас.
                        0
                        Ниже уже описаны преимущества:

                        what3words — точная и простая система, способная дать адреса всем, в том числе и не техническим, людям.

                        Наши словари тщательно составлены таким образом, чтобы исключить возможность ошибки. Мы не используем слова. которые звучат одинаково, и многие другие, способные спровоцировать ошибку. А все похожие комбинации разнесены по разным уголкам планеты.
                          0
                          Если вы не против дискуссии, не могли бы вы, пожалуйста, отвечать по существу, а не маркетинговыми слоганами одно и то же?

                          Например:
                          «Да, с переводом адреса на другой язык у нас проблема. У нас нет нормальной интернационализации, доступной даже без нашего API.»
                          или
                          «Нет, у нас отличная интрнационализация, потому что...» (не могу придумать почему она у вас отличная).

                          Или например:
                          «Да, детям будет трудно использовать наши трехсловные адреса. Но из-за малого количества слов в языках, мы решили, что использовать непонятные слова лучше, чем доступность использования детьми и малообразованными гражданами бедных страх. Это подтверждается статистическим исследованиями ...»
                          или
                          «Мы считаем примуществом использования малопонятных слов, это сподвигнет людей к самообразованию. Мы уверены, что каждый захочет узнать значение слова 'аттрактант' как только увидит его в адресе».

                          И т.д. по всем вопросам.

                            0
                            Я рекомендую вам ознакомиться с лингвистическим анализом словарей what3words. Думаю, эта публикация ответит на большую часть ваших вопросов.
                            habrahabr.ru/company/what3words/blog/249269/

                            Мы не переводим адреса на другой язык, так как для каждого языка разные слова являются «хорошими» (короткими и удобными). Хорошие слова мы используем для адресации густонаселенных районов, а также для адресации той местности, в которой эти адреса с большей вероятностью будут использовать носители языка.

                            Если на какие-то вопросы анализ не даст вам ответа, пожалуйста, обращайтесь.
                              0
                              Благодарю, прочитал.
                              Безусловно, работа со словарями проделана значительная. И использование простых слов по плотности носителей языка, и разделение суши и моря, и «вычесывание» омофонов, и фильтрация вульгарщины.

                              Это все здорово. Но есть куча недостатков, о которых вам пишут в комментариях почти каждой вашей статьи. Вы везде говорите о достоинствах W3W. Но нигде не признаете или не выражаете своего отношения к указанным недостаткам. А именно это мне интересно.
                                0
                                Если речь о том, что в адресах встречаются редкие слова, которые могут быть сложными для запоминания и понимания — это действительно так. Однако, благодаря составленному алгоритму адресации, такие слова достались наиболее пустынным районам. И все еще, адреса из трех сложных и редких слов проще и точнее чем почтовые адреса, особенно в тех самых пустынных районах.
                0
                Первый минус — у двух близких мест первые 7 букв будут одинаковые. Это и плюс, и минус.
                  0
                  Почему это минус?
                    0
                    Легче ошибиться на пару километров.
                      0
                      Я так понимаю, что составление слов с нужными буквами вносит помехоустойчивость и нивелирует этот минус.
                        0
                        Есть у вас две любимые девушки:
                        WhaT ThE HelL, GuyS
                        WaT TreE HeiL, GirL
                        Но у второй из слов фигня какая-то получилась, а первая оказалась парнем. Ну, если у них начала были одинаковые — первая в любом случае оказалась парнем, а вторая, what the hell, замужем.
                          0
                          Простите, три раза перечитал, но так мысль и не понял. Что-то туплю. Можете, пожалуйста, как-то иначе объяснить.
                            0
                            В системе адресации what3words адреса с похожими словами находятся в разных уголках планеты, на разных континентах, и так далеко друг от друга, насколько это только возможно. В идеальном случае автоматическая система корректировки поймет, какой адрес вы имели ввиду и исправит ошибку, либо вы сами догадаетесь, что все-таки ошиблись, и не отправитесь на другой континент.

                            В случае с предложенной выше системой вероятность ошибки очень большая, особенно при таком количестве свободы, которая дается людям на составление адреса самостоятельно. Пример Кащея отлично показывает такую систему на практике.
                              0
                              При использовании словарных слов, шанс на ошибку не больше чем у вас. Зато есть огромный бонус в виде отношения близости в адресах.
                0
                Сама идея интересная, но реализация ИМХО не приживется… мне кажется подобная вещь может стать очень распространенной только если превратится в некоторый открытый стандарт с открытыми словарями и алгоритмом. Но тогда будут проблемы с OneWord)
                Такая система просто обязана работать в оффлайне… корабли в море, спасатели в зоне стихийных бедствий. Может это и удобно, но навигатор без сети превратит визитку магазина с тремя словами в пустую бумажку.
                Есть ли у вас оффлайновая библиотека? Как часто она должна обновляться… ведь если кто-то купил OneWord, то о нем оффлайн навигаторы не узнают.
                  0
                  what3words может работать оффлайн, вся система занимает меньше 10 Мб.
                    +1
                    Что касается OneWord, мы постепенно отказываемся от них. Останутся лишь адреса из 3 слов, однако все, кто успел купить OneWord, смогут их использовать.

                    SDK занимает 6 Мб, и может быть использован в любом навигаторе на суше и на воде.
                    0
                    почему порядок имеет значение?
                      0
                      Потому что в русском и других языках недостаточно слов для составления 57 триллионов комбинаций, но достаточно для составления такого количества комбинаций в определенном порядке.
                        0
                        всего 3!=6 раз, какая тонкая грань!
                      0
                      Чем Linux curl отличается от Mac OS X, FreeBSD и т.д. curl? :)

                      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                      Самое читаемое