Запросы API

Навител Мониторинг – программа с открытым API интерфейсом. Получение/редактирование/удаление какой-либо информации об объектах мониторинга, равно как и администрирование пользователей, возможно с помощью API запросов. Авторизация запросов в диспетчерскую систему осуществляется при помощи API ключей, генерируемых в настройках диспетчерской системы. Чтобы получить такой ключ, в диспетчерской системе откройте меню Настройки и выберите вкладку API.

1. Общие положения

Для всех запросов публичного JSON-RPC API используется префикс «public-1.0-». В последующем описании всех методов этот префикс подразумевается. Например, метод, описанный ниже как group.get должен вызываться как public-1.0-group.get.

Закрыть

1.1. Формат запросов

Все запросы представляют собой запросы HTTP POST, в качестве тела запроса используется JSON объект следующей структуры:

{ "jsonrpc": "2.0", "id": <request-id>, # steadily increasing integer "method": <method-name>, # method name, a string "params": [ .... ] }

  • Поле id — монотонно увеличивающийся идентификатор запроса, целое число;

  • Поле method — название метода, строка;

  • Поле params — список, возможно, пустой аргументов метода.

Поскольку JSON-RPC API предназначено для роботов, то входящие запросы сейчас не будут поддерживать фильтры и пейджирование. Вся фильтрация должна осуществляться на стороне инициатора запроса.

Закрыть

1.2. Возвращение результата

Все методы возвращают код HTTP и тело ответа. В случае, если запрос является допустимым HTTP-запросом, возвращается код HTTP 200, а в качестве тела ответа — JSON объект. Если запрос завершился успешно, то возвращаемый объект содержит поле result.

{ "result": .... }

Возвращаемое в поле result значение специфично для каждого из запросов и описано ниже.

Закрыть

1.3. Сообщения об ошибках

Если запрос был отклонен по причинам, связанным с корректностью формирования HTTP-запроса, то возможны соответствующие коды ошибок HTTP (например, 400, 403, 404, 405 и т.п.).

Если запрос был синтаксически корректен, но при выполнении произошла ошибка уровня Диспетчерской Системы, то возвращается код HTTP 200, но возвращаемый JSON-объект имеет не поле result, а поле error:

{ "error": .... }

Форматы возможных ошибок при выполнении запросов описаны ниже.

Закрыть

2. Основные запросы

2.1. Получение списка машин

Перед созданием каких-либо мониторинговых запросов необходимо создать запрос на вывод списка транспортных средств и их идентификационных характеристик. Для этого нужно создать запрос в формате GET:

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

где «apikey=[val]» — параметр типа «имя/значение», в котором «apikey» является именем, а «[val]» — значением. Полученный в настройках диспетчерской системы API ключ необходимо вставить на место значения «[val]» данного параметра. Таким образом, запрос с введенным значением параметра apikey будет выглядеть следующим образом:

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

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

namefilter=[value]

где «[value]» — значение фильтра. Вы можете указать название имени объекта, информацию о котором вы хотите получить, или оставить поле пустым, чтобы получить информацию о всех объектах, как показано в примере выше.

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

<reply> <resulttype="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 кода

https://www.dispatch.navitel.ru/api/1.0/vehicles.xml

в этом примере результатом запроса будет код json

https://www.dispatch.navitel.ru/api/1.0/vehicles.json

Закрыть

2.2. Аутентификация запросов

JSON-RPC API использует для идентификации API ключ, который является первым обязательным параметром всех методов, кроме apikey.get. Для получения API ключа в строке меню нажмите Настройки (). В открывшемся диалоговом окне выберите вкладку API, нажмите кнопку Создать.

Закрыть

2.2. Схема создания запросов

  • apikey.get - получение API ключа по имени пользователя и паролю

    • Параметры:

      • login - имя пользователя (логин)

      • password - пароль

    • Результат:

      • строка API ключа

Закрыть

2.4. Запросы групп

  • group.get — получение списка групп.

    • Параметры:

      • Объект, содержащий следующие поля:

        • (опциональный) parent_group_uuid_list – необязательный список родительских групп. Родительские группы должны быть доступны пользователю, выполняющему запрос. В случае отсутствия или пустого списка в запросе результат содержит все группы верхнего уровня, доступные пользователю, или все группы, если параметр recursive равен True.

        • recursive — boolean перечислять ли группы рекурсивно.

    • Результат:

      • список структур, описывающих группы. Документированы следующие поля в структурах:

        • обязательные:

          • uuid — UUID группы

          • name — название группы

        • необязательные:

          • parent_group_uuid — UUID родительской группы, если родительская группа существует и пользователю доступен API ключ

          • limits — объект, содержащий список ограничений, если ограничения заданы для группы (группа является компанией):

            • max_users — максимальное количество пользователей, целое число или null, если ограничение не задано

            • max_vehicles — максимальное количество машин, целое числи или null, если ограничение не задано

            • valid_until — срок действия лицензии, строка в формате ISO-8601 или null, если ограничение не задано

  • group.create — создание групп.

    • Параметры:

      • groups — список объектов, описывающих создаваемые группы. В каждом объекте документированы те же поля, что и поля group.get. Не следует указывать UUID группы, поле будет проигнорировано.

    • Результат

      • список UUID созданных групп.

  • group.edit — изменение выбранных полей в существующих группах.

    • Параметры:

      • group_fields — словарь объектов, описывающих изменяемые поля групп. Ключами в словаре являются UUID групп. Поля в объектах соответствуют полям в group.get. Неуказанные в объекте поля не изменяются. Отсутствие на момент выполнения запроса группы с указанным UUID является ошибкой.

    • Результат отсутствует

  • group.delete — удаление групп.

    • Параметры:

      • uuid_list — список UUID удаляемых групп. Отсутствие на момент выполнения запроса группы с указанным UUID ошибкой не считается.

    • Результат отсутствует

Закрыть

2.5. Запросы объектов мониторинга

  • vehicle.get — получение списка устройств слежения для указанной группы.

    • Параметры:

      • parent_group_uuid — UUID группы.

    • Результат:

      • список структур, описывающих объекты мониторинга в данной группе. В каждой структуре документированы следующие поля:

        • обязательные:

          • uuid — UUID объекта мониторинга

          • name — название объекта мониторинга

          • parent_group_uuid — UUID родительской группы

          • tracker_type — строка идентифицирующая тип трекера, из фиксированного списка строк (enum), В настоящее время в списке ровно один элемент - OLYMPSTROY. В дальнейшем список трекеров, поддерживаемых данным API, будет расширен

          • tracker_identifier — строка или набор строк, идентифицирующие экземпляр трекера данного типа.
            Примечание: в настоящее время трекеров, требующих массив строк, нет, позднее они будут явно перечислены

        • необязательные:

          • display_icon — номер иконки. В настоящее время стандартизованы номера от 0 до 14 включительно.

          • display_color — цвет иконки, строка в формате CSS hexadecimalcolors (#RRGGBB).

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

  • vehicle.create — создание новых объектов мониторинга.

    • Параметры:

      • vehicles — список структур, описывающих создаваемые объекты мониторинга. UUID не указывается (задается сервером). Допустимые поля соответствуют полям в vehicle.get. Обязательными для указания являются поля:

        • name

        • parent_group_uuid

        • tracker_type

        • tracker_identifier

    • Результат:

      • список UUID'ов созданных объектов мониторинга или ошибка, если хотя бы один из запрошенных объектов не может быть создан.

  • vehicle.edit — редактирование свойств объектов мониторинга.

    • Параметры:

      • vehicle_fields — словарь, ключами которого являются UUID объектов мониторинга, а значениями — структуры, описывающие изменения в объектах. Допустимые поля соответствует полям в vehicle.get. Неуказанные в запросе поля не изменяются. Невозможность по тем или иным причинам отредактировать хотя бы один из объектов из перечисленных приводит к ошибке всего запроса, никакие изменения не применяются.

    • Результат:

      • отсутствует, если операция завершена успешно, либо отображается сообщение об ошибке в установленном формате.

  • vehicle.delete — удаление объектов мониторинга.

    • Параметры:

      • uuid_list — список UUID удаляемых объектов мониторинга. Отсутствие на момент выполнения запроса объекта с указанным UUID ошибкой не считается.

    • Результат: отсутствует, если операция завершена успешно, или сообщение об ошибке в установленном формате.

Закрыть

2.6. Запросы ролей

  • role.get — получение списка ролей для указанной группы.

    • Параметры:

      • parent_group_uuid — UUID группы.

    • Результат:

      • список структур, описывающих роли в данной группе. В каждой структуре документированы поля:

        • uuid — UUID роли

        • name — название роли

Закрыть

2.7. Запросы пользователей

  • user.get — получение списка пользователей для указанной группы.

    • Параметры:

      • parent_group_uuid — UUID группы.

    • Результат:

      • список структур, описывающих пользователей в данной группе. Поля описаны выше.

  • user.create — создание пользователей.

    • Параметры:

      • Users — список структур, описывающих создаваемых пользователей. UUID не указывается (задается сервером).

    • Результат:

      • список UUID созданных пользователей.

  • user.edit — изменение выбранных полей у существующих пользователей.

    • Параметры:

      • user_fields — словарь структур, описывающих изменяемые поля пользователей. Ключами в словаре являются UUID пользователей. Неуказанные в структуре поля не изменяются. Отсутствие на момент выполнения запроса пользователя с указанным UUID является ошибкой.

    • Результат отсутствует

  • user.setPassword – установка пароля пользователю.

    • Параметры:

      • uuid – UUID пользователя

      • password – новый пароль

  • user.delete — удаление существующих пользователей.

    • Параметры:

      • uuid_list — список UUID удаляемых пользователей. Отсутствие на момент выполнения запроса пользователя с указанным UUID ошибкой не считается.

    • Результат отсутствует

Закрыть

3. Запросы для создания путевых листов

3.1. Получение данных из отчета по поездкам

JSON-RPC запрос выглядит так:

{ "jsonrpc": "2.0", "id": <requestId>, "method": "public-1.0-report.trip.get", "params": [ apiKey, { "startTime": <timestamp>, "endTime": <timestamp>, "lang": <langId>, "vehicles": [ "<uuid1>", "<uuid2>",... ] } ] }

Формат ответа:

{ "id": <requestId>, // request ID "result": { "startTime": <timestamp>, "endTime": <timestamp>, "address_fields": [ "country", "region", "parish", "city", "district", "street", "building" ], "headers": [ "moveTime", "startTime", "origin", "endTime", "destination", "maxSpeed", "kilometresTravelled", "totalFuelConsumption" ], "vehicles": [ { "uuid": "<uuid>", // vehicle UUID "name": "<name>", "rows": [ [ <interval>, <timestamp>, <address>, <timestamp>, <address>, <kmh>, <km>, <litres> ], ... ] }, { "uuid": "<uuid>", // vehicle UUID "name": "<name>", "rows": [ ... ], }... ] } }

Закрыть

3.2. Запрос на получение мониторинговой информации

Запрос к диспетчерской системе можно представить как совокупность элементов: основной URL и параметры запроса. К базовому (основному) URL относится вся та часть запроса, которая находится до окончания указания расширения xml или json.
Пример основного URL, используемого при создании любых запросов к диспетчерской системе:

https://www.dispatch.navitel.ru/api/1.0/vehicleinfo.xml?

(исключением является запрос на получение списка машин, обращающийся к другому URL)
Параметры запроса представляют собой ряд пар типа «имя/значение», где каждая пара отделяется амперсандом («&»). Список параметров начинается сразу после вопросительного знака, следующего за указанием расширения. Всякий параметр имеет следующую форму:

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. Набор запрашиваемых параметров, each parameter separated by an ampersand ("&"):

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

где «[field]» — имя параметра, «[value]» — значение параметра. Используйте таблицы ниже в качестве руководства по написанию мониторинговых запросов.

Закрыть

3.3. Параметры для фиксированного момента времени

К этому моменту вы должны уметь включать в запрос идентификаторы автомобилей и API ключ. Однако неисследованными остались мониторинговые параметры. Их можно условно разделить на две группы: временные и информационные. В этой главе будут рассмотрены информационные параметры. Обращение к таким параметрам осуществляется через запросы с помощью использования имени «what» и выбора подходящего значения. Значения разных запросов указаны в таблице ниже.

Например, если бы было необходимо получить информацию о скорости какого-либо объекта на текущий момент времени, потребовалось бы в поле имени параметра указать «what», а в поле значения, согласно таблице, приведенной ниже, указать значение «speed_kmh»:

what=speed_kmh

полный запрос выглядел бы следующим образом:

https://www.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

Закрыть

3.4. Установка времени

Существуют временные параметры двух типов. Первый — фиксированное время. Второй — интервал времени. Если ни один из временных параметров не задан, то запрос возвращает запрашиваемые данные на текущий момент времени.
Чтобы самостоятельно указать какой-либо момент времени, на который вас интересует запрашиваемая информация, добавьте очередной параметр:

time=[val]

где «time» — название временного параметра, а «[val]» — значение. В значении должна быть указана дата и время в соответствии со стандартом ISO 8601. Примечание: Запросы чувствительны к регистру букв.

Укажите дату и время в значении параметра «time=[val]» в следующем формате: «ГГГГ-ММ-ДДTчч:мм:сс».
Параметр в запросе будет выглядеть так:

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

указана дата: 12 июля 2015 года, время: 12:00:00. Обратите внимание: символ «T», разделяющий дату и время, — латинская буква.

Вы можете обозначить тайм зону, добавив в конце значения времени аббревиатуру соответствующей тайм зоны (например, «MSK» или «Asia/Novosibirsk»).

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

Чтобы в качестве зоны указать UTC, в конце временного значения добавьте латинскую букву «Z».

Тайм зона также может быть задана смещением времени вперед или назад относительно UTC.

time=2016-07-22T12:00:00+03:00

Закрыть

3.5. Спецификация временного интервала

Чтобы указать временной интервал, установите начало и конец интервала во временном параметре так, как показано ниже, используя разделяющий символ «/».

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

Закрыть

4. Работа со слоями

4.1. Получение списка слоев в группах

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.get", "params": [ "", ["", ""...] // list of group's UUID ] }

Ответ при положительном исходе:

{ "result": [ <object list> ] }

Каждый слой описывается следующей структурой:

{ "uuid": "", "external_id": ", // non-obligatory ID of layer in external system "parent_group_uuid": "", "name": ", "visibility": , "priority": }

Закрыть

4.2. Обновление данных в слое

Данный метод очищает слой, указанный в параметре "", и затем заполняет этот слой списком новых объектов.

Запрос:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.replace", "params": [ "", "", [ <object list> ] ] }

Каждый объект имеет следующую структуру:

{ "name": "", "geometry": "", // currently supported only one type POINT "icon_url": "", "color_id": , // currently only colors from 1 to 9 are standardized "geo_object_fields": { // non-obligatory dictionary of additional object features "": ,... } }

Ответ при положительном исходе:

{ "result": [ "", ""... ] // list of created object's UUIDs. }

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

Закрыть

4.3. Добавление объектов в слое

Аналогично "public-1.0-layer.objects.replace", но без предварительного удаления имеющихся в слое объектов.

Запрос:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.create", "params": [ "", "", [ <object list> ] ] }

Каждый объект имеет следующую структуру:

{ "name": "", "geometry": "", // currently supported only one type POINT "icon_url": "", "color_id": , // currently only colors from 1 to 9 are standardized "geo_object_fields": { // non-obligatory dictionary of additional object features "": ,... } }

Ответ при положительном исходе:

{ "result": [ "", ""... ] // list of created object's UUIDs. }

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

Закрыть

4.4. Редактирование объектов в слое

Аналогично "public-1.0-layer.objects.replace", но перечисляемые объекты, идентифицируемые по полю "uuid", уже должны существовать в слое. Указание свойств объектов, кроме "uuid", является необязательным. Неуказанные в запросе поля объекта не изменяются в диспетчерской системе.

Запрос:

{ "jsonrpc": "2.0", "id": , "method": "public-1.0-layer.objects.create", "params": [ "", "", [ <object list> ] ] }

Каждый объект имеет следующую структуру:

{ "uuid": "", // All the following fields are optional, if the field is not specified it will not be edited. "name": "", "geometry": "", // currently supported only one type POINT "icon_url": "", "color_id": , // currently only colors from 1 to 9 are standardized "geo_object_fields": { // non-obligatory dictionary of additional object features "": ,... } }

Закрыть

5. Описание типов данных

<RequestId> - уникальный ID запроса-ответа, integer.

<LangId> - код предпочтительного языка ответа, language is a lowercase, two-letter, ISO 639 language code.

<Interval> - интервал времени в секундах, integer.

<Timestamp> - количество секунд с 01.01.1970 00:00 UTC.

<Address> - массив, элементами которого являются строки, соответствующие компонентам адреса, перечисленным в поле address_fields.

<Kmh> - скорость, км/ч, float.

<Km> - расстояние, км, float.

<Litres> - объем, л, float.

Закрыть