# Visicom API
## Запити API

### Доступ до мережі доріг

| Запит | Опис |
| ------ | -------- |
| [`distance`][1] | Розрахунок маршруту між двома точками.|
| [`tsp`][3] | Рішення "задачі комівояжера" (максимум 50 точок).|
| [`distancematrix`][2] | Розрахунок матриці відстаней між багатьма точками (максимум 25х25 точок).|
| [`snaptoroad`][4] | Прив'язує точки від супутників GNSS до дорожньої мережі. |


[1]:/uk/products/data-api/data-api-references/distance
[2]:/uk/products/data-api/data-api-references/distancematrix
[3]:/uk/products/data-api/data-api-references/tsp
[4]:/uk/products/data-api/data-api-references/snaptoroad

 	
### Доступ до даних

| Запит | Опис |
| ------ | -------- |
| [`geocode`][5] | Пряме і зворотне геокодування (пошук об'єктів за словами з назви, а також пошук за координатами). Можна вибрати тільки категорії об'єктів, які цікавлять. Також можливі комбіновані запити|
| [`feature`][6] | Отримати геометрію і повний опис об'єкта. Передаючи кілька ID об'єктів через кому, можна отримати геометрію до 250-ти об'єктів. |


[5]:/uk/products/data-api/data-api-references/geocode
[6]:/uk/products/data-api/data-api-references/feature


### Операції з даними

| Запит | Опис |
| ------ | -------- |
| [`buffer`][7] | 	Побудувати буферну зону навколо геометрії. Геометрію можна задавати в форматі WKT або за допомогою ID об'єкта.| 
| [`location`][8] | Обчислити координати точки за заданими координатами іншої точки, а також відстанню і напрямком, що з'єднує ці точки. Координата базової точки задається як `lng,lat` або за допомогою ID об'єкта. | 

[7]:/uk/products/data-api/data-api-references/buffer
[8]:/uk/products/data-api/data-api-references/location

## Геокодування /geocode

Пошук країн, об'єктів адміністративно-територіального поділу,
міст, вулиць, адрес і точок інтересу за словами з назви, а також
зворотне геокодування.

### Схема запиту

```http
https://api.visicom.ua/data-api/5.0/[lang]/geocode[.format]?[categories|ci][&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).|
| `categories | ci` | Список [ідентифікаторів категорій][2] через «,» в яких буде виконуватися пошук об'єктів.|
|`categories_exclude|ce`|Список [ідентифікаторів категорій][2] через «,» котрі будуть виключені з результатів пошуку.|
|`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`.|
|`order` | Параметр вказує на тип сортування об'єктів у відповіді. Може приймати значення `relevance` (сортування за релевантністю об'єктів для даного запиту), `distance` (сортування за віддаленістю від місця, вказаного параметром `near`). За замовченням - значення `relevance`.|
|`intersect|i` | Ідентифікатор об'єкта або геометрія в форматі WKT з кількістю вершин не більше 250. Для точок можливий спрощений запис у вигляді `lng,lat`. Запит повертає об'єкти, геометрія яких перетинається з геометрією, описаною даними параметром.|
|`contains|co` |Ідентифікатор об'єкта або геометрія в форматі WKT з кількістю вершин не більше 250. Для точок можливий спрощений запис у вигляді `lng,lat`. Запит повертає об'єкти, геометрія яких знаходиться всередині геометрії, описаної даним параметром.|
|`zoom|z` | Масштаб карти по специфікації TMS. Чим менше масштаб, тим менше враховуються координати, зазначені параметром `near` при розрахунку релевантності об'єктів.|
|`limit|l` | Максимальна кількість об'єктів, що повертаються. Максимум 250.|
|`country|c` | Код країни.|
|`boost_country|bc` | Код країни. Якщо не вказаний параметр `country`, то об'єкти в зазначеній цим параметром країні мають більший пріоритет.|
|`key` | Ключ авторизації «Dapi».|
|`callback` | Ім'я функції для JSONP запиту до сервера.|


**взаємовиключні параметри**

* `near`, `intersect`, `contains`
* `text`, `word_text`
* `categories`, `categories_exclude`

Цей запит не повертає повну геометрію об'єктів. У відповіді є тільки гео-центр ваги (`geo_centroid`) і обмежуюча рамка (`bbox`). Для отримання повного опису і геометрії об'єкта використовуйте запит [`/feature`][1]

### Відповідь на запит

Cтруктура відповіді на запит `/geocode` залежить від категорії об'єкта ([список категорій][2]). Схеми відповіді в залежності від `categories` можна подивитися перейшовши за посиланнями:

* [adm_country](https://api.visicom.ua/data-api/5.0/uk/schema/adm_country)
* [adm_district](https://api.visicom.ua/data-api/5.0/uk/schema/adm_district)
* [adm_level1](https://api.visicom.ua/data-api/5.0/uk/schema/adm_level1)
* [adm_level2](https://api.visicom.ua/data-api/5.0/uk/schema/adm_level2)
* [adm_level3](https://api.visicom.ua/data-api/5.0/uk/schema/adm_level3)
* [hst_district](https://api.visicom.ua/data-api/5.0/uk/schema/hst_district)
* [adm_settlement](https://api.visicom.ua/data-api/5.0/uk/schema/adm_settlement)
* [adr_address](https://api.visicom.ua/data-api/5.0/uk/schema/adr_address)
* [adr_street](https://api.visicom.ua/data-api/5.0/uk/schema/adr_street)
* [roa_road](https://api.visicom.ua/data-api/5.0/uk/schema/roa_road)
* [pois](https://api.visicom.ua/data-api/5.0/uk/schema/pois)

### Приклад

Отримати всі вулиці міста Києва, в імені яких зустрічається слово «Заплавна»:

```http
https://api.visicom.ua/data-api/5.0/uk/geocode.json?categories=adr_street&text=Київ, заплавна&key=YOUR_API_KEY
```

Знайти адресу «м. Київ, вул. Хрещатик, 26»:  

```http
https://api.visicom.ua/data-api/5.0/uk/geocode.json?text=м. Київ, вул. Хрещатик, 26&key=YOUR_API_KEY
```

Отримати всі ресторани в радіусі 300 метрів від компанії Візіком:

```http
https://api.visicom.ua/data-api/5.0/uk/geocode.json?categories=poi_restaurant&near=POIA1KIGKN&radius=300&key=YOUR_API_KEY
```

Знайти найближчу адресу в радіусі 50 м від заданої точки:

```http
https://api.visicom.ua/data-api/5.0/uk/geocode.json?categories=adr_address&near=30.51043,50.45358&r=50&l=1&key=YOUR_API_KEY
```

[1]:/uk/products/data-api/data-api-references/feature
[2]:https://api.visicom.ua/data-api/5.0/uk/categories


## Повний опис об'єкта /feature

Отримання геометрії і всієї інформації по об'єкту. Пошуковий запит [`/geocode`][1] повертає тільки основну інформацію по об'єктах, без геометрії.

### Схема запиту

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

### Параметри запиту

| Параметр | Опис |
| -------- | -------- |
|`lang` | Мова відповіді. Одна з (uk, en, ru).|
|`id` | Ідентифікатор об'єкта. У параметрі можна передати кілька ідентифікаторів об'єктів, розділених комою. Максимальна кількість об'єктів - 250.|
|`format` | Формат даних (json, csv).|
|`geometry` | Параметр вказує, чи повертати у відповіді геометрію об'єкта. Може приймати значення: `no` — не повертати геометрію (поле `geometry` відсутнє). Якщо параметр не вказано, то геометрія до відповіді включається.|
|`callback` | Ім'я функції для JSONP запиту до сервера.|

### Відповідь на запит

Структура відповіді на запит `feature` залежить від значення параметра `categories`. Дивись посилання на схеми відповідей в описі [`/geocode`][1].

### Приклади

```http
https://api.visicom.ua/data-api/5.0/uk/feature/POIA1KIGKN.json?key=YOUR_API_KEY 
```

[1]:/uk/products/data-api/data-api-references/geocode


## Розрахунок маршруту /distance

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

### Схема запиту

```http
https://api.visicom.ua/data-api/5.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. Символ `,` — роздільник точок в списку при використанні ідентифікаторів. Символ `|` — роздільник точок в списку при використанні широти і довготи.|
| `locks|l` | Масив координат блокувань проїздів. Блокування описується ідентифікатором об'єкта або широтою і довготою у вигляді `lng,lat`. Для автомобільних проїздів забороняє прокладку маршруту в місці блокування. Має сенс тільки для режиму розрахунку `driving` та `driving-shortest`. Символ `,` — роздільник точок в списку при використанні ідентифікаторів. Символ `|` — роздільник точок в списку при використанні широти і довготи.|
| `mode|m` | Режим розрахунку маршруту. Може приймати значення `driving` (оптимальний маршрут по автомобільним дорогам), `driving-shortest` (найкоротший маршрут по автомобільним дорогам), `direct` (відстань по прямій). За замовчуванням розрахунок відбувається в режимі `driving`.|
| `geometry|g` | Параметр вказує, чи повертати у відповіді геометрію маршруту. Може приймати значення `no` (не повертати), `path` (повертати геометрію маршруту між двома точками як LineString). За замовчуванням значення `no` - геометрія не повертається.|
| `accuracy|a` | Генералізація геометрії маршруту в метрах. За замовчуванням приймається 10 м.
| `key` | Ключ авторизації «Dapi».|
| `callback` | Ім'я функції для JSONP запиту до сервера.|

### Приклади запиту

```http
https://api.visicom.ua/data-api/5.0/core/distance.json?origin=30.42612,50.45111&destination=30.44946,50.45682&key=YOUR_API_KEY
```

```http
https://api.visicom.ua/data-api/5.0/core/distance.json?origin=POIA1KIGKN&destination=30.52239,50.44777&waypoints=30.54173,50.44497&geometry=path&key=YOUR_API_KEY
```

### Відповідь на запит

Структура відповіді на запит  `distance` залежить від значення параметру `geometry`. 

**`geometry = no`**

```javascript
{
    "distance": 1234
}
```

Об'єкт з одним полем `distance` — довжина маршруту в метрах.


**`geometry = path`**

```javascript
{
    "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
    ]
}
```

У відповіді повертається [GeoJSON][1]-об'єкти типу [Feature][2]. Поле `geometry` містить об'єкт типу [LineString][3]. Поле `properties` містить JSON-об'єкт з полями:

* `origin` тип [Point][4] — стартова точка
* `destination` тип [Point][4] — фінішна точка
* `distance` - довжина маршруту в метрах

Якщо не вдалося розрахувати маршрут, то повертається порожній об'єкт `{}`. 

### Демо

Ви можете переміщати точки.

<iframe src="https://maps.visicom.ua/iframe/uk/725:390/?c/30.5235:50.45259:14/r0/30.49676:50.4492/r1/30.5456:50.4498/" width="100%" height="390" scrolling="no" frameborder="0"></iframe

[1]:http://geojson.org
[2]:http://geojson.org/geojson-spec.html#feature-objects
[3]:http://geojson.org/geojson-spec.html#linestring
[4]:http://geojson.org/geojson-spec.html#point

## Матриця відстаней /distancematrix

Розрахунок дистанцій для матриці вихідних і кінцевих точок.

### Схема запиту

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

### Параметри запиту

| Параметр | Опис |
| -------- | -------- |
`origins|o` | Масив координат вихідних точок. Точка описується ідентифікатором об'єкта, або широтою і довготою у вигляді `lng,lat` або в форматі WKT з кількістю точок не більше 25. Символ `,` — роздільник точок в списку при використанні ідентифікаторів. Символ `|` — роздільник точок в списку при використанні широти і довготи.|
`destinations|d` | Масив координат кінцевих точок. Точка описується ідентифікатором об'єкта, або широтою і довготою у вигляді `lng,lat` або в форматі WKT з з кількістю точок не більше 25. Символ `,` — роздільник точок в списку при використанні ідентифікаторів. Символ `|` — роздільник точок в списку при використанні широти і довготи.|
`locks|l` | Масив координат блокувань проїздів. Блокування описується ідентифікатором об'єкта або широтою і довготою у вигляді `lng,lat`. Для автомобільних проїздів забороняє прокладку маршруту в місці блокування. Має сенс тільки для режиму розрахунку `driving` і `driving-shortest`. Символ `,` — роздільник точок в списку при використанні ідентифікаторів. Символ `|` — роздільник точок в списку при використанні широти і довготи.|
`mode|m` | Режим розрахунку маршруту. Може приймати значення `driving` (оптимальний маршрут по автомобільним дорогам), `driving-shortest` (найкоротший маршрут по автомобільним дорогам), `direct` (відстань по прямій). За замовчуванням розрахунок відбувається в режимі `driving`.|
`key` | Ключ авторизації «Dapi».|
`callback` | Ім'я функції для JSONP запиту до сервера.|

### Приклади запиту

```http
https://api.visicom.ua/data-api/5.0/core/distancematrix.json?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&key=YOUR_API_KEY 
```


### Відповідь на запит

Відповідь повертається у вигляді масиву рядків. Кожен рядок містить дистанції маршрутів з поточної вихідної точки (`origins`) в усі кінцеві (`destinations`).

```javascript
{"rows": [
    [
        {"distance": 0, "status": "OK"},
        {"distance": 12110,"status": "OK"},
        {"distance": 22616,"status": "OK"},
        {"distance": 14885,"status": "OK"}
    ],
    [
        {"distance": 12442,"status": "OK"},
        {"distance": 0,"status": "OK"},
        {"distance": 13060,"status": "OK"},
        {"distance": 9323,"status": "OK"}
    ],
    [
        {"distance": 22793,"status": "OK"},
        {"distance": 14416,"status": "OK"},
        {"distance": 0,"status": "OK"},
        {"distance": 10177,"status": "OK"}
    ],
    [
        {"distance": 16747,"status": "OK"},
        {"distance": 10541,"status": "OK"},
        {"distance": 8706,"status": "OK"},
        {"distance": 0,"status": "OK"}
    ]
]}
```


## Задача комівояжера /tsp

Визначення порядку об'їзду пунктів.

### Схема запиту

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

### Параметри запиту

| Параметр | Опис |
| -------- | -------- |
| `waypoints|w`| Масив точок для розрахунку. Максимум 50. Перша зафіксована як старт. Точка описується ідентифікатором об'єкта, або широтою і довготою у вигляді `lng,lat`. Символ `,` — роздільник точок в списку при використанні ідентифікаторів. Символ `|` — роздільник точок в списку при використанні широти і довготи.|
| `round_trip|rt` | Булівське значення, чи повертатися в першу точку. якщо `false`, то за фінішну точку приймається остання точка в масиві `waypoints`. Значення за замовчуванням `true`.|
| `locks|l` | Масив координат блокувань проїздів. Блокування описується ідентифікатором об'єкта або широтою і довготою у вигляді `lng,lat`. Для автомобільних проїздів забороняє прокладку маршруту в місці блокування. Має сенс тільки для режиму розрахунку `driving` і `driving-shortest`. Символ `,` — роздільник точок в списку при використанні ідентифікаторів. Символ `|` — роздільник точок в списку при використанні широти і довготи.|
| `mode|m` | Режим розрахунку маршруту. Може приймати значення `driving` (оптимальний маршрут по автомобільним дорогам), `driving-shortest` (найкоротший маршрут по автомобільним дорогам), `direct` (відстань по прямій). За замовчуванням розрахунок відбувається в режимі `driving`.|
| `key` | Ключ авторизації «Dapi».|
| `callback` | Ім'я функції для JSONP запиту до сервера.|


### Приклади запиту

```http
https://api.visicom.ua/data-api/5.0/core/tsp.json?waypoints=28.71483,50.29734|31.93485,46.98892|31.27979,51.50313|24.01646,49.8392|32.41791,50.90552&key=YOUR_API_KEY
```

```http
https://api.visicom.ua/data-api/5.0/core/tsp.json?waypoints=31.6032,48.61124|31.93485,46.98892|31.27979,51.50313|24.01646,49.8392|32.41791,50.90552&round_trip=false&key=YOUR_API_KEY
```


### Відповідь на запит

```javascript
{"list": [
    {"index": 0},
    {"index": 1},
    {"index": 3},
    {"index": 4},
    {"index": 2},
    {"index": 5}
]}
```

Упорядкований список точок об'їзду. Повертається JSON-об'єкт з одним полем list, в якому знаходиться масив індексів точок в поле `waypoints` запиту. Індексація з нуля.


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

Розрахунок буферної зони навколо заданої геометрії або об'єкта.

### Схема запиту

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


### Параметри запиту

| Параметр | Опис |
| -------- | -------- |
|`near|n` | Ідентифікатор об'єкта або геометрія в форматі WKT з кількістю вершин не більше 250. Для точок можливий спрощений запис у вигляді `lng,lat`.|
|`radius|r` | Радіус буферної зони в метрах. Максимум 10 000 метрів. Якщо радіус негативний, то у відповіді повертається буферна зона від'ємної ширини.|


###  Відповідь на запит

У відповідь повертається GeoJSON-об'єкт, що описує геометрію буферної зони. [Схема відповіді](https://api.visicom.ua/data-api/4.0/ru/schema/buffer).

### Приклад

Побудувати буферну зону навколо Хрещатика радіусом 250 метрів:

```http
https://api.visicom.ua/data-api/5.0/core/buffer.json?near=STR3K0MXUAGD&radius=250&key=YOUR_API_KEY 
```

## Пряма геодезична задача /location

Отримання точки по азимуту і відстані, пряма геодезична задача - обчислення координат деякої точки, що лежить на земній поверхні (фактично на еліпсоїді), за заданими координатами іншої точки, а також відстані і напрямку, що з'єднує ці точки.

### Схема запиту

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

### Параметри запиту

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

### Відповідь на запит

У відповідь повертається GeoSJON-об'єкт, що описує шукану точку. [Схема відповіді][1].

### Приклад

Отримати точку, віддалену на 5 км на південний захід від Лаврської дзвіниці:

```http
https://api.visicom.ua/data-api/5.0/core/location.json?start=30.55631,50.43474&azimut=225&distance=5000&key=YOUR_AUTHORITY_KEY 
```


[1]:https://api.visicom.ua/data-api/4.0/ru/schema/location

## Прив'язка точок до дорог /snaptoroad

Snap to Road приймає список точок отриманих від супутникових систем
навігації (GNSS) у вигляді широти, довготи, зібраних впродовж маршруту, та
повертає список точок, що формують маршрут, прив'язаний до доріг на
карті. Ви також можете використовувати інтерполяцію по заданих точках. Тоді
відповіддю буде лінія, що відповідає геометрії дороги.

Цей запит може бути важливою частиною при розробці систем
стеження, а саме при візуалізації отриманих супутникових даних.


### Схема запиту

```http
https://api.visicom.ua/data-api/5.0/core/snaptoroad.json?[points][&interpolate][&mode][&key][&callback]
```

### Параметри запиту

| Параметр | Опис |
| -------- | -------- |
| `points|p` | Масив координат точок. Точка задається широтою та довготою у вигляді `lng,lat`. Символ `|` — роздільник точок у списку. Максимальна кількість точок - 250|
| `interpolate|l` | Чи необхідна інтерполяція точок до линії, що повторює повну геометрію дороги з урахуванням перехресть та тунелів. У цьому випадку відповідь буде містити об'єкт [LineString][3]. За замовчуванням `false`.|
| `mode|m` | Режим прив'язки точок. Може приймати значення `driving` (по автомобільним дорогам, приймається за замовчуванням) або `walking` — усі дороги.|
| `separate | s` | При зазначеному параметрі кожна точка в запиті розглядається окремо і не враховуються попередні точки (`interpolate` - ігнорується навіть якщо вказано). Можна використовувати і коли потрібно прив'язати кілька пристроїв до доріг в одному запиті. За замовчуванням `false`. |
| `key` | Ключ авторизації «Dapi».|
| `callback` | Ім'я функції для JSONP запиту до сервера.|

### Приклад запиту

```http
https://api.visicom.ua/data-api/5.0/core/snaptoroad.json?points=30.36277,50.51605|30.49667,50.49508|30.59761,50.45226|30.51383,50.44789&interpolate=true&key=YOUR_API_KEY
```

### Відповідь на запит

Структура відповіді на запит `snaptoroad` залежить від значення параметру `interpolate`  та кількості переданих точок.

Передана одна точка, за будь-якого значення параметру `interpolate`. 

```javascript
{ 
	"type": "Feature",
	"geometry": {
		"type": "Point", 
		"coordinates": [
			30.42615,
			50.45119
		]
	}
}
```

У відповіді повертається [GeoJSON][1]-об'єкт типу [Feature][2]. У полі `geometry` міститься об'єкт типу [Point][4] з координатами, що прив'язані до дороги.

**`interpolate = false`** (за замовчуванням) та передано декілька точок

```javascript
{ 
	"type": "FeatureCollection",
	"bbox": [
		30.42615,
		50.44802,
		30.44679,
		50.45716
	],
	"features": [
		{
			"type": "Feature",
			"geometry": {
				"type": "Point", 
				"coordinates": [
					30.42615,
					50.45119
				]
			}
		},
		{
			"type": "Feature",
			"geometry": {
				"type": "Point", 
				"coordinates": [
					30.43615,
					50.46119
				]
			}
		},
		{
			"type": "Feature",
			"geometry": {
				"type": "Point", 
				"coordinates": [
					30.44615,
					50.47119
				]
			}
		}
	]
}
```

У відповіді повертається [GeoJSON][1]-об'єкт типу [FeatureCollection][5]. Поле features містить масив об'єктів типу [Feature][2] з полем geometry типу [Point][4]. Кожна точка містить координати, що прив'язані до дороги.

**`interpolate = true`** та передано декілька точок

```javascript
{
    "type": "Feature",
    "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
            ]
        ]
    },
    "bbox": [
        30.42615,
        50.44802,
        30.44679,
        50.45716
    ]
}
```

У відповіді повертається [GeoJSON][1]-об'єкт типу [Feature][2]. У полі `geometry` міститься об'єкт типу [LineString][3] з координатами маршруту, що проходить через прив'язані до доріг точки.


### Демо

Ви можете поставити точки клікнувши по карті.

<div id="map" style="height: 100%; width:100%;">
<iframe src="https://api.visicom.ua/uk/iframe/snaptoroad/" width="100%" height="600px" scrolling="no" allowfullscreen></iframe>
</div>


[1]:https://geojson.org/
[2]:https://geojson.org/geojson-spec.html#feature-objects
[3]:https://geojson.org/geojson-spec.html#linestring
[4]:https://geojson.org/geojson-spec.html#point
[5]:https://geojson.org/geojson-spec.html#feature-collection-objects



## Специфікація доступу до тайлів 

**Тайли** — можна використовувати в будь-якій з поширених бібліотек
веб-картографії, таких як [Leaflet][2], [OpenLayers][3] та інших.


### Схема запиту і точка входу

```http
https://tms[n].visicom.ua/2.0.0/[map]/[style]/[z]/[x]/[y].[format][?origin=sw|nw][&key]
```

### Параметри

| Параметр | Опис   |
| -------- | ---------- |
| `n`      | Піддомени - для прискорення завантаження, а також балансування, може приймати значення «порожньо», 0, 1, 2 або 3|
| `map`    | Ім'я набору даних. [Див. детальніше][4]|
| `style`  | Ім'я стилю відображення. Як правило існують базові стилі для будь-якого набору `base` [Див. детальніше][5]|
| `z`      | Рівень деталізації (масштаб) від 0 до 19|
| `x`, `y` | Номер тайла по горизонталі і вертикалі  |
| `format` | Може приймати одне із значень `png` (палітра адаптивна), `jpg`, `svg`, `pdf`|
| `origin` | Схема тайлів [`tms`](#tms) чи `xyz` (`nw`), за замовчуванням [`tms`](#tms) (`sw`) |
|`lang` | Бажана мова підписів, буде використовуватися там, де можливо. Одна з (uk, en) або відсутня |
| `key`      | Ключ авторизації «Visicom Tiles»|

Розміри тайлів 256 х 256 пікс.

### Приклад

Фрагмент коду бібліотеки [Leaflet][2] для підключення тайлів.

```javascript
var map = new L.Map("map", {
    center: new L.LatLng(50.455002, 30.511284),
    zoom: 9,
    layers: [
        new L.TileLayer("https://tms{s}.visicom.ua/2.0.0/planet3/base/{z}/{x}/{y}.png", {
            attribution: "Дані карт © 2025 АТ «<a href='https://api.visicom.ua/'>Візіком</a>»",
            subdomains: "123",
            maxZoom: 19,
            tms: true
        })
    ]
});
```

Результат

<div id="map" style="height: 400px;"></div>
<script>
    document.addEventListener("DOMContentLoaded", function () {
        var map = new L.Map("map", {
            center: new L.LatLng(50.455002, 30.511284),
            zoom: 9,
            layers: [
                new L.TileLayer("https://tms{s}.visicom.ua/2.0.0/planet3/base/{z}/{x}/{y}.png", {
                    attribution: "Дані карт © 2025 АТ «<a href='https://api.visicom.ua/'>Візіком</a>»",
                    subdomains: "0123",
                    maxZoom: 18,
                    tms: true
                })
            ]
        });
    });
</script>  


### Діаграма тайлів TMS<a name="tms"></a>

![Діаграма тайлів TMS](/media/tiles-diagram.png)


[2]:https://leafletjs.com
[3]:https://openlayers.org/
[4]:/uk/products/tiles/tiles-dataset
[5]:/uk/products/tiles/tiles-dataset#styles