Úč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):
| 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
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):
| 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 |
Voliteľné parametre, ktoré nie sú povinné, ale môžu byť začlenené do požiadavky:
| 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 |
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:
| 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, parametre požiadavke a odpovede možno sledovať v “Swagger” prostredníctvom odkazu: https://api.fm-track.com