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:

ParameterTypeDescription
versionStringVersion of the API, currently only version=1 is available
api_keyUser identification key

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

ParameterTypeDescription
object_idStringExternal 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:

NameTypeDescriptionUnits
object_idStringObject identifier in our systemText
datetimeDateDate and time point of coordinate generated in hardware
Format: "yyyy-mm-ddThh:mm:ss.sssZ"
According ISO8601
ignition_statusEnumIndicating if object has ignition on.
"ON" - Ignition on
"OFF" - Ignition off
"UNKNOWN" - No data about ignition
ON - OFF
positionArrayContains all record GPS parameters
latitudeFloatGPS coordinate - latitude valueDegrees
longitudeFloatGPS coordinate - longitude valueDegrees
altitudeIntegerGPS coordinate - altitude valueNumber
directionIntegerMoving direction in degrees0 = north, increasing clock-wise
speedIntegerObject moving speedkm/h
satellites_countIntegerNumber of visible GPS or GLONASS satellites(depends on device configuration) while generating record in deviceNumber
device_inputsContainer for parameters received from hardware
power_supply_voltageIntegerObject power supply voltagemV
ibuttonStringiButton or RFID card code of a driver assigned to a vehicleText
hdopFloatGPS precisionNumber
first_driver_idStringTCO code of the first driverText
second_driver_idStringTCO code of the second driverText
digital_input_1BooleanConfigured object or its equipment status
true - status = active
false - status = inactive
True - False
digital_input_2BooleanConfigured object or its equipment status
true - status = active
false - status = inactive
True - False
digital_input_3BooleanConfigured object or its equipment status
true - status = active
false - status = inactive
True - False
digital_input_4BooleanConfigured object or its equipment status
true - status = active
false - status = inactive
True - False
temperature_sensor_0FloatTemperature sensor data°C
temperature_sensor_1FloatTemperature sensor data°C
temperature_sensor_2FloatTemperature sensor data°C
temperature_sensor_3FloatTemperature sensor data°C
temperature_sensor_0_idStringTemperature sensor IDText
calculated_inputsArray
mileagefloatObject 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.