Запросы к сервису

Запрос Описание
Доступ к сети дорог
distance Расчет маршрута между двумя точками.
distancematrix Расчет матрицы расстояний между многими точками (максимум 25х25 точек).
tsp Решение "задачи коммивояжёра" (максимум 25 точек).
Доступ к данным
search Запрос позволяет получать данные по координатам (геозапрос) и по тексту. В запросе указывается категория интересующих данных и параметры поиска. Этот запрос не возвращает всей геометрии объекта, только гео-центроид (geo_centroid) и ограничивающую рамку (bbox). В ответе для каждого объекта указан url для получения полной геометрии.
geocode Запрос геокодирования - получение объекта по тексту. В отличие от запроса search поиск происходит по все базе данных, по всем категориям. Этот запрос не возвращает всей геометрии объекта, только гео-центроид (geo_centroid) и ограничивающую рамку (bbox). В ответе для каждого объекта указан url для получения полной геометрии.
feature Получить геометрию и полное описание объекта. Передавая несколько ID объектов через запятую, можно получить геометрию до 255-ти объектов.
Операции с данными
buffer Построить буферную зону вокруг геометрии. Геометрию можно задавать в формате WKT или с помощью ID объекта.
location Вычислить координаты точки, по заданным координатам другой точки, а также расстоянию и направлению, соединяющим эти точки. Координата базовой точки задается как lng,lat или с помощью ID объекта.

Расчет маршрута /distance

Расчет маршрута по двум точкам. Есть возможность указать точки, через которые должен и через которые не должен проходить маршрут.

Схема запроса

http://api.visicom.ua/data-api/3.0/core/distance.json?[origin][&destination][&waypoints][&locks][&mode][&accuracy][&key][&callback]

Параметры запроса

Параметр Описание
origin|o Стартовая точка. Идентификатор объекта или широта и долгота в виде lng,lat. Также можно задать геометрию в формате WKT с количеством вершин не более 250.
destination|d Финишная точка. Идентификатор объекта или широта и долгота в виде lng,lat. Также можно задать геометрию в формате WKT с количеством вершин не более 250.
waypoints|w Список промежуточных точек (не более 25). Точка описывается идентификатором объекта или широтой и долготой в виде lng,lat или в формате WKT с количеством вершин не более 250. Символ '|' - разделитель точек в списке.
locks|l Массив координат блокировок проездов. Блокировка описывается широтой и долготой в виде lng,lat. Для автомобильных проездов запрещает прокладку маршрута в месте блокировки. Имеет смысл только для режима расчета driving и driving-shortest. Символ '|' - разделитель точек в списке.
mode|m Режим расчета маршрута. Может принимать значения driving (оптимальный маршрут по автомобильным дорогам), driving-shortest (кратчайший маршрут по автомобильным дорогам), direct (раcстояние по прямой). По умолчанию расчет происходит в режиме driving.
geometry|g Параметр указывет, возвращать ли в ответе геометрию маршрута. Может принимать значения no (не возвращать), path (возвращать геометрию маршрута между двумя точками как LineString). По умолчанию значение no - геометрия не возвращается.
accuracy|a Генерализация геометрии маршрута в метрах. По умолчанию принимается 10 м.
key Ключ авторизации.
callback Имя функции для JSONP запроса к серверу.

Примеры запроса

http://api.visicom.ua/data-api/3.0/core/distance.json?origin=30.42612,50.45111&destination=30.44946,50.45682 [JSON]

http://api.visicom.ua/data-api/3.0/core/distance.json?origin=ADR3K0MXU9ZPTRK0P8&destination=30.52239,50.44777&waypoints=30.54173,50.44497&geometry=path [JSON]

Ответ на запрос

Структура ответа на запрос distance зависит от значения параметра geometry.

geometry описание
no

{
    "distance": 1234
}
[schema]
                
Объект с одним полем distance - длина маршрута в метрах.
path

{
  "type": "Feature",
  "properties": {
    "distance": 3038,
    "origin": { "type": "Point", "coordinates": [30.42615,50.45119]},
    "destination": { "type": "Point", "coordinates": [30.44679,50.45716]}
  },
  "geometry": {
    "type": "LineString",
    "coordinates": [[30.42615,50.45119],[30.42749,50.45097],
      [30.42674,50.44899],[30.43016,50.44846],[30.43318,50.44802],
      [30.43347,50.44879],[30.4339,50.44997],[30.43456,50.45171],[30.43622,50.45597],
      [30.44134,50.45515],[30.4464,50.45433],[30.44656,50.45423],[30.44661,50.45415],
      [30.44663,50.45409],[30.44657,50.4539],[30.44643,50.45351],[30.44635,50.45342],
      [30.44625,50.45338],[30.44614,50.45335],[30.44591,50.45333],[30.44579,50.45334],
      [30.44569,50.45338],[30.44562,50.45344],[30.44553,50.45365],[30.44609,50.4551],
      [30.4463,50.4557],[30.44651,50.45627],[30.44679,50.45716]]
  },
  "bbox": [30.42615,50.44802,30.44679,50.45716]
}
[schema]
                
В ответе возвращается GeoJSON-объект типа Feature. Поле geometry содержит объект типа LineString. Поле properties содержит JSON-объект с полями:
  • origin тип Point - стартовая точка
  • destination тип Point - финишная точка
  • distance - длина маршрута в метрах

Если не удалось рассчитать маршрут, то возвращается пустой объект {}.

Протестировать как работает расчет маршрута можно с помощью инструмента Дистанция. Для этого необходимо получить ключ доступа.

Матрица расстояний /distancematrix

Расчет дистанций для матрицы исходных и конечных точек.

Схема запроса

http://api.visicom.ua/data-api/3.0/core/distancematrix.json?[origins][&destinations][&locks][&mode][&key][&callback]

Параметры запроса

Параметр Описание
origins|o Массив координат исходных точек. Точка описывается идентификатором объекта, или широтой и долготой в виде lng,lat или в формате WKT с количеством вершин не более 250. Символ '|' - разделитель точек в списке.
destinations|d Массив координат конечных точек. Точка описывается идентификатором объекта, или широтой и долготой в виде lng,lat или в формате WKT с количеством вершин не более 250. Символ '|' - разделитель точек в списке.
locks|l Массив координат блокировок проездов. Блокировка описывается широтой и долготой в виде lng,lat. Для автомобильных проездов запрещает прокладку маршрута в месте блокировки. Имеет смысл только для режима расчета driving и driving-shortest. Символ '|' - разделитель точек в списке.
mode|m Режим расчета маршрута. Может принимать значения driving (оптимальный маршрут по автомобильным дорогам), driving-shortest (кратчайший маршрут по автомобильным дорогам), direct (раcстояние по прямой). По умолчанию расчет происходит в режиме driving.
key Ключ авторизации.
callback Имя функции для JSONP запроса к серверу.

Параметры запроса

http://api.visicom.ua/data-api/3.0/core/distancematrix.html?origins=25.42168,50.75275|28.63243,50.28956|30.54474,50.47389|31.34674,51.45807|34.78168,50.91329&destinations=25.42168,50.75275|28.63243,50.28956|30.54474,50.47389|31.34674,51.45807|34.78168,50.91329 [JSON]

http://api.visicom.ua/data-api/3.0/core/distancematrix.html?origins=30.36277,50.51605|30.49667,50.49508|30.59761,50.45226|30.51383,50.44789&destinations=30.36277,50.51605|30.49667,50.49508|30.59761,50.45226|30.51383,50.44789&mode=driving-shortest [JSON]

Ответ на запрос


{
  "rows": [
    [{"distance": 254032,"status": "OK"},{"distance": 401441,"status": "OK"},{"distance": 540414,"status": "OK"},{"distance": 733783,"status": "OK"}],
    [{"distance": 0,"status": "0"},{"distance": 151878,"status": "OK"},{"distance": 290851,"status": "OK"},{"distance": 484220,"status": "OK"}],
    [{"distance": 148398,"status": "OK"},{"distance": 0,"status": "0"},{"distance": 139644,"status": "OK"},{"distance": 333013,"status": "OK"}],
    [{"distance": 294323,"status": "OK"},{"distance": 145506,"status": "OK"},{"distance": 0,"status": "0"},{"distance": 303204,"status": "OK"}],
    [{"distance": 479259,"status": "OK"},{"distance": 330443,"status": "OK"},{"distance": 302446,"status": "OK"},{"distance": 0,"status": "0"}]
  ]
}
[schema]
    

Ответ возвращается в виде массива строк. Каждая строка содержит длину маршрута из исходных точек в текущую конечную.

Задача коммивояжёра /tsp

Определение порядка объезда пунктов.

Схема запроса

http://api.visicom.ua/data-api/3.0/core/tsp.json?[waypoints][&round_trip][&locks][&mode][&key][&callback]

Параметры запроса

Параметр Описание
waypoints|w Массив точек для расчета. Максимум 25. Первая зафиксирована как старт. Точка описывается идентификатором объекта, или широтой и долготой в виде lng,lat или в формате WKT с количеством вершин не более 250. Символ '|' - разделитель точек в списке.
round_trip|rt Булевское значение, возвращаться ли в первую точку. Если false, то за финишную точку принимается последняя точка в массиве waypoints. Значение по умолчанию true.
locks|l Массив координат блокировок проездов. Блокировка описывается широтой и долготой в виде lng,lat. Для автомобильных проездов запрещает прокладку маршрута в месте блокировки. Имеет смысл только для режима расчета driving и driving-shortest. Символ '|' - разделитель точек в списке.
mode|m Режим расчета маршрута. Может принимать значения driving (оптимальный маршрут по автомобильным дорогам), driving-shortest (кратчайший маршрут по автомобильным дорогам), direct (раcстояние по прямой). По умолчанию расчет происходит в режиме driving.
key Ключ авторизации.
callback Имя функции для JSONP запроса к серверу.

Примеры запроса

http://api.visicom.ua/data-api/3.0/core/tsp.html?waypoints=28.71483,50.29734|34.46411,44.89917|31.27979,51.50313|37.76207,47.98739|24.01646,49.8392|32.41791,50.90552 [JSON]

http://api.visicom.ua/data-api/3.0/core/tsp.html?waypoints=31.6032,48.61124|34.46411,44.89917|31.27979,51.50313|37.76207,47.98739|24.01646,49.8392|32.41791,50.90552&round_trip=false [JSON]

Ответ на запрос


{
  "list": [{"index": 0},{"index": 4},{"index": 1},{"index": 3},{"index": 2},{"index": 5}]
}    
[schema]  
    
Упорядоченный список точек объезда. Возвращается JSON-объект с одним полем list, в котором находится массив индексов точек в поле waypoints запроса. Индексация с нуля.

Поиск данных /search

Поиск стран, объектов админивно-территориального деления, городов, улиц, адресов и точек интереса.

Схема запроса

http://api.visicom.ua/data-api/3.0/[lang]/search/[categories].[format]?[text|t][&word_text|wt][&near|n|intersect|i|contains|co][&radius|r][&limit|l][&country|c][&key][&callback]

Параметры запроса

Параметр запроса Описание
lang Язык запроса и ответа. Один из (ru,uk,en)
categories Имена категорий через запятую, в этих категориях будет выполняться поиск объектов (список категорий).
format Формат данных (json, csv).
text|t Текст, который должен встречаться в описании объекта.
Пример: text=Крещатик, t=Жовтень.
word_text|wt Слова, которые должны встречаться в описании объекта.
Пример: word_text=Киев. В поиск не попадут Киевский, Киевская и т.д.
radius|r Радиус в метрах вокруг местоположения, которое заданно параметром near. Максимум 10 000 метров.
near|n Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat. Запрос возвращает объекты, сортированные по удаленности от заданного местоположения.
Пример: near=POIA1KIGKN, n=30.5113,50.4550.
intersect|i Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat. Запрос возвращает объекты, геометрия которых пересекается с геометрией, описанной данным параметром. Пример: i=POLYGON ((30.2407 50.3848, 30.6094 50.5011, 30.6537 50.3114, 50.3848 30.2407)).
contains|co Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat. Запрос возвращает объекты, геометрия которых находится внутри геометрии, описанной данным параметром. Пример: co=POLYGON ((30.2407 50.3848, 30.6094 50.5011, 30.6537 50.3114, 50.3848 30.2407)).
limit|l Максимальное количество возвращаемых объектов. Максимум 250.
country|c Код страны.
key Ключ авторизации.
callback Имя функции для JSONP запроса к серверу.

near, intersect и contains — взаимоисключающие параметры.

text, word_text — взаимоисключающие параметры.

Данный запрос не возвращает полное геометрии объектов. В ответе есть только гео-центроид и гео-центроид (geo_centroid) и ограничивающая рамка (bbox). Для получения полного описания и геометрии объекта используйте запрос /feature.

Ответ на запрос

Структура ответа на запрос /search зависит от значения параметра categories (список категорий). Схемы ответа в зависимости от categories можно посмотреть перейдя по ссылкам:

Пример

Получить все улицы Киева, в имени которых есть слово «Красноармейская»:
http://api.visicom.ua/data-api/3.0/ru/search/adr_street.json?text=Киев,%20Красноармейская [JSON]

Получить все рестораны в радиусе 300 метров от компании Визиком:
http://api.visicom.ua/data-api/3.0/ru/search/poi_restaurant.json?near=POIA1KIGKN&radius=300 [JSON]

Получить кинотеатры, в имени которых есть слово «Kyiv» (английский язык):
http://api.visicom.ua/data-api/3.0/en/search/poi_cinema.json?text=Kyiv [JSON]

Получить станции метро в Харькове (украинский язык):
http://api.visicom.ua/data-api/3.0/uk/search/poi_underground_railway_station.json?intersect=STL1NWULT [JSON]

Получить улицы, пересекающие треугольник (заданный в WKT):
http://api.visicom.ua/data-api/3.0/ru/search/adr_street.json?i=POLYGON((24.014090 49.83404,24.01409
49.83865,24.01728 49.83865, 24.014090 49.83404))

Получить населенные пункты, в имени которых есть слово «Киев»:
http://api.visicom.ua/data-api/3.0/ru/search/adm_settlement.json?text=Киев [JSON]

Получить населенные пункты, в имени которых есть слова, начинающиеся с букв «Киев»:
http://api.visicom.ua/data-api/3.0/ru/search/adm_settlement.json?text=Киев* [JSON]

Геокодирование /geocode

Поиск объектов по всей базе.

Схема запроса

http://api.visicom.ua/data-api/3.0/[lang]/geocode[.format]?[text|t][&word_text|wt][&near|n|intersect|i|contains|co][&radius|r][&limit|l][&country|c][&boost_country|bc][&zoom][&key][&callback]

Параметры запроса

Параметр запроса Описание
lang Язык запроса и ответа. Один из (ru,uk,en)
format Формат данных (json, csv).
text|t Текст, который должен встречаться в описании объекта.
Пример: text=Крещатик, t=Жовтень.
word_text|wt Слова, которые должны встречаться в описании объекта.
Пример: word_text=Киев. В поиск не попадут Киевский, Киевская и т.д.
near|n Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat. Запрос возвращает объекты, сортированные по удаленности от заданного местоположения.
Пример: near=POIA1KIGKN, n=30.5113,50.4550.
radius|r Радиус в метрах вокруг местоположения, которое заданно параметром near. Максимум 10 000 метров.
intersect|i Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat. Запрос возвращает объекты, геометрия которых пересекается с геометрией, описанной данным параметром. Пример: i=POLYGON ((30.2407 50.3848, 30.6094 50.5011, 30.6537 50.3114, 50.3848 30.2407)).
contains|co Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat. Запрос возвращает объекты, геометрия которых находится внутри геометрии, описанной данным параметром. Пример: co=POLYGON ((30.2407 50.3848, 30.6094 50.5011, 30.6537 50.3114, 50.3848 30.2407)).
zoom|z Мастаб карты по спецификации TMS Чем меньше масштаб, тем меньше учитывается координаты указанные параметром near при расчете релевантности объектов.
limit|l Максимальное количество возвращаемых объектов. Максимум 250.
country|c Код страны.
boost_country|bs Код страны. Если не указан параметр country, то объекты в указанной этим параметром стране имеют больший приоритет.
key Ключ авторизации.
callback Имя функции для JSONP запроса к серверу.

near, intersect и contains — взаимоисключающие параметры.

text, word_text — взаимоисключающие параметры.

Данный запрос не возвращает полные геометрии объектов. В ответе есть только гео-центроид (geo_centroid) и ограничивающая рамка (bbox). Для получения полного описания и геометрии объекта используйте запрос, описанный ниже.

Ответ на запрос

Структура ответа на запрос /geocode зависит от категории объекта (список категорий). Схемы ответа в зависимости от categories можно посмотреть перейдя по ссылкам:

Пример

Найти адрес г. Киев, ул. Крещатик, 26:
http://api.visicom.ua/data-api/3.0/ru/geocode.json?text=г. Киев,%20ул.%20Крещатик,%2026 [JSON]

Полное описание объекта /feature

Полчучение геометрии и всей информации по объекту. Поисковый запрос search возвращает только основную информацию по объектам, без геометрии.

Схема запроса

http://api.visicom.ua/data-api/3.0/[lang]/feature/[id].[format][?key][&callback]

Параметры запроса

Параметр Описание
lang Язык ответа. Один из (ru,uk,en)
id Идентификатор объекта.
format Формат данных (json, csv).
geometry Параметр указывет, возвращать ли в ответе геометрию объекта. Может принимать значения:
no - не возвращаять геометрию (поле geometry отсутсвует),
centroid - не возвращаять всю геометрию, а только geo_centroid.
Если параметр не указан, то геометрия в ответе присутствует.
callback Имя функции для JSONP запроса к серверу.

Если объект с указанным id не найден — возвращается код НТТP 404.

В параметре id можно передать несколько идентификаторов объектов, разделенных запятой. Максимум 250.

Ответ на запрос

Структура ответа на запрос feature зависит от значения параметра categories. Смотри ссылки на схемы ответов в описании search.

Пример

http://api.visicom.ua/data-api/3.0/ru/feature/POIA1KIGKN.json [JSON]

Буферная зона /buffer

Расчет буферной зоны вокруг переданной геометрии или объекта.

Схема запроса

http://api.visicom.ua/data-api/3.0/core/buffer.json?[near|n]

Параметры запроса

Параметр Описание
near|n Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat.
radius|r Радиус буферной зоны в метрах. Максимум 10 000 метров. Если радиус отрицательный, то в ответе возвращается буферная зона отрицательной ширины.

Ответ на запрос

В ответ возвращается GeoSJON-объект, описывающий геометрию буферной зоны. [schema]

Пример

Построить буферную зону вокруг Крещатика радиусом 250 метров:
http://api.visicom.ua/data-api/3.0/core/buffer.json?near=STR3K0MXUAGD&radius=250 [JSON]

Прямая геодезическая задача /location

Получение точки по азимуту и расстоянию, прямая геодезическая задача — вычисление координат некоторой точки, лежащей на земной поверхности (фактически на эллипсоиде), по заданным координатам другой точки, а также расстоянию и направлению, соединяющим эти точки.

Схема запроса

http://api.visicom.ua/data-api/3.0/core/location.[format]?[start|s][&azimut|a][&distance|d]

Параметры запроса

Параметр Описание
start|s Базовая точка. Идентификатор объекта или геометрия в формате WKT с количеством вершин не более 250. Для точек возможна упрощенная запись в виде lng,lat. Для линий и полигонов вычисляется центроид.
azimut|a Азимут (дирекционный угол) — в градусах.
distance|d Дистанция в метрах.
format Формат данных (json, csv).

Ответ на запрос

В ответ возвращается GeoSJON-объект, описывающий искомую точку. [schema]

Пример

Получить точку, отдаленную на 5 км на юго-запад от Лаврской колокольни:
http://api.visicom.ua/data-api/3.0/core/location.json?start=30.55631,50.43474&azimut=225&distance=5000 [JSON]