Rajapintakuvaus Liikenneluvat

Transkriptio

1 Rajapintakuvaus Liikenneluvat

2 MUUTOSHISTORIA Versio Päiväys Laatija Muutoksen kuvaus / hyväksyjä 0.1 Tapio Oikarainen Ensimmäinen versio 2(7)

3 Sisällysluettelo 1. Johdanto Yleistä Rajaus Dokumentaatio Liikennelupakysely Käyttöoikeudet ja roolit Palvelukutsuparametrit Palvelukutsu Palvelukutsuesimerkkejä Vastaussanomat Onnistuneen haun vastaussanoma Epäonnistuneen haun vastaussanoma Tietokohtaisia muodostussääntöjä Osoitetiedot Turvakiellon alaiset tiedot Tietojen esitystavat Numeerinen tieto Aakkosnumeerinen tieto Tyhjä kenttä (7)

4 1. Johdanto 1.1. Yleistä 1.2. Rajaus Tämä dokumentti kuvaa palvelurajapinnat, joita käytetään haettaessa liikennelupatietoja teknisellä sovellus-sovellus-yhteydellä Trafin järjestelmästä. Rajapinnan kutsut tehdään REST -muodossa. Tietojen välityksessä käytetään JSON-esitystapaa. Tämä dokumentti ei sisällä rajapinnan varsinaisia JSON-kuvauksia vaan ne ovat liitteenä (JSON-skeema -tiedosto) Dokumentaatio 2. Liikennelupakysely Rajapintakuvausdokumentaatio muodostuu seuraavista osista: 1. Tämä dokumentti on kuvaus liittymästä ja rajapinnasta laadittuna tietojen vastaanottajan näkökulmasta. Tässä dokumentissa on kuvattu myös välitystietueen tietosisältö. 2. Rajapintojen kuvaukset JSON-skeemana: LiikenneluvatRajapintaSchema.json 3. Välitettävien tietojen tietokuvaukset: Aineistokuvaus_liikenneluvat.xlsx Liikenneasioiden rekisteri sisältää tietoa voimassaolevista liikenneluvista. Liikennelupia ovat mm. taksiliikenneluvat, joukkoliikenneluvat ja tavaraliikenneluvat. Liikennelupien avoimen rajapinnan kautta on mahdollista hakea tietoja Y-tunnuksen, luvanhaltijan nimen, luvan yksilöintitunnuksen tai postinumeron perusteella voimassa olevasta liikenneluvasta, luvan yksilöintitunnuksesta, luvanhaltijan nimestä ja toiminnanharjoittamiseen liittyvistä yhteystiedoista. Henkilö- ja tavaraliikenteen ilmoituksenvaraisen toiminnan osalta on saatavilla vastaavat tiedot, pois lukien luvan yksilöintitunnus Käyttöoikeudet ja roolit Palvelu on kaikille avoin, eikä erilisiä käyttöoikeuksia tarvita. Kutsumalla rajapintaa käyttäjä hyväksyy Trafin avoimen tietoaineiston Creative Commons Nimeä 4.0 Kansainvälinen -lisenssin. 4(7)

5 2.2. Palvelukutsuparametrit Liikennelupakyselyn kutsuparametrit Parametrin nimi Selite Arvot Valinnainen NIMI LUPANUMERO YTUNNUS Luvanhaltijan nimi Luvan yksilöivä tunnus Y-tunnus, jos luvanhaltija on yritys tai yhteisö JOUKKO-xxxxxx (Joukkoliikennelupa) JJ-xxxxxx (Joukkoliikennelupajäljennös) JY-xxxxxx (Joukkoyhteisölupa) JYJ-xxxxxx (Joukkoyhteisölupajäljennös) T-xxxxxx (Kotimaan tavaraliikennelupa) KUTSU-xxxxxx (Kutsujoukkoliikennelupa) REITTI-xxxxxx (Reittiliikennelupa) TAKSI-xxxxxx (Taksiliikennelupa) TY-xxxxxx (Tavarayhteisölupa) TYJ-xxxxxx (Tavarayhteisölupajäljennös) LTR-xxxxxx (Traktoriliikennelupa) xxxxxxx-x LUPALAJI Luvan kategoria Ilmoituksenvarainen taksiliikenne Ilmoituksenvarainen tavaraliikenne Joukkoliikennelupa Joukkoliikennelupajäljennös Joukkoyhteisölupa Joukkoyhteisölupajäljennös Kotimaan tavaraliikennelupa Kutsujoukkoliikennelupa Reittiliikennelupa X 5(7)

6 LAHIOSOITE POSTINUMERO POSTITOIMI- PAIKKA Luvanhaltijan katuosoite ja kadun/asunnon numero tai postilokeroosoite Luvanhaltijan osoitteen postinumero Luvanhaltijan osoitteen postitoimipaikka Taksiliikennelupa Tavarayhteisölupa Tavarayhteisölupajäljennös Traktoriliikennelupa xxxxx X X 2.3. Palvelukutsu Kutsu REST -palvelurajapintaan tehdään antamalla palvelun URI ja palvelukutsun parametrit GET -metodilla. Testiympäristö: Tuotantoympäristö: Kutsun on sisällettävä vähintään yksi pakollisista kutsuparametreistä. NIMI-parametrin kutsun on sisällettävä vähintään kolme merkkiä Palvelukutsuesimerkkejä Seuraavassa on esimerkkejä tuotantoympäristöön tehdyistä kutsuista. Esimerkki 1. Haetaan kaikki postinumeroalueen lupatiedot: Esimerkki 2. Haetaan kaikki postinumeroalueen taksiliikenteen lupatiedot (useampi hakuehto): Esimerkki 3. Haetaan yksittäinen taksiliikenneluvan tiedot, kun luvan yksilöintitunnus eli lupanumero tiedetään (lupanumeron on oltava täsmälleen oikeassa muodossa): Esimerkki 4: Haetaan kaikki luvanhaltijat, joiden nimitieto sisältää merkkijonon korho 6(7)

7 3. Vastaussanomat 3.1. Onnistuneen haun vastaussanoma Onnistuneesta hausta palautetaan kysytyn liikenneluvan tiedot käyttäjän kyselyn mukaisesti. Vastaussanoman rakenne on kuvattu JSON -skeemassa Epäonnistuneen haun vastaussanoma Jos hakuehdoilla ei löydy tietoja, palauttaa kysely tyhjän tuloksen palvelun kutsujalle. Jos pakollinen hakuehto puuttuu, palauttaa kysely virheilmoituksen. 4. Tietokohtaisia muodostussääntöjä 4.1. Osoitetiedot Luvanhaltijan osoitetietona voi olla joko katuosoite tai postilokero-osoite Turvakiellon alaiset tiedot Rajapinnassa ei välitetä turvakiellon alaisia tietoja. 5. Tietojen esitystavat 5.1. Numeerinen tieto Numeerisen tiedon tietotyyppinä rajapinnassa on number. Tiedot sisältävät vain kokonaislukuja Aakkosnumeerinen tieto 5.3. Tyhjä kenttä Aakkosnumeerisen tiedon esitystapa rajapinnassa on string. Tyhjä tietokenttä ilmaistaan arvolla null. 7(7)