Glavna svrha API-ja za strujanje koordinata objekata je informiranje korisnika o promjenama objekata. Ovaj API radi kao strujanje informacija koristeći SSE (server sent events – događaji poslani od strane poslužitelja) . Nakon što korisnik pošalje API zahtjev, prvo se prikazuje posljednja poznata koordinata za svaki objekt, a nakon toga će se korisniku poslati novi podaci čim dođe do promjene. Nema potrebe za ponovnim slanjem API zahtjeva osim ako je strujna veza prekinuta.
Bilješka
Budući da API prvo vraća posljednju poznatu koordinatu, u slučajevima kada je API stream bio u tijeku i iz nekog razloga ponovno povezan, bez primljenih novih koordinata između tog vremena, korisnik će primiti posljednju poznatu koordinatu, koja je već jednom primljena, čime se duplicira zapis koordinata. To treba imati na umu, jer može uzrokovati probleme u raznim sustavima.
Streaming API-ja za koordinate objekata može se pokrenuti za jedan određeni objekt ili za sve korisniku dostupne objekte.
Primjer zahtjeva za određeni objekt:
GET /object-coordinates-stream?version=1&object_id= <...>&api_key= <...>
DOMAĆIN: api.fm-track.com
Vrsta sadržaja: tekst/tok događaja; skup znakova=UTF-8
Primjer zahtjeva za sve klijentske objekte:
GET /object-coordinates-stream?version=1&api_key= <...>
DOMAĆIN: api.fm-track.com
Vrsta sadržaja: tekst/tok događaja; skup znakova=UTF-8
Da bi ovaj API radio, obavezna su samo dva parametra:
| Parameter | Type | Description |
|---|---|---|
| version | String | Version of the API, currently only version=1 is available |
| api_key | User identification key |
I u zahtjevu se može uključiti samo jedan opcionalni parametar:
| Parameter | Type | Description |
|---|---|---|
| object_id | String | External object ID |
Odgovor s poslužitelja:
{
"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
}
}
Sva polja odgovora koja se mogu primiti sa svakom vrstom parametra opisana su u sljedećoj tablici:
| 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 |
API krajnje točke, parametri zahtjeva i odgovori mogu se pregledati u „Swaggeru” putem ove poveznice: https://api.fm-track.com
Bilješka
Imajte na umu da je odgovor poslužitelja tok podataka, isti podaci koji su primljeni s uređaja. Svi primljeni podaci pružaju se „kakvi jesu”. To znači da uređaj može periodički slati koordinate prethodne pozicije između zapisa trenutne pozicije. API ne provjerava niti upravlja kontinuitetom primljenih podataka.