Rajapintakuvaus Liikenneluvat
MUUTOSHISTORIA Versio Päiväys Laatija Muutoksen kuvaus / hyväksyjä 0.1 Tapio Oikarainen Ensimmäinen versio 2(7)
Sisällysluettelo 1. Johdanto... 4 1.1. Yleistä... 4 1.2. Rajaus... 4 1.3. Dokumentaatio... 4 2. Liikennelupakysely... 4 2.1. Käyttöoikeudet ja roolit... 4 2.2. Palvelukutsuparametrit... 5 2.3. Palvelukutsu... 6 2.4. Palvelukutsuesimerkkejä... 6 3. Vastaussanomat... 7 3.1. Onnistuneen haun vastaussanoma... 7 3.2. Epäonnistuneen haun vastaussanoma... 7 4. Tietokohtaisia muodostussääntöjä... 7 4.1. Osoitetiedot... 7 4.2. Turvakiellon alaiset tiedot... 7 5. Tietojen esitystavat... 7 5.1. Numeerinen tieto... 7 5.2. Aakkosnumeerinen tieto... 7 5.3. Tyhjä kenttä... 7 3(7)
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). 1.3. 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. 2.1. 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)
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)
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ö: https://testijulkinen.liikennevirasto.fi/liikennelupahaku Tuotantoympäristö: https://julkinen.liikennevirasto.fi/liikennelupahaku Kutsun on sisällettävä vähintään yksi pakollisista kutsuparametreistä. NIMI-parametrin kutsun on sisällettävä vähintään kolme merkkiä. 2.4. Palvelukutsuesimerkkejä Seuraavassa on esimerkkejä tuotantoympäristöön tehdyistä kutsuista. Esimerkki 1. Haetaan kaikki postinumeroalueen 00130 lupatiedot: https://julkinen.liikennevirasto.fi/liikennelupahaku?postinumero=00130 Esimerkki 2. Haetaan kaikki postinumeroalueen 02600 taksiliikenteen lupatiedot (useampi hakuehto): https://julkinen.liikennevirasto.fi/liikennelupahaku?postinumero=02600&lupalaji=taksiliikennelupa Esimerkki 3. Haetaan yksittäinen taksiliikenneluvan tiedot, kun luvan yksilöintitunnus eli lupanumero tiedetään (lupanumeron on oltava täsmälleen oikeassa muodossa): https://julkinen.liikennevirasto.fi/liikennelupahaku?lupanumero=taksi-012345 Esimerkki 4: Haetaan kaikki luvanhaltijat, joiden nimitieto sisältää merkkijonon korho https://julkinen.liikennevirasto.fi/liikennelupahaku?nimi=korho 6(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. 3.2. 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. 4.2. 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. 5.2. Aakkosnumeerinen tieto 5.3. Tyhjä kenttä Aakkosnumeerisen tiedon esitystapa rajapinnassa on string. Tyhjä tietokenttä ilmaistaan arvolla null. 7(7)