História súradníc objektu API

Účelom história súradníc API je výstup historických dát objektu klienta (súradníc). História súradníc má dva koncové body, teda sú dva typy požiadaviek. Prvý typ požiadavky je pre objekt. Tone a určitý dátum a čas. Zobrazí sa iba dáta zaznamenaná v určitom dátume a čase.

Príklad požiadavke pre určitý dátum:

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

Aby požiadavka Api fungoval, musí sa špecifikovať tri parametre (okrem API_key):

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

Poznámka
Odporúča sa použiť parameter času dňa z druhého koncového bodu z História súradníc objektu, pretože parameter času dňa je špecifikovaný tým druhým a systém nehľadá dáta okolo špecifikovaného dátumu.

Príklad odpovede, keď sú zahrnuté všetky parametre a API_key je platný:

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
{
"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
},
"calculated_inputs":{
"mileage" : 0
}
}

Ak parameter alebo API_key bol zadaný nesprávne, systém odpovie kódom chyby. Všetky chybové kódy sú popísané v oddiele o API. Parametre sú popísané na konci tohto oddielu.

Druhý koncový bod História API zobrazuje pole historických dát pre definované obdobie. Každý počet dát má určený dátum a čas, ktoré je možné použiť pri odoslaní prvého typu požiadavke História API.

Príklad požiadavke pre určené obdobie:

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

Aby požiadavka Api fungoval, musí sa špecifikovať tri parametre (okrem API_key):

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

Voliteľné parametre, ktoré nie sú povinné, ale môžu byť začlenené do požiadavky:

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

Príklad odpovede:

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
32
33
34
35
36
{
"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
},
"calculated_inputs":{
"mileage" : 0
}
}
]
}

Všetky polia odpovede, ktoré môžu byť prijaté s každým typom parametra sú popísané v nasledujúcej tabuľke:

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
device_inputsArrayContainer for parameters received from hardware
calculated_inputsArrayContainer for parameters calculated in system from other parameters according to the configuration
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
longitudeFloatGPS coordinate - longitude valueDegrees
latitudeFloatGPS coordinate - latitude valueDegrees
altitudeIntegerGPS coordinate - altitude valueNumber
speedIntegerObject moving speedkm/h
directionIntegerMoving direction in degrees0 = north, increasing clock-wise
ignition_statusEnumIndicating if object has ignition on.
"ON" - Ignition on
"OFF" - Ignition off
"UNKNOWN" - No data about ignition
ON- OFF
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
ibuttonStringiButton or RFID card code of a driver assigned to a vehicleText
first_driver_idStringTCO code of the first driverText
second_driver_idStringTCO code of the second driverText
satellites_countIntegerNumber of visible GPS or GLONASS satellites(depends on device configuration) while generating record in deviceNumber
mileageFloatObject driven distance (depends on object configuration)km
power_supply_voltageIntegerObject power supply voltagemV

Koncové body API, parametre požiadavke a odpovede možno sledovať v “Swagger” prostredníctvom odkazu: https://api.fm-track.com