Основная цель API истории координат объекта это выдача исторических данных (координаты) об объекте клиента. API Истории координат объекта имеет две конечные точки, это означает что есть два типа запроса. Первый тип запроса это для одного конкретного объекта по определённой дате и времени. Только данные которые были записаны в указанные дату и время будут отображены.
Пример запроса по конкретной дате:
GET /objects/{object_id}/coordinates/{datetime}?version=1&api_key=<…>
HOST:api.fm-track.com
Content-Type:application/json;charset=UTF-8
Для данного типа запроса необходимы три параметра ( не считая ключа API), которые нужно указать для работы API:
| Параметр | Тип | Пояснение |
|---|---|---|
| object_id | Строка | Внешний ID объекта |
| datetime | Дата и время | Запрос записи по конкретной дате и времени. Пример формата даты и времени: “2017-04-13T06:58:48.090Z” в соответствии с ISO-8601 стандартом |
| version | Строка | Версия API, в настоящее время только версия = 1 доступна |
| api_key | Строка | Ключ идентификации пользователя |
Примечание
Рекомендуется использовать параметр даты и время с второй конечной точки API истории координат объекта, т.к. дата и время указано с точностью до секунды. Система не выполняет поиск координат по близлежащему времени, только по точно указанному моменту.
Пример ответа с сервера если все параметры были введены а также был введён действительный ключ API:
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 | { "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 } } |
Если какой либо параметр или ключ API был введён неправильно, то система ответит кодом ошибки, все возможные коды ошибок описаны в разделе API. Параметры описаны в конце данного раздела.
Вторая конечная точка данного API это массив исторических данных за указанный период времени. Каждый набор данных имеет конкретную дату и время, которые могут быть использованы для первого типа данного API который описан ранее.
Пример запроса по конкретному периоду времени:
GET /objects/{object_id}/coordinates?version=1{&from_datetime,to_datetime,continuation_token,limit}&api_key=<…>
HOST:api.fm-track.com
Content-Type:application/json;charset=UTF-8
Для данного типа запроса необходимы три параметра ( не считая ключа API), которые нужно указать для работы API:
| Параметр | Тип | Пояснение |
|---|---|---|
| objectId | Строка | Внешний ID объекта |
| fromDatetime | Дата и время | Запрос записей начиная от указанной даты и времени. Пример формата даты и времени: “2017-04-13T06:58:48.090Z” в соответствии с ISO-8601 стандартом |
| version | Строка | Версия API |
| api_key | Строка | Ключ идентификации пользователя |
Другие выборочны параметры которые не обязательны но могут быть включены в запрос:
| Параметр | Тип | Пояснение |
|---|---|---|
| toDatetime | Дата и время | Найти записи до указанной даты и времени. Если дата и время не указаны, то система будет искать записи до настоящей даты до тех пор пока небудет достигнут лимит записей. Пример формата даты и времени: “2017-04-13T06:58:48.090Z” в соответствии с ISO-8601 стандартом |
| continuationToken | Дата и время | Включая и жетон продолжения, будет отображать следующий набор записей, по истечению предыдущего лимита на записи. |
| limit | Целое число | Ограничение на число записей в одном ответе с системы (значение по умолчанию – 100 записей, максимальное число – 1000) |
| api_key | Строка | Ключ идентификации пользователя |
Пример ответа с сервера показан далее:
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 27 28 29 30 31 | { "continuation_token": "2017-04-13T06:58:48.121Z", "items": [ { "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 | Тип | Описание | Измерение |
|---|---|---|---|
| continuation_token | Жетон продолжения получается при запросе большого объёма записей, которые превышают установленный лимит записей. Жетон продолжения будет указан в конце ответа. Данный жетон может быть использован после для отображения следующего набора записей за указанный период времени. Если после жетона больше записей нет, то ответ вернётся пустой | Дата и время | |
| device_inputs | Массив | Контейнер для параметров полученных с устройств | |
| calculated_inputs | Массив | Контейнер для параметров высчитанных системой с других параметров в соответствии с конфигурацией | |
| items | Массив | Содержит все параметры в соответствии с запросом. | |
| object_id | Строка | Определитель объекта (внешний) | Текст |
| 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 (действительно /активно – недействительно / неактивно) |
| ibutton | Строка | Код iButton или RFID водителя который назначен транспортному средству. | Текст |
| first_driver_id | Строка | TCO код первого водителя | Текст |
| second_driver_id | Строка | TCO код второго водителя | Текст |
| satellites_count | Целое число | Число видимых GPS или GLONASS спутников (зависит от конфигурации устройства) во время генерации записей. | Число |
| mileage | Число с плавающей запятой | Пройденное расстояние объектом (зависит от конфигурации) | Км |
| power_supply_voltage | Целое число | Напряжение источника питания объекта | mV (милливольт) |
Конечные точки API, запрашиваемые параметры а также примеры ответов могут быть просмотрены в “Swagger” через данную ссылку: https://api.fm-track.com