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):
| Parameter | Type | Description |
|---|---|---|
| object_id | String | External object ID |
| datetime | Date time | Requested 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 |
| version | String | Version of the API, currently only version=1 is available |
| api_key | String | User 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):
| Parameter | Type | Description |
|---|---|---|
| objectId | String | External object ID |
| fromDatetime | Date time | Find 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 |
| version | String | Version of API |
| api_key | String | User identification key |
Opcjonalne parametry, które nie są obowiązkowe, ale można je uwzględnić w żądaniu:
| Parameter | Type | Description |
|---|---|---|
| toDatetime | Date time | Find 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 |
| continuationToken | Date time | Including a continuation token, will display the next set of records, after the previous limit of records was reached. |
| limit | Integer | Limits records to the set count in the system response (default value – 100 records, maximum value – 1000) |
| api_key | String | User 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:
| Name | Type | Description | Units |
|---|---|---|---|
| continuation_token | Continuation 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_inputs | Array | Container for parameters received from hardware | |
| calculated_inputs | Array | Container for parameters calculated in system from other parameters according to the configuration | |
| items | Array | Contains all parameters in accordance to the request | |
| object_id | String | Object identifier (external) | Text |
| datetime | Date | Date and time point of coordinate generated in hardware Format: "yyyy-mm-ddThh:mm:ss.sssZ" | According ISO-8601 |
| longitude | Float | GPS coordinate - longitude value | Degrees |
| latitude | Float | GPS coordinate - latitude value | Degrees |
| altitude | Integer | GPS coordinate - altitude value | Number |
| speed | Integer | Object moving speed | km/h |
| direction | Integer | Moving direction in degrees | 0 = north, increasing clock-wise |
| ignition_status | Enum | Indicating if object has ignition on. "ON" - Ignition on "OFF" - Ignition off "UNKNOWN" - No data about ignition | ON- OFF |
| digital_input_1 | Boolean | Configurated 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 |
| ibutton | String | iButton or RFID card code of a driver assigned to a vehicle | Text |
| first_driver_id | String | TCO code of the first driver | Text |
| second_driver_id | String | TCO code of the second driver | Text |
| satellites_count | Integer | Number of visible GPS or GLONASS satellites(depends on device configuration) while generating record in device | Number |
| mileage | Float | Object driven distance (depends on object configuration) | km |
| power_supply_voltage | Integer | Object power supply voltage | mV |
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