Object Coordinates History API

Object Coordinates History API main purpose is to output clients’ object historical data (coordinates). Object Coordinates History API has two endpoints, thus there are two types of requests. The first type of request is for one object and a specific date and time. Only data recorded at the specified date and time is shown.

Request example for a specific date:

GET /objects/{object_id}/coordinates/{datetime}/?version=1&api_key=<..> HTTP/1.1
HOST:api.fm-track.com
Content-Type:application/json;charset=UTF-8

The request type requires three parameters (not counting the API_key) to be specified in order for the API request to work:

ParameterTypeDescription
object_idStringExternal object ID
datetimeDate timeRequested record for the specified date and time. Date and time format example: “2017-04-13T06:58:48.090Z” in accordance to the ISO-8601 standard
versionStringVersion of the API, currently only version=1 is available
api_keyStringUser identification key

Note
It is recommended to use datetime parameter from the second endpoint of the Object Coordinates History API because the date time parameter is specified by the second, and the system does not search for data around the specified date.

A response example is shown if all the parameters were included and the API_key is valid:

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

If a parameter or the API_key was inputted incorrectly, the system will respond with an error code, all possible error codes are described in the APIs section. Parameters are described at the end of this section.

The second endpoint of the History API displays an array of  history data for a defined period of time. Each set of data has a specified date and time, which can be used when sending the first type of History API request.

Request example for a specific date period:

GET /objects/{object_id}//coordinates?version=1{&fromDatetime,toDatetime,continuationToken,limit}&api_key=<..> HTTP/1.1
HOST:api.fm-track.com
Content-Type:application/json;charset=UTF-8

The request type requires three parameters (not counting the API_key) to be specified in order for the API request to work:

ParameterTypeDescription
objectIdStringExternal object ID
fromDatetimeDate timeFind records starting from the specified date and time. Date and time format example: “2017-04-13T06:58:48.090Z” in accordance to the ISO-8601 standard
versionStringVersion of API
api_keyStringUser identification key

Optional parameters that are not mandatory, but can be included in the request:

ParameterTypeDescription
toDatetimeDate timeFind records up until the specified date and time. If it is not specified, the system will search for records up until the current date until the limit of records is reached. Date and time format example: “2017-04-13T06:58:48.090Z” in accordance to the ISO-8601 standard
continuationTokenDate timeIncluding a continuation token, will display the next set of records, after the previous limit of records was reached.
limitIntegerLimits records to the set count in the system response (default value – 100 records, maximum value – 1000)
api_keyStringUser identification code

A response example is shown below:

{
  "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,
         "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
continuation_tokenContinuation token is received when requesting large amounts of records, for long periods, which exceeds the set records limit, the continuation token will be displayed at the end of the response. It can be used afterwards to display the next set of records for the selected period. If no more records are available after the token, the response will return empty.Datetime
itemsArrayContains all parameters in accordance to the request
object_idStringObject identifier (external)Text
datetimeDateDate and time point of coordinate generated in hardware
Format: "yyyy-mm-ddThh:mm:ss.sssZ"
According ISO-8601
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_inputsArrayContainer for parameters received from hardware
power_supply_voltageIntegerObject power supply voltagemV
ibuttonStringiButton or RFID card code of a driver assigned to a vehicleText
hdopFloatGPS coordinate precisionNumber
first_driver_idStringTCO code of the first driverText
second_driver_idStringTCO code of the second driverText
digital_input_1BooleanConfigurated 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_inputsArrayContainer for parameters calculated in system from other parameters according to the configuration
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