Основная цель API потока координат объекта это информировать пользователя о изменениях в объекте. Данное API работает как поток информации. После того как пользователь выслал запрос API, с начала будут получены последние известные координаты всех объектов, далее новая информация будет отображаться пользователю как только будет зарегистрировано изменение. Нет необходимости повторно отправлять запрос API, только если не было прервано подключение.
Примечание
Т.к. данное API с начало выдает последние известные координаты, в случаях если был установлен поток данных и по какой либо причине произошло пере подключение потока, если новые координаты небыли получены в это время, то система выдаст повторно последнюю известную координату, которая уже ранее поступала. Таким образом запись будет дублирована. Это необходимо иметь ввиду, т.к. это может вызвать определённые неполадки в различных системах.
API Потока координат объекта может быть инициирована для одного конкретного объекта, либо для всех объектов пользователя.
Пример запроса для одного конкретного объекта:
GET /object-coordinates-stream?version=1&object_id=<…>&api_key=<…>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8
Пример запроса для всех объектов клиента:
GET /object-coordinates-stream?version=1&api_key=<…>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8
Для работы данного API, необходимы только два параметра:
| Параметр | Тип | Пояснение |
|---|---|---|
| version | Строка | Версия API, в настоящее время только версия = 1 доступна |
| api_key | Ключ идентификации пользователя |
И дополнительно доступен только один выборочны параметр:
| Параметр | Тип | Пояснение |
|---|---|---|
| object_id | Строка | Внешний ID объекта |
Пример ответа с сервера показан далее:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | data:{ "object_id" : "abc123", "datetime" : "2017-04-13T06:58:48.090Z", "ignition_status" : "UNKNOWN", "position" : { "altitude" : 0, "direction" : 0, "latitude" : 0, "longitude" : 0, "satellites_count" : 0, "speed" : 0 }, "device_inputs" : { "digital_input_1" : true, "digital_input_2" : true, "digital_input_3" : true, "digital_input_4" : true, "power_supply_voltage" : 0, "ibutton" : "xxxxxxxxxx", "first_driver_id" : "xxxxxxxxxx", "second_driver_id" : "xxxxxxxxxx" }, "calculated_inputs":{ "mileage" : 0 } } |
Все поля ответа которые могут быть получены с каждым типом параметров описаны далее в таблице:
| Name | Type | Description | Units |
|---|---|---|---|
| object_id | Строка | Определитель объекта в системе | Текст |
| device_inputs | Контейнер для параметров полученных с устройств | ||
| calculated_inputs | Контейнер для параметров высчитанных системой с других параметров в соответствии с конфигурацией | ||
| datetime | Дата | Дата и момент во времени когда координата была зарегистрирована оборудованием. Формат : "yyyy-mm-ddThh:mm:ss.sssZ" | в соответствии с ISO-8601 |
| longitude | Число с плавающей запятой | GPS координата – значение долготы | Градусы |
| latitude | Число с плавающей запятой | GPS координата – значение широты | Градусы |
| altitude | Целое число | GPS координата – значение высоты | Число |
| speed | Целое число | Скорость движения объекта | Км/ч |
| direction | Целое число | Направление движения в градусах | 0 = Север, увеличивается по часовой стрелке |
| ignition_status | Enum | Индикацию включенного зажигания объекта. "ON" – Зажигание включено "OFF" – Зажигание выключено "UNKNOWN" – Дата о зажигании не поступает | ON – OFF (Вкл – Выкл) |
| digital_input_1 | Логическое значение | Состояние сконфигурированного оборудования или его состояние True – состояние = активное False – состояние = неактивное | True – False (действительно /активно – недействительно / неактивно) |
| digital_input_2 | Логическое значение | Состояние сконфигурированного оборудования или его состояние True – состояние = активное False – состояние = неактивное | True – False (действительно /активно – недействительно / неактивно) |
| digital_input_3 | Логическое значение | Состояние сконфигурированного оборудования или его состояние True – состояние = активное False – состояние = неактивное | True – False (действительно /активно – недействительно / неактивно) |
| digital_input_4 | Логическое значение | Состояние сконфигурированного оборудования или его состояние True – состояние = активное False – состояние = неактивное | True – False (действительно /активно – недействительно / неактивно) |
| power_supply_voltage | Целое число | Напряжение источника питания объекта | mV (милливольт) |
| ibutton | Строка | Код iButton или RFID водителя который назначен транспортному средству. | Текст |
| first_driver_id | Строка | TCO код первого водителя | Текст |
| second_driver_id | Строка | TCO код второго водителя | Текст |
| satellites_count | Целое число | Число видимых GPS или GLONASS спутников (зависит от конфигурации устройства) во время генерации записей. | Число |
| mileage | Число с плавающей запятой | Пройденное расстояние объектом (зависит от конфигурации) | Км |
Конечные точки API, запрашиваемые параметры а также примеры ответов могут быть просмотрены в “Swagger” через данную ссылку: https://api.fm-track.com
Примечание:
Необходимо учесть что все ответы с сервера это поток данных, те же самые данные которая поступают с устройства. Все данные предоставлены “Как есть”. Это означает что устройство может периодически отправить координаты предыдущей позиции между записями настоящей позиции. API не проверяет и не управляет последовательностью поступающих данных.