Опис API

Вступ

Авторизація запитів в диспетчерську систему здійснюється за допомогою API ключів, що генеруються в налаштуваннях диспетчерської системи. Щоб отримати такий ключ, в диспетчерській системі відкрийте меню Налаштування і виберіть вкладку API.

Отримання списку машин

Перед створенням будь-яких моніторингових запитів необхідно створити запит на виведення списку транспортних засобів та їх ідентифікаційних характеристик. Для цього потрібно створити запит (GET):

http://dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=[val]&namefilter=

де "apikey=[val]" – параметр типу "ім'я/значення", в якому "apikey" є іменем, а "[val]" – значенням. Отриманий у налаштуваннях диспетчерської системи API ключ необхідно вставити на місце значення "[val]" даного параметра. Таким чином, запит з введеним значенням параметра apikey буде виглядати наступним чином:

http://dispatch.navitel.ru/api/1.0/vehicles.xml?apikey=00000000000000000000000&namefilter=

Крім того, в кінці запиту також повинен бути параметр фільтра імені

namefilter=[value]

де "[value]" - значення фільтра. Ви можете вказати в значення назву імені об'єкта, інформацію про який ви хочете отримати, або залишити поле порожнім, щоб отримати інформацію про всі об'єкти, як показано в прикладі вище.

В якості відповіді на такий запит буде представлений список машин із зазначенням їх ідентифікаційних характеристик. Код буде представлений у форматі XML або JSON.

<reply> <result type="array"> <v i="0"> <group_name>security_group</group_name> <tracker_id>GALILEOSKY:00000000000000000000000000000000</tracker_id> <tracker_type>GALILEOSKY</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>Subaru</vehicle_name> </v> <v i="1"> <group_name>security_group</group_name> <tracker_id>GRANIT:00000000000000000000000000000</tracker_id> <tracker_type>GRANIT04</tracker_type> <vehicle_id>xxxxx-xxxx-xxxx-xxxxxxxxxxxx</vehicle_id> <vehicle_name>cardabalet</vehicle_name> </v> </result> </reply>

Відповідь містить наступну ідентифікаційну інформацію про засоби пересування: група/компанія (в диспетчерській системі), imei/id трекера, тип трекера, id машини, ім'я машини. Ця інформація необхідна для виконання наступних запитів, в яких вам знадобиться вказувати ідентифікаційні дані тих об'єктів, по яким ви хочете зробити запит.

При написанні запиту ви можете вказати бажаний формат відповіді, яку отримаєте : xml або json. Для цього у запиті після "vehicles" напишіть ".xml" або ".json" (це можливо зробити в будь-якому типі запитів до диспетчерської системи).

Результат цього запиту буде доставлений у формі XML-коду

http://dispatch.navitel.ru/api/1.0/vehicles.xml

у цьому прикладі, результатом такого запиту буде код JSON

http://dispatch.navitel.ru/api/1.0/vehicles.json
Запит на отримання моніторингової інформації

Запит до диспетчерської системи можна представити як сукупність елементів: основний URL і параметри запиту. До базового (основного) URL відноситься вся та частина запиту, яка знаходиться до закінчення вказівки розширення xml або json. Приклад основного URL, використовуваного при створенні будь-яких запитів до диспетчерської системи (винятком є запит на отримання списку машин, який звертається до іншого URL):

http://dispatch.navitel.ru/api/1.0/vehicleinfo.xml?

Параметри запиту являють собою ряд пар типу "ім'я/значення", де кожна пара відділяється амперсандом ("&"). Список параметрів починається відразу після знака, наступного за вказівкою розширення. Кожен параметр має наступну форму:

field=[value]

де "field" –ім'я параметра, а "[value]" – значення. API запити до диспетчерської системи розпізнають наступні імена параметрів: "id", "name", "imei", "time", "what", "apikey". Зверніть увагу, що такі запити чутливі до регістру букв.

Запит зазвичай містить набір таких параметрів:

  1. Ідентифікатори автомобіля. Автомобіль можна вибрати, використовуючи один з трьох доступних для кожного автомобіля ідентифікаторів: "id", "name", "imei". Приклад введення параметра:

    id=[vehicle_static_id_0]

    де "[vehicle_static_id_0]" – це ID автомобіля, який можна дізнатися, зробивши запит на отримання списку машин.

    Ідентифікатори – прості параметри, такі ж, як параметри apikey або якої б то не було ще в запитах до диспетчерської системи. Таким чином, в одному запиті можна вказати більше одного ідентифікатора, що дозволить отримати інформацію про декількох автомобілях відразу.

    Як і інші параметри, параметри-ідентифікатори повинні відділятися один від одного амперсандом:

    id=[vehicle_static_id_0]&id=[vehicle_static_id_0]

    Ви також можете використовувати різні типи ідентифікаторів для вибору автомобілів, наприклад:

    id=[vehicle_static_id_0]&name=[vehicle_name]&imei=[vehilce_imei]&id=[vehicle_static_id_N]

    Якщо вийшло так, що значення різних ідентифікаторів визначають один і той же автомобіль, нічого страшного, цей автомобіль не буде відображений двічі.

  2. Ключ API. Приклад:

    apikey=[val]

    де "apikey" є іменем, а "[val]" – значенням. Отриманий у налаштуваннях диспетчерської системи API ключ необхідно вставити на місце значення "[val]" даного параметра.

  3. Набір потрібних параметрів:

    field=[value]&field=[value]&field=[value]

    де "[field]" – ім'я параметра, "[value]" – значення параметра. Використовуйте таблиці нижче в якості керівництва по написанню моніторингових запитів.

Параметри для фіксованого моменту часу

До цього моменту ви повинні вміти включати в запит ідентифікатори автомобілів і API ключ. Однак недослідженими залишилися моніторингові параметри. Їх можна умовно розділити на дві групи: тимчасові і інформаційні. У цій главі будуть розглянуті інформаційні параметри. Звернення до таких параметрів здійснюється через запити з допомогою використання імені "what" і вибору відповідного значення. Значення різних запитів зазначені в таблиці нижче.

Наприклад, якщо б було необхідно отримати інформацію про швидкість якого-небудь об'єкта на поточний момент часу, треба було б у полі імені параметра вказати "what", а у полі значення, згідно з таблицею, наведеною нижче, вказати значення "speed_kmh":

what=speed_kmh

повний запит виглядав би наступним чином:

http://dispatch.navitel.ru/api/1.0/vehicleinfo.xml?apikey=00000000000000000000000&name=NaviCar&what=speed_kmh

У цьому прикладі була запитана інформація про швидкості об'єкта, іменованого «NaviCar», а також використаний ключ API «00000000000000000000000» для отримання доступу до інформації диспетчерської системи. Аналогічним чином ви можете створювати і інші запити, використовуючи імена і значення для параметрів, зазначені в таблиці нижче.

Опис
Значення
Описзапалювання
Значенняignition
Описширота, довгота
Значенняlat_deg, lon_deg
Описшвидкість
Значенняspeed_kmh
Описнапрямок руху
Значенняdirection_deg
Опискількість супутників, hdop
Значенняsatellite_count, hdop
Описвисота
Значенняaltitude_m
Описпараметри gsm (mcc,mnc,lac и пр)
Значенняmcc, mnc, lac, cellid, signal_strength, timing_advance
Описнапруга зовнішнього живлення
Значенняexternal_power_mv
Описнапруга внутрішньої батареї
Значенняbattery_power_mv
Опистемпература трекера
Значенняtemperature_c
Описпоказання акселерометра (x, y, z)
Значенняacceleration_x_ms2,
acceleration_y_ms2,
acceleration_z_ms2
Опистривожна кнопка
Значенняalarm_on
Опистемпература охолоджуючої рідини
Значенняcoolant_temp_c
Описобороти двигуна
Значенняengine_rpm
Описрівень палива (%)
Значенняfuel_percent
Описзагальний пробіг
Значенняmileage_km
Описзагальна витрата палива
Значенняtotal_fuel_consumed_l
Описрівень палива (can)
Значенняcan_fuel_l
Описчас напрацювання двигуна (can)
Значенняmhours
Описшвидкість (can)
Значенняcan_speed_kmh
Описрівень палива (порахований, перетворений і т.п.)
Значенняfuel_l
Описаналогові входи
Значенняanalog_input
Описцифрові входи
Значенняdigital_input
Описрегістри can шини
Значенняcan_input
Описчастотні входи
Значенняfrequency_hz
Описвходи, які рахують імпульси
Значенняpulse_counter_pcs
Описнавантаження на осі
Значенняaxle_load_kg
Описверсія can log
Значенняcan_log_version
Описрозмір в байтах пакету, що прийшов
Значенняin_chunk_size
Опискількість надходжених пакетів
Значенняin_package_count
Описрозмір в байтах відповіді сервера
Значенняout_chunk_size
Опискількість відповідей сервера
Значенняout_package_count
Описсписок всіх значень входів wire
Значенняone_wire_input
Описсписок всіх значень цифрових входів
Значенняsensor_input
Описсписок всіх значень аналогових входів
Значенняvoltage_mv
Специфікація часу

Існують часові параметри двох типів. Перший – фіксований час. Другий – інтервал часу. Якщо ні один часовий параметр не заданий, то запит повертає запитувані дані на поточний момент часу.

Щоб вказати який-небудь момент часу, на який вас цікавить запитувана інформація, додайте черговий параметр:

time=[val]

де "time" - назва часового параметру, а "[val]" - значення. У значенні повинна бути вказана дата і час відповідно до стандарту ISO 8601 (про стандарт є інформація в інтернеті - https://ru.wikipedia.org/wiki/ISO_8601). Запити чутливі до регістру букв.

Вкажіть дату і час в значенні параметра "time = [val]" в наступному форматі: "РРРР-ММ-ДДTчч: мм: сс".

Параметр в запиті буде виглядати так:

time=2015-07-12T12:00:00

вказана дата: 12 липня 2015 року, час: 12:00:00. Зверніть увагу: символ "T", що розділяє дату і час, - латинська буква.

Ви можете позначити тайм зону, додавши в кінці значення часу абревіатуру відповідної тайм зони (наприклад, "MSK" або "Asia / Novosibirsk").

time=2015-07-12T12:00:00MSK

Щоб в якості зони вказати UTC, наприкінці тимчасового значення додайте латинську букву "Z".

Тайм зона також може бути задана зміщенням часу вперед або назад щодо UTC.

time=2015-07-22T12:00:00+03:00
Специфікація тимчасового інтервалу

Щоб вказати часовий інтервал, встановіть початок і кінець інтервалу в часовому параметрі так, як показано нижче, використовуючи розділяючий символ "/".

time=[val1]/ [val2]

де "[val1]" - початок інтервалу, а "[val2]" його кінець.

Наприклад:

time=2015-07-12T12:00:00/2015-07-15T15:52:01

Параметр вище позначає часовий інтервал з початком, датується на 12 число липня 2015 в 12:00:00 і кінцем 15 липня 2015 в 15:52:01.

Також можна задати інтервал у вигляді "IsoTime / duration", де тривалість інтервалу має вигляд PxxYxxMxxDTxxHxxMxxS (за префіксом P слідує тривалість інтервалу). Якщо заданий інтервал, то для параметрів з групи A береться найбільший час з цього інтервалу.

У таблиці нижче позначені ті інформаційні параметри "what", які можуть використовуватися тільки вкупі з тимчасовими інтервалами:

Опис
Значення
Описчас руху
ЗначенняmoveTime
Описчас стоянки
ЗначенняstopTime
Описчас відсутності даних
ЗначенняlostSignalTime
Описпробіг
ЗначенняkilometresTravelled
Описспоживання палива в літрах
ЗначенняtotalFuelConsumption
Описсередня швидкість
ЗначенняavgMoveSpeed
Описмаксимальна швидкість
ЗначенняmaxSpeed
Описвихідний пункт
Значенняorigin
Описпункт призначення (місце останньої зупинки)
Значенняdestination
Опискінцевий/початковий рівень палива
ЗначенняendFuelLevel, startFuelLevel
Описвитрата палива л/100км
ЗначенняfuelPer100Km
Описчисло заправок/зливів
ЗначенняfuelingCount, fuelDrainCount
Описзаправлено/злито (л)
ЗначенняtotalFueling, totalFuelDrain
Робота з шарами
1. Отримання списку шарів у групах
{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.get", "params": [ "", ["", ""...] // список UUID'ів груп ] }

Відповідь при позитивному результаті:

{ "result": [ <список-шарів> ] }

Кожен шар описується наступною структурою:

{ "uuid": "", "external_id": "", // необов’язковий ID шару в зовнішній системі "parent_group_uuid": "", "name": "", "visibility": , "priority": }
2. Оновлення даних в шарі

Даний метод очищує шар, зазначений у параметрі "", і потім заповнює цей шар списком нових об'єктів.

Запит:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.replace", "params": [ "", "", [ <список об’єктів> ] ] }

Кожен об’єкт має наступну структуру:

{ "name": "", "geometry": "", // на даний момент підтримується тільки тип POINT "icon_url": "", "color_id": , // на даний момент специфіковані кольори від 1 до 9 "geo_object_fields": { // необов’язковий словник додаткових властивостей об’єкта "": ,... } }

Відповідь при позитивному результаті:

{ "result": [ "", ""... ] // список UUID'ів створених об’єктів. }

У відповіді порядковий номер UUID-а відповідає номеру об'єкта в запиті.
Всі запитані зміни застосовуються атомарно: або всі застосувались, або стан шарів не змінився.

3. Додавання об'єктів в шарі

Аналогічно "public-1.0-layer.objects.replace", але без попереднього видалення наявних у шарі об'єктів.

Запит:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.create", "params": [ "", "", [ <список об’єктів> ] ] }

Кожен об’єкт має наступну структуру:

{ "name": "", "geometry": "", // на даний момент підтримується тільки тип POINT "icon_url": "", "color_id": , // на даний момент специфіковані кольори від 1 до 9 "geo_object_fields": { // необов’язковий словник додаткових властивостей об’єкта "": ,... } }

Відповідь при позитивному результаті:

{ "result": [ "", ""... ] // список UUID'ів створених об’єктів. }

У відповіді порядковий номер UUID-а відповідає номеру об'єкта в запиті.
Всі запитані зміни застосовуються атомарно: або всі застосувались, або стан шарів не змінився.

4. Редагування об'єктів в шарі

Аналогічно "public-1.0-layer.objects.replace", але перелічувані об'єкти, що ідентифікуються по полю "uuid", вже повинні існувати в шарі. Зазначення властивостей об'єктів, крім "uuid", є необов'язковим. Незазначені в запиті поля об'єкта не змінюються в ДС.

Запит:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.create", "params": [ "", "", [ <список об’єктів> ] ] }

Кожен об’єкт має наступну структуру:

{ "uuid": "", // всі наступні поля необов’язкові, якщо поле не вказано воно не буде відредаговано. "name": "", "geometry": "", // на даний момент підтримується тільки тип POINT "icon_url": "", "color_id": , // на даний момент специфіковані кольори від 1 до 9 "geo_object_fields": { // необов’язковий словник додаткових властивостей об’єкта "": ,... } }