Lo scopo principale delle API Object Coordinates Streaming è quello di informare l’utente sui cambiamenti degli oggetti. Questa particolare API funziona come un flusso di informazioni, utilizzando la tecnologia SSE (server sent events). Una volta che l’utente ha inviato una richiesta API, per prima cosa viene visualizzata l’ultima coordinata nota per ogni oggetto, dopodiché i nuovi dati verranno inviati all’utente non appena si verifica un cambiamento. Non è necessario inviare nuovamente la richiesta API, a meno che la connessione allo streaming non sia stata interrotta.
Note
Since the API first returns the last known coordinate, in cases when the API stream was ongoing and for some reason reconnected, with no new coordinates received between that time, the user will receive the last know coordinate, which has already been received once, thus duplicating the coordinate record. This should be kept in mind, since it may cause issues in various systems.
Coordinate dell’oggetto Lo streaming API può essere avviato sia per un oggetto specifico che per tutti gli oggetti disponibili all’utente.
Esempio di richiesta per un oggetto specifico:
GET /object-coordinates-stream?version=1&object_id=<...>&api_key=<...>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8
Esempio di richiesta per tutti gli oggetti dei clienti:
GET /object-coordinates-stream?version=1&api_key=<...>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8
Affinché questa API funzioni, sono obbligatori solo due parametri:
| Parameter | Type | Description |
|---|---|---|
| version | String | Version of the API, currently only version=1 is available |
| api_key | User identification key |
E solo un parametro opzionale può essere incluso nella richiesta:
| Parameter | Type | Description |
|---|---|---|
| object_id | String | External object ID |
Risposta dal server:
{
"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,
"temperature_sensor_0_id": "xxxxxxxxxx"
},
"calculated_inputs":{
"mileage" : 0
}
}
Tutti i campi di risposta che possono essere ricevuti con ogni tipo di parametro sono descritti nella tabella successiva:
| Name | Type | Description | Units |
|---|---|---|---|
| object_id | String | Object identifier in our system | Text |
| datetime | Date | Date and time point of coordinate generated in hardware Format: "yyyy-mm-ddThh:mm:ss.sssZ" | According ISO8601 |
| ignition_status | Enum | Indicating if object has ignition on. "ON" - Ignition on "OFF" - Ignition off "UNKNOWN" - No data about ignition | ON - OFF |
| position | Array | Contains all record GPS parameters | |
| latitude | Float | GPS coordinate - latitude value | Degrees |
| longitude | Float | GPS coordinate - longitude value | Degrees |
| altitude | Integer | GPS coordinate - altitude value | Number |
| direction | Integer | Moving direction in degrees | 0 = north, increasing clock-wise |
| speed | Integer | Object moving speed | km/h |
| satellites_count | Integer | Number of visible GPS or GLONASS satellites(depends on device configuration) while generating record in device | Number |
| device_inputs | Container for parameters received from hardware | ||
| power_supply_voltage | Integer | Object power supply voltage | mV |
| ibutton | String | iButton or RFID card code of a driver assigned to a vehicle | Text |
| hdop | Float | GPS precision | Number |
| first_driver_id | String | TCO code of the first driver | Text |
| second_driver_id | String | TCO code of the second driver | Text |
| digital_input_1 | Boolean | Configured 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 |
| temperature_sensor_0 | Float | Temperature sensor data | °C |
| temperature_sensor_1 | Float | Temperature sensor data | °C |
| temperature_sensor_2 | Float | Temperature sensor data | °C |
| temperature_sensor_3 | Float | Temperature sensor data | °C |
| temperature_sensor_0_id | String | Temperature sensor ID | Text |
| calculated_inputs | Array | ||
| mileage | float | Object driven distance (depends on object configuration) | km |
Gli endpoint API, i parametri di richiesta e le risposte possono essere visualizzati in anteprima in “Swagger” attraverso questo link: https: //api.fm-track.com
Nota
Tieni presente che la risposta del server è un flusso di dati, gli stessi che vengono ricevuti dal dispositivo. Tutti i dati ricevuti sono forniti “così come sono”. Ciò significa che il dispositivo può inviare periodicamente le coordinate di una posizione precedente tra le registrazioni della posizione attuale. L’API non controlla né gestisce la continuità dei dati ricevuti.