API

Pored toga što običnim korisnicima na raspolaganje stavlja GUI za pretragu linija GSP-a na osnovu naziva neke Beogradske ulice kroz koje one prolaze, servis PrevozNIK istu tu funkcionalnost nudi i programerima, u vidu javnog API-ja.

API, odnosno web servis, kojeg ova aplikacija nudi, zasniva se na istoj "business" logici koja je implementirana na početnoj stranici ovog sajta, tačnije za obradu zahteva iz forme za pretragu. Konzumiranje tog web servisa se svodi na slanje HTTP zahteva na određeni URL, i pritom prosleđujući parametre za pretragu. Ti parametri odgovaraju poljima za pretragu, koja se nalaze u formi na početnoj stranici. Slanje zahteva na web servis ove aplikacije za rezultat ima odgovor u XML ili JSON formatu, u zavisnosti od toga za koji format se odlučio korisnik pri slanju zahteva, budući da ta opcija takođe može biti definisana kroz URL.

Sintaksa API-ja je na engleskom jeziku, iz prostog razloga što je ovaj sajt dvo-jezički (verzija na srpskom i engleskom jeziku), a kako API ne može biti na dva jezika, engleski se nameće kao najrasprostranjeniji svetski jezik i jezik kojeg mnogi smatraju globalnim.

Zahtev na API servisa PrevozNIK mora imati sledeću formu:

http://prevoznik.nikolaposa.in.rs/api/format?parametri

pri čemu format može biti xml - za odgovor u XML formatu, ili json - za odgovor u JSON formatu.

Što se parametara tiče, situacija je ista kao i u formi za pretragu na početnoj stranici sajta, pa je tako potrebno poslati barem naziv ulice. U nastavku je opis podržanih parametara:

street - Naziv ulice za koju se vrši pretraga,
mode - Parametar za filtiranje linija koje će biti vraćene u odgovoru po režimu njihovog rada. Pritom, vrednost ovog parametra može biti 0 - bilo koje linije, 1 - dnevne linije, 2 - noćne linije. Ovaj parametar je opcioni i ne mora biti poslat u zahtevu, a njegova podrazumevana vrednost je 0.

Primer jednog zahteva bi izgledao ovako:

http://prevoznik.nikolaposa.in.rs/api/xml?street=kneza+milosa&mode=1

* Obratite pažnju da URL vašeg zahteva mora biti validan, tačnije, vrednosti parametara u njemu moraju biti pravilno URL-kodovani.

Odgovor na zahtev iz gornjeg primera bi izgledao ovako:

<PrevozNIK_Search>
    <status>OK</status>
    <nearby_streets>false</nearby_streets>
    <result>
        <street>Kneza Miloša</street>
        <transport_line>
            <id>23</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>37</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>40</id>
            <mode>daily</mode>
            <type>trolley bus</type>
        </transport_line>
        <transport_line>
            <id>41</id>
            <mode>daily</mode>
            <type>trolley bus</type>
        </transport_line>
        <transport_line>
            <id>44</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>52</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>53</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>56</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>56 L</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>58</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>74</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>78</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
        <transport_line>
            <id>83</id>
            <mode>daily</mode>
            <type>bus</type>
        </transport_line>
    </result>
</PrevozNIK_Search>

Odgovor se sastoji od root elementa <PrevozNIK_Search>, zajedno sa tri top-level elementa:

status - govori o statusu odgovora, i može imati jednu od sledećih vrednost:
- OK - zahtev je uspešan i sadrži rezultate
- NO_RESULTS - zahtev je uspešan, ali bez rezultata
- INVALID_REQUEST - zahtev je nekompletan ili nevalidan, najčešće zbog toga što nije poslat naziv ulice (street parametar)
- ERROR - govori da je došlo do greške pri obradi zahteva
nearby_streets - marker koji govori da li su u rezultatima sadržane okolne ulice ili je ustanovljeno da neke GSP linije prolaze kroz ulicu koja je poslata preko street parametra.
result - Jedan ili više rezultata, koji predstavljaju pronađene trase (nazive ulica ili objekata), zajedno sa linijama GSP-a koje kroz njih prolaze.

U slučaju da polje za status ima vrednost "INVALID_REQUEST" ili "ERROR", message element, koji sadrži detaljnije informacije o samom statusu, će biti u okviru odgovora umesto elemenata nearby_streets i result.