API funkcije – integracija informacijskih sistemov
(Dopolnitev September 2024 - funkcija getState)
Sistem TRACK.SI ima na voljo nabor API funkcij, ki omogočajo ON-LINE povezovanje sistema TRACK.SI in drugi informacijskih sistemov. Funkcija ima ime in parametre. Vsako funkcija ima prvi vstopni parameter API key. Na podlagi API ključa se določa seznam naprav do katerih lahko sistem partner dostopa. API ključ dodeli administrator sistema TRACK.SI. Funkcije so realizirane preko namenske HTTP strežniške aplikacije. Podatki se vračajo v tekstovni obliki - CSV obliki, z namenom čim manjše prenesene količine podatkov. Polja so ločena s tabulatorjem (#9), vrstica se pa konča s zaključkom (LF oziroma #13#10). Prva vrstica seznam imen podatkov/stolpcev iz baze, naslednje vrstice so podatki.
za testni dostop se obrnite na info@track.si
Funkcija: ECHO
opis: Funkcija je namenjena testiranju delovanja sistema.
parametri: ni parametrov
primer klica funkcije: http://track.si:8080/echo
odgovor: OK
Funkcija:GETSTATE
opis: Funkcija vrne trenutno stanje sledilnih naprav
parametri:
apikey - api ključ - obvezen,
IDNaprava - ID naprave (če ga ni, sistem vrnem seznam vseh naprav, ki pripadajo API ključu)
primer klica funkcije: http://track.si:8887/getstate?apikey=test&IDnaprava=1040
odgovor:
| ime polja | primer podatka | opis |
| idnaprava | 1040 | unikatna oznaka naprave |
| datvpisa | 2016-4-21 9:56 | datum vpisa v register |
| opis | Avto šola Volan | poimenovanje naprave |
| cas | 2016-05-16 10:36 | aktualni čas GPS pozicije |
| dv | 3.7 | aktualna hitrost (km/h) |
| krajds | 33 | zračna oddaljenost od naslova |
| kraj1 | LJUBLJANA | lokacija 1 |
| kraj2 | ZEMLJEMERSKA ULICA 7 | lokacija 2 |
| wx | 14.5173 | WGS 84 koordinata |
| wy | 46.0469 | WGS 84 koordinata |
| z | 100 | nadmorska višina |
| gkx | 5463012 | Gauss krueger koordinata |
| gky | 5100412 | Gauss krueger koordinata |
| tipnaprave | FOXLITE | tip naprave, proizvajalec |
| ulcount | 1456 | število ulic v kraju |
| krhscount | 34551 | število naslovov v kraju |
| izhod1 | 0 | digit.vhod 1 (kontakt ključa: 0-ni, 1-da) |
| izhod2 | 0 | digit.vhod 2 (0-ni, 1-da) |
| prtID | 0 | ID oznaka partnerja |
| reportTime | 2016-05-16 10:30 | čas izračuna poročil |
| currentDS | 36522 | danšanja prevožena pot (m) |
| currentDriveDT | 2:05:11 | današnji čas vožnje |
| currentStopDT | 0:30:04 | današnji postanki |
| currentStart | 2016-05-46 7:54 | današnji start |
| stopduration | 5 | min.čas postanka |
| vehiclecounter | 191378 | trenutni števec kilometrov |
| description | dodatni opis | |
| faktorKM | 0 | korekcijski faktor km (%) |
| dashdisplay | numeric | nivo goriva v L |
| dashdisplayp | numeric | nivo goriva v % |
| minDist | numeric | startni števec km v dnevu |
| totaldistance | numeric | končni števec km v dnevu |
| minFuelCons | numeric | startna poraba v dnevu L |
| FuelCons | numeric | končna poraba v dnevu L |
| tcspeed | numeric | trenutno hitrost km/h po števcu |
| enginespeed | numeric | trenutni obrati na minuto |
| skup | text | skupina/filter kateri pripada naprava (vrnjena prva po seznamu) |
- prevožene km v dnevu: totaldistance-minDist
- poraba goriva v dnevu: FuelCons-minFuelCons
Funkcija: GETHISTORY
opis: Funkcija vrne vse zapise za zahtevani datum
parametri:
apikey - api ključ - obvezen,
IDNaprava - ID naprave
DATUM- datum, oblika YYYYMMDD
CAS- ura HHNNSS (če parametra ni, potem vrne funkcija vse zapise za podani datum)
primer klica funkcije: http://track.si:8887/gethistory?apikey=test&IDnaprava=8103&datum=20160516&cas=090520
odgovor:
| ime polja | primer podatka | opis |
| id | 249431882 | unikatni ID zapisa TRACK.SI |
| uporabnik | 8103 | unikatna oznaka naprave |
| cas | 2016-05-16 7:19 | čas odčitavanja GPS pozicije |
| y | 46.0859 | koordinata WGS 84 |
| x | 14.4754 | koordinata WGS 84 |
| dat_sp | 2016-05-16 7:19 | čas vpisa podatka na strežnik |
| ds | 432 | razdalja do predhodne GPS pozicije (m) |
| dv | 57 | hitrost km/h |
| dt | 30 | čas od predhodne GPS pozicije (sek) |
| kraj1 | LJUBLJANA | lokacija 1 |
| kraj2 | CELOVŠKA CESTA 291 | lokacija 2 |
| stsat | 9 | število satelitov |
| z | 315 | nadmorska višina |
| gkx | 5459798 | Gauss kreager koordinata |
| gky | 5104772 | Gauss kreager koordinata |
| izhod1 | 0 | DIN1- kontakt ključa (0-ne, 1-da) |
| izhod2 | 0 | DIN2- dig.vhod (0-ne, 1-da) |
| alfa | 144 | smer |
| country | SI | država |
Funkcija: GETDATELOG
opis: Funkcija vrne za napravo najstarejši čas v dnevu. Najstarejši čas se ujema z zadnji podatkov iz funkcije GetHistory. Podatki v sistem prihajajo vedno po metodi FIFO tako se lahko za poljuben datum/naprava preveri če so preneseni vsi podatki
parametri:
apikey - api ključ - obvezen,
IDNaprava - ID naprave - opcija (če ni parametra sistem vrne podatke za vse naprave, ki pripadajo API key)
DATUM- datum, oblika YYYYMMDD
primer klica funkcije: http://track.si:8887/getdatelog?apikey=test&IDnaprava=8103&datum=20160516
odgovor:
| ime polja | primer podatka | opis |
| uporabnik | 8103 | unikatna oznaka naprave |
| datum | 2016-05-16 | datum |
| konec | 2016-05-16 19:42:43 | najstarejši čas GPS poozicije v dnevu |
Funkcija: GETDAILYSTAT
opis: Funkcija vrne za napravo dnevno statistiko za napravo
parametri:
apikey - api ključ - obvezen,
IDNaprava - ID naprave - opcija (če ni parametra sistem vrne podatke za vse naprave, ki pripadajo API key)
DATUM- datum, oblika YYYYMMDD
primer klica funkcije: http://track.si:8887/getdailystat?apikey=test&IDnaprava=8103&datum=20160516
odgovor:
| ime polja | primer podatka | opis |
| datum | 2016-05-16 | datum |
| uporabnik | 8103 | unikatna oznaka naprave |
| casmax | 2016-05-16 19:42:43 | najstarejši čas GPS poozicije v dnevu |
| mincas | 2016-05-16 06:10:11 | prvi čas GPS poozicije v dnevu |
| povphitrost | 39 | povprečna hitrost v km/h |
| maxhitrost | 142 | max. hitrost v km/h |
| skupaj | 74889 | prevožena pot v metrih |
| casp | 39394 | čas postankov - sekunde |
| upopis | Coolio 1 | poimenovanje naprave na dan |
| counter | 15584 | števec kilometrov - kumulativa |
Funkcija: GETPST
opis: Funkcija vrne seznam postankov za napravo v dnevu, sortiranje po ID naprave in času prihoda na lokacijo
parametri:
apikey - api ključ - obvezen,
IDNaprava - ID naprave - opcija (če ni parametra sistem vrne podatke za vse naprave, ki pripadajo API key)
DATUM- datum, oblika YYYYMMDD
primer klica funkcije: http://track.si:8887/getpst?apikey=test&IDnaprava=8103&datum=20160516
odgovor:
| ime polja | primer podatka | opis |
| datum | 2016-05-16 | datum |
| uporabnik | 8103 | unikatna oznaka naprave |
| cas | 2016-05-25 19:29:56 | čas prihoda na lokacijo |
| lokacija | Trebnje, Kidričeva ulica 16 | naslov lokacije |
| trajanje | 862 | čas vožnje do lokacije (od predhodne) v sekundah |
| ptrajanje | 4338 | trajanje postanka na lokaciji v sekundah |
| trajajnjes | 0:14:22 | čas vožnje do lokacije (oblika čas) |
| ptrajanjes | 1:12:18 | trajanje postanka na lokaciji (oblika čas) |
| razdalja | 4661 | prevožena pot do lokacije (od predhodne) v metrih |
| wx | 15.0069 | koordinata postanka WGS 84 |
| wy | 45.911 | koordinata postanka WGS 84 |
| gkx | 5500907 | Gauss kreager koordinata |
| gky | 5085201 | Gauss kreager koordinata |
| konec | 2016-05-25 20:42:14 | odhod iz lokacije |
| maxhitrost | 63 | maksimalna hitrost v km/h |
Naslednji dve funkciji sta namenjeni za dostop do podatkov o aktivnosti Eye beacon senzorjih proizvajalca Teltonike. Naprava periodično skenira preko Bluetooth in vrne zaznane senzorje. Tako dobimo na sistem periodično podatke o prisotnih senzorjih v bližini. Pri tem imamo dva režima in sicer med vožnjo in mirovanjem in lahko ločeno nastavimo periodo pošiljanja.
Funkcija: GETBEACONS
Opis: Funkcija vrne seznam Beacon-ov ki so vpisani v aplikaciji track.si na šifrantu za Beacone. Poleg ID ja vrne še poimenovanje iz šifrante
Primer klica: http://track.si:8080/getbeacons?apikey=test
parameter: apikey - api ključ - obvezen
Funkcija: GETBEACONH
Opis: Funkcija vrne zgodovino aktivnosti/dosegljivosti Beracon
Primer klica: http://track.si:8080/getbeaconh?apikey=test&beaconID=0F1060ACD68055AABABA0A57812B0055&datum=20230301&cas=200000
parameter: apikey - api ključ - obvezen, beacoind je unikatna oznaka beacona, pridobi se iz predhodne funkcije, datum v obliki YYYYMMDD in cas v obliki HHNNSS
Zgornja funkcija bo vrnila največ 1000 zapisov od 01.03.2023 20:00:00 dalje ki pripada beacon-u z oznako 0F1060ACD68055AABABA0A57812B0055.
ID je unikatni zapis iz baze, ki vedno narašča, cas pove čas zaznava senzorja v bližini, beacontype je 21 ali 01 odvisno od nastavitev, y in x sta kordinati geopozicije, uporabnik je id naprave, ki je zaznala beacon, signal izraža izmerjeno moč, ki kaže na oddaljenost senzorja. Podatki prihajajo v bazo po sistemu FIFO.
Funkcijo GetbeaconH je smiselno kombinirati s funkcijo GetHistory. In sicer sta tabeli povezani s polji uporabnik in cas. Za vsak zapis getbecaonH najdete dodatne podatke v tabeli zgodovine (GetHistory) naprave, če pogledate v tabelo zgodovine z istim cas in uporabnik
