Účelem historie souřadnic API je výstup historických dat objektu klienta (souřadnic). Historie souřadnic má dva koncové body, tudíž jsou dva typy požadavků. První typ požadavku je pro objekt. Tone a určitý datum a čas. Zobrazí se pouze data zaznamenána v určitém datu a čase.
Příklad požadavku pro určitý datum:
GET /objects/{object_id}/coordinates/{datetime}?version=1&api_key=<…>
HOST:api.fm-track.com
Content-Type:application/json;charset=UTF-8
Aby požadavek Api fungoval, musí se specifikovat tři parametry (kromě API_key):
| 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 |
Poznámka
Doporučuje se použít parametr času dne z druhého koncového bodu z Historie souřadnic objektu, protože parametr času dne je specifikován tím druhým a systém nehledá data kolem spespecifikovaného datumu.
Příklad odpovědi, když jsou zahrnuty všechny parametry 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 } } |
Jestliže parametr nebo API_key byl zadán nesprávně, systém odpoví chybovým kódem. Všechny chybové kódy jsou popsány v oddíle o API. Parametry jsou popsány na konci tohoto oddílu.
Druhý koncový bod Historie API zobrazuje pole historických dat pro definované období. Každá sada dat má urrčený datum a čas, jež lze použít při odeslání prvního typu požadavku Historie API.
Příklad požadavku pro určené období:
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žadavek Api fungoval, musí se specifikovat tři parametry (kromě API_key):
| 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 |
Volitelné parametry, jež nejsou povinné, ale mohou být začleněny do požadavku:
| 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 |
Příklad odpovědi:
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šechny pole odpovědi, jež mohou být přijaty s každým typem parametru jsou popsány v následující tabulce:
| 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 |
Koncové body API, parametry požadavku a odpovědi lze shlédnout v “Swagger” prostřednictvím odkazu: https://api.fm-track.com