Interfejsy API współrzędnych obiektu w czasie rzeczywistym (Object Coordinates Streaming API) w głównej mierze służą do informowania użytkownika o zmianach dotyczących obiektu. Ten interfejs API zapewnia strumieniowe przesyłanie informacji. Po wysłaniu przez użytkownika żądania API najpierw wyświetlana jest ostatnia znana współrzędna każdego z obiektów, a następnie nowe dane są wysyłane do użytkownika bezpośrednio po wystąpieniu jakiejkolwiek zmiany. Wysyłanie kolejnych żądań API nie jest konieczne, chyba że połączenie strumieniowe zostało zerwane.
Uwaga
Ponieważ API najpierw zwraca ostatnią znaną współrzędną, w przypadkach, gdy połączenie ze strumieniem API zostało zerwane i nawiązane ponownie bez nowych współrzędnych odebranych w tym czasie, użytkownik otrzyma ostatnią znaną współrzędną, która została już raz odebrana raz, a więc duplikat rekordu. Należy o tym pamiętać, ponieważ w niektórych systemach może to powodować komplikacje.
Przesyłanie strumieniowe API współrzędnych obiektu w czasie rzeczywistym może zostać zainicjowane dla określonego obiektu albo dla wszystkich obiektów dostępnych dla użytkownika.
Przykład żądania dla wskazanego obiektu:
GET /object-coordinates-stream?version=1&object_id=<…>&api_key=<…>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8
Przykład żądania API dla wszystkich obiektów klientów:
GET /object-coordinates-stream?version=1&api_key=<…>
HOST:api.fm-track.com
Content-Type:text/event-stream;charset=UTF-8
Ten interfejs API wymaga do działania jedynie dwóch parametrów obowiązkowych:
| Parameter | Type | Description |
|---|---|---|
| version | String | Version of the API, currently only version=1 is available |
| api_key | User identification key |
W żądaniu można umieścić jedynie jeden parametr opcjonalny:
| Parameter | Type | Description |
|---|---|---|
| object_id | String | External object ID |
Odpowiedź z serwera:
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 | data:{ "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 |
|---|---|---|---|
| object_id | String | Object identifier in our system | Text |
| device_inputs | Container for parameters received from hardware | ||
| calculated_inputs | Container for parameters calculated in system from other parameters according configuration | ||
| datetime | Date | Date and time point of coordinate generated in hardware Format: "yyyy-mm-ddThh:mm:ss.sssZ" | According ISO8601 |
| 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 | 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 |
| 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
Uwaga
Należy pamiętać, że odpowiedź z serwera jest strumieniem danych, tych samych, które są odbierane z urządzenia. Wszystkie otrzymane dane są dostarczane „tak jak jest”. Oznacza to, że urządzenie może czasem między rekordami pozycji aktualnej wysyłać współrzędne pozycji poprzedniej. Interfejs API nie sprawdza ani nie reguluje ciągłości odebranych danych.