Object Coordinates Streaming API

Object Coordinates Streaming APIs main purpose is to inform the user about objects changes. This particular API works as a stream of information, using SSE (server sent events) technology. Once the user has sent an API request, first the last known coordinate for each object is displayed, afterwards new data will be outputted to the user as soon as a change occurs. There is no need to resend the API request unless the streaming connection was broken.

This image has an empty alt attribute; its file name is Streaming-API-234x300.png

Note
Since the API first returns the last known coordinate, in cases when the API stream was ongoing and for some reason reconnected, with no new coordinates received between that time, the user will receive the last know coordinate, which has already been received once, thus duplicating the coordinate record. This should be kept in mind, since it may cause issues in various systems.

Object Coordinates Streaming API streaming can be initiated for either for one specific object or for all user available objects.

Request example for a specific object:

GET /object-coordinates-stream?version=1&object_id=<…>&api_key=<…>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8

Request example for all clients objects:

GET /object-coordinates-stream?version=1&api_key=<…>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8

For this API to work, only two parameters are mandatory:

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

And only one optional parameter can be included in the request:

Parameter	Type	Description
object_id	String	External object ID

Response from server:

{
    "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
    }
}

All response fields than can be received with every type of parameter are described in the next table:

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 endpoints, request parameters and responses can be previewed in “Swagger” through this link : https://api.fm-track.com

Note
Please note, that the response from the server is a stream of data, the same data that is received from the device. All data received is provided “As is”. This means that the device can periodically send coordinates of a previous position between records of the current position. The API does not check or manage the continuity of the received data.

‹ Object Coordinates History API v3

Object Coordinates Streaming API v2 ›