API потокового передавання координат об’єктів

Основна мета API потокового передавання координат об’єктів – інформувати користувача про зміни об’єктів. Цей API працює як потік інформації, використовуючи технологію SSE (server sent events). Після того, як користувач надіслав запит до API, спочатку відображаються останні відомі координати для кожного об’єкта, а потім нові дані будуть виводитися користувачеві, як тільки відбудуться зміни. Немає необхідності повторно надсилати API-запит, якщо тільки потокове з’єднання не було розірвано.

Це зображення має порожній атрибут alt; ім'я файлу Streaming-API-234x300.png

Примітка
Оскільки 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 обов’язковими є лише два параметри:

Parameter	Type	Description
version	String	Version of the API, currently only version=1 is available
api_key	User identification key

До запиту можна включити лише один необов’язковий параметр:

Parameter	Type	Description
object_id	String	External object ID

Відповідь від сервера:

{
    "object_id" : "abc123",
    "datetime" : "2017-04-13T06:58:48.090Z",
    "ignition_status" : "UNKNOWN",
    "position" : {
        "altitude" : 0,
        "direction" : 0,
        "latitude" : 0,
        "longitude" : 0,
        "hdop": 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",
         "temperature_sensor_0": 0,
         "temperature_sensor_1": 0,
         "temperature_sensor_2": 0,
         "temperature_sensor_3": 0,
         "temperature_sensor_0_id": "xxxxxxxxxx"
    },
    "calculated_inputs":{
        "mileage" : 0
    }
}

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

Name	Type	Description	Units
object_id	String	Object identifier in our system	Text
datetime	Date	Date and time point of coordinate generated in hardware Format: "yyyy-mm-ddThh:mm:ss.sssZ"	According ISO8601
ignition_status	Enum	Indicating if object has ignition on. "ON" - Ignition on "OFF" - Ignition off "UNKNOWN" - No data about ignition	ON - OFF
position	Array	Contains all record GPS parameters
latitude	Float	GPS coordinate - latitude value	Degrees
longitude	Float	GPS coordinate - longitude value	Degrees
altitude	Integer	GPS coordinate - altitude value	Number
direction	Integer	Moving direction in degrees	0 = north, increasing clock-wise
speed	Integer	Object moving speed	km/h
satellites_count	Integer	Number of visible GPS or GLONASS satellites(depends on device configuration) while generating record in device	Number
device_inputs	Container for parameters received from hardware
power_supply_voltage	Integer	Object power supply voltage	mV
ibutton	String	iButton or RFID card code of a driver assigned to a vehicle	Text
hdop	Float	GPS precision	Number
first_driver_id	String	TCO code of the first driver	Text
second_driver_id	String	TCO code of the second driver	Text
digital_input_1	Boolean	Configured object or its equipment status true - status = active false - status = inactive	True - False
digital_input_2	Boolean	Configured object or its equipment status true - status = active false - status = inactive	True - False
digital_input_3	Boolean	Configured object or its equipment status true - status = active false - status = inactive	True - False
digital_input_4	Boolean	Configured object or its equipment status true - status = active false - status = inactive	True - False
temperature_sensor_0	Float	Temperature sensor data	°C
temperature_sensor_1	Float	Temperature sensor data	°C
temperature_sensor_2	Float	Temperature sensor data	°C
temperature_sensor_3	Float	Temperature sensor data	°C
temperature_sensor_0_id	String	Temperature sensor ID	Text
calculated_inputs	Array
mileage	float	Object driven distance (depends on object configuration)	km

Кінцеві точки API, параметри запитів та відповіді можна переглянути в “Swagger” за цим посиланням: https: //api.fm-track.com.

Примітка
Зверніть увагу, що відповідь від сервера – це потік даних, тих самих даних, які отримуються від пристрою. Всі отримані дані надаються “як є”. Це означає, що пристрій може періодично надсилати координати попередньої позиції між записами поточної позиції. API не перевіряє і не керує безперервністю отриманих даних.

‹ API історії координат об’єктів v2

API потокового передавання координат об’єктів v2 ›