API historycznych współpółrzęzęddnych obiektu

Głównym celem interfejsu API historycznych współrzędnych obiektu (Object Coordinates History API) jest wyprowadzanie danych (współrzędnych) historycznych dla obiektów klientów. API historycznych współrzędnych obiektu posiada dwa punkty końcowe, dlatego obsługuje dwa typy żądań. Pierwszy typ żądania dotyczy jednego obiektu oraz określonej daty i godziny. Wyświetlane są tutaj tylko dane zarejestrowane w określonym dniu i czasie.

Przykład żądania dotyczącego określonej daty:

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

W przypadku tego typu żądania API, aby zapytanie było efektywne, wymaga podania trzech parametrów (nie licząc klucza API):

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

Uwaga
Zaleca się używanie parametru „datetime” z drugiego punktu końcowego interfejsu API historycznych współrzędnych obiektu, ponieważ parametr „datetime” jest określony przez drugi, i system nie wyszukuje danych w okolicach określonej daty.

Jeśli wszystkie parametry zostały uwzględnione, a klucz API_ jest poprawny, wyświetlany jest poniższy przykład odpowiedzi:

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

Jeśli parametr lub klucz API został wprowadzony niepoprawnie, system wyśle odpowiedź w postaci kodu błędu – wszystkie możliwe kody błędów są opisane w sekcji dotyczącej API. Parametry są opisane na końcu niniejszej sekcji.

Drugi punkt końcowy interfejsu „History API” wyświetla tablicę danych historycznych dla określonego przedziału czasowego. Każdy zestaw danych ma określoną datę i godzinę, które można wykorzystać podczas wysyłania żądania interfejsu „History API” pierwszego typu .

Przykład zapytania dotyczącego określonego przedziału dat:

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

W przypadku tego typu żądania API, aby zapytanie było efektywne, należy podać trzy parametry (nie licząc klucza API):

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

Opcjonalne parametry, które nie są obowiązkowe, ale można je uwzględnić w żądaniu:

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

Poniżej przedstawiono przykład odpowiedzi:

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

Poniższa tabela przedstawia wszystkie pola odpowiedzi, które mogę być otrzymane dla każdego rodzaju parametru:

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

Punkty końcowe interfejsu API, parametry żądania i komunikaty zwrotne można przeglądać przy pomocy edytora „Swagger” za pośrednictwem: https://api.fm-track.com