Изучаем API HTTP-маршрутизатора сервиса CloudMade

В этой заметке я продолжу рассказ о картографическом сервисе CloudMade (начало смотри здесь) и рассмотрю, как можно использовать API HTTP-маршрутизатора.

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

Для получения данных о маршруте между двумя точками необходимо отправить запрос к маршрутизатору по протоколу HTTP.

Пример такого запроса:

http://routes.cloudmade.com/56eded06210846ecbb758f29e7c28152/api/0.3/56.32233,43.948743,56.315914,43.99581/bicycle.js?lang=ru

Разберем пример подробно, а затем я перечислю все параметры которые можно использовать в запросе.

В самом началеhttp://routes.cloudmade.com/ — это адрес сервера к которому мы обращаемся.

Следующий параметр через слеш — ключ API для Вашего сайта.

После этого идет параметр API и версия API — 0.3.

Затем, через запятую указываются координаты начальной и конечной точки маршрута (широта, долгота).

Следующий параметр bicycle — определяет вид передвижения (на велосипеде).

Предпоследний параметр (js) — определяет формат вывода результатов JSON.

Последний (lang), после знака вопроса, язык вывода инструкций маршрутизатора (ru – русский).

Параметров для запроса к маршрутизатору существует больше чем в примере, перечислю их по порядку.

Параметры запроса к маршрутизатору:

start_point — координаты начала маршрута в формате широта, долгота (lat,lon);
end_point — координаты конца маршрута в формате широта, долгота (lat,lon);
route_type — вид передвижения (автомобиль — car, велосипед — bicycle или пешком — ‘foot );
output_format — формат вывода результатов ("js", "gpx")

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

transit_points — указывать дополнительные точки, через которые должен пройти маршрут, они указываются в порядке следования в квадратных скобках, например, [51.2227,4.4120,51.2,4.41];
route_type_modifier — модификатор вида передвижения, на данный момент доступен один параметр — shortest, кратчайший маршрут на автомобиле;
lang — iso 2 символьный код языка вывода, по-умолчанию en, возможные значения доступных языков ( de, en, es, fr, hu, it, nl, ro, ru, se, vi, zh);
units — единицы измерения растояния, километры и мили (km или miles), по умолчанию — km;
callback — указывается функция обратного вызова, например, callback=routeLoaded, тогда ответ будет представлен в виде функции routeLoaded(JSON_object).

Возможные форматы ответа: "js" или "gpx".

Теперь рассмотрим, формат ответа маршрутизатора.

Пример ответа в формате JS (JSON):

{
"version":0.3,
"status":0,
"route_summary":{
"total_distance":4646,
"total_time":873,
"start_point":"улица Литвинова",
"end_point":"улица Звездинка"
},
"route_geometry":[
[
56.32233,
43.948761
],
[
56.322529,
43.948818
],
[
56.323139,
43.948971
],
 
...
 
[
56.31591,
43.995811
]
],
"route_instructions":[
[
"Направляйтесь на север по улица Литвинова",
202,
0,
36,
"0.2 км",
"N",
9.7
],
[
"Поверните направо на Канавинская улица",
241,
6,
87,
"0.2 км",
"S",
179.4,
"TR",
94.1
],
[
"Поверните налево",
155,
9,
28,
"0.2 км",
"E",
82.4,
"TL",
264.6
],
 
...
 
[
"Примите вправо на улица Звездинка",
14,
89,
3,
"14 м",
"E",
70.5,
"TSLR",
25.1
]
]
}

Параметр version — обозначает версию API, в данном случае 0.3

status — обозначает получен ответ (0) или произошла ошибка (1)

Если произошла ошибка, то следующим идет параметр status_message — содержит сообщение об ошибке.

route_summary — содержит данные о маршруте

total_distance — длина маршрута в метрах;

total_time — время движения по маршруту в секундах;

start_point — название начальной точки маршрута;

end_point — название конечной точки маршрута;

В случае указания в запросе транзитных точек, они перечисляются в параметре transit_points: [[наименование точки, широта, долгота], … [наименование точки, широта, долгота]]

route_geometry — содержит в себе координаты всех точек маршрута в виде массива, в проекции wgs84(EPSG:4326) .

route_instructions — содержит набор инструкций о движении по маршруту.

Параметры для инструкций:

Первая строка — текст инструкции, например, Поверните направо;

length, double — длина отрезка маршрута в метрах;

position, int — значение координат первой точки сегмента в route_geometry;

length_caption , String — длина сегмента в указанных единицах, например, 22 м, 23,4 км, 14,4 км

earth_direction , String — направление движения по сторонам света начала отрезка маршрута (в настоящее время поддерживаются только 8 направлений, N, NE, E, SE, S, SW, W, NW);

azimuth, double — азимут;

turn_type , String — код типа очереди, опционально, отсутствует для первого сегмента:

— C — продолжать (сразу),
— TL — поворот налево.
— TSLL — поворот налево плавный,
— TSHL — повернуть строго налево,
— TR — повернуть направо,
— TSLR — плавно повернуть направо,
TSHR — резкий поворот направо,
ТU — разворот

turn_angle — угол в градусах поворота между двумя сегментами, 0 для двигаться прямо, 90, повернуть

направо, 270, повернуть налево, 180 для разворота.

Пример в формате GPX:

<?xml version="1.0" encoding="UTF-8"?>
<gpx creator="CloudMade" version="1.1" xmlns="http://www.topografix.com/GPX/1/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
<metadata>
<author>
<name>CloudMade</name>
<email id="support" domain="cloudmade.com" />
<link rel="nofollow" href="http://maps.cloudmade.com"></link>
</author>
<copyright author="CloudMade">
<license>http://cloudmade.com/faq#license</license>
</copyright>
<time>2011-10-16T09:22:21</time>
</metadata>
<extensions>
<distance>4646</distance>
<time>873</time>
<start>улица Литвинова</start>
<end>улица Звездинка</end>
</extensions>
<wpt lat="56.322327" lon="43.948761"/>
<wpt lat="56.322525" lon="43.948826"/>
<wpt lat="56.323135" lon="43.948967"/>
 
...
 
<wpt lat="56.31591" lon="43.995811"/>
<rte>
<rtept lat="56.322327" lon="43.948761">
<desc>Направляйтесь на север по улица Литвинова, 0.2 км</desc>
<extensions>
<distance>202</distance>
<time>36</time>
<offset>0</offset>
<distance-text>0.2 км</distance-text>
<direction>N</direction>
<azimuth>9.7</azimuth>
</extensions>
</rtept>
<rtept lat="56.323509" lon="43.950462">
<desc>Поверните направо на Канавинская улица, 0.2 км</desc>
<extensions>
<distance>241</distance>
<time>87</time>
<offset>6</offset>
<distance-text>0.2 км</distance-text>
<direction>S</direction>
<azimuth>179.4</azimuth>
<turn>TR</turn>
<turn-angle>94.1</turn-angle>
</extensions>
</rtept>
<rtept lat="56.321678" lon="43.950409">
<desc>Поверните налево, 0.2 км</desc>
<extensions>
<distance>155</distance>
<time>28</time>
<offset>9</offset>
<distance-text>0.2 км</distance-text>
<direction>E</direction>
<azimuth>82.4</azimuth>
<turn>TL</turn>
<turn-angle>264.6</turn-angle>
</extensions>
</rtept>
 
...
 
<rtept lat="56.315872" lon="43.995602">
<desc>Примите вправо на улица Звездинка, 14 м</desc>
<extensions>
<distance>14</distance>
<time>3</time>
<offset>89</offset>
<distance-text>14 м</distance-text>
<direction>E</direction>
<azimuth>70.5</azimuth>
<turn>TSLR</turn>
<turn-angle>25.1</turn-angle>
</extensions>
</rtept>
</rte>
</gpx>

Документацию по использованию API HTTP-маршрутизатора CloudMade можно прочитать здесь.

Вы скажете, все это конечно хорошо, но для чего это можно использовать?

Вы можете это использовать для организации сервиса построения маршрутов на своем сайте и не обязательно использовать полностью API CloudMade.

Я покажу Вам простой пример реализации такого проекта с использованием API Google Maps и API HTTP-маршрутизатора CloudMade.

1. Используем карту Google

В этом примере мы будем использовать API Google Maps v3 для отображения карты и построения на ней рассчитанного маршрута.

Начальная и конечная точка маршрута задаются путем клика мышью по карте в нужных местах, после этого формируется запрос со значениями координат к HTTP-маршрутизатору CloudMade, ответ в формате JSON затем обрабатывается, по координатам строится с помощью полилинии маршрут, а с права от карты выводится текст с инструкциями о движении по маршруту.

Посмотреть пример в действии.

Рассмотрим код примера.

В начале, после определения необходимых стилей, мы подключаем JavaScript-библиотеку jQuery из хранилища скриптов Google и API Google Maps v3.

После этого в функции инициализации мы определяем переменные для хранения данных:

counter — счетчик числа кликов по карте;

points — массив для хранения координат точек маршрута;

start_point, end_point — для хранения строки с координатами начальной и конечной точки.

Фрагмент кода:

var myOptions = {
	zoom: 14,
	center: new google.maps.LatLng(56.32233,43.948743),
	mapTypeId: google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById('map_canvas'), myOptions);

служит для определения параметров карты: центра карты 56.32233,43.948743, начального масштаба — 14, типа карты — MapTypeId.ROADMAP и размещения стандартных элементов управления на карте.

Карту мы будем создавать в контейнере с id=’map_canvas’.

После мы определяем обработчик кликов по карте google.maps.event.addListener

При каждом клике по карте мы увеличиваем счетчик кликов counter на единицу и проверяем его значение.

Если counter==1, то мы запоминаем координаты точки в переменной start_point, а на карте размещаем маркер.

Если counter==2, то мы также запоминаем координаты точки в end_point, на карту помещаем маркер и формируем запрос к HTTP-маршрутизатору CloudMade.

В запросе мы передаем координаты точек, а также 56eded06210846ecbb758f29e7c28152 — значения ключа API для нашего сайта, версию используемого API – 0.3, параметр car — вид перемещения на автомобиле, js — формат ответа JS(JSON), язык ответа для инструкций — lang=ru, а так как мы производим междоменный запрос передаем имя функции обратного вызова callback, в простейшем случае можно указать значение callback=?

Посылаем запрос методом getJSON и обрабатываем ответ в функции function(json).

С начала мы проверяем значение статуса, если все прошло без ошибок то оно должно равняться нулю.

Разбераем полученные данные, выводим значения:

Растояние всего, м
Время в пути, сек
Начало
Конец

Текст инструкций выводим в контейнер с id=’result’

Координаты точек маршрута добавляем в массив points и по ним строим полилинию на карте.
В случае, если counter имеет значение отличное от 1 или 2 присваиваем ему 0.

И последнее для загрузки карты необходимо с начала полностью загрузить код страницы, это определяется событием google.maps.event.addDomListener(window, ‘load’, initialize);

2. Используем карту OpenStreetMap

Здесь код похож на рассмотренный ранее, отличие заключается в том, что мы создаем новый тип карты OpenStreetMap и работаем с ним.

Посмотреть пример в действии