Etusivu / Tietoa Suomi.fistä / Leijukkeet ja avoimet rajapinnat / REST-rajapinta ja XML-siirrot Suomi.fistä

REST-rajapinta ja XML-siirrot Suomi.fistä

Suomi.fi-portaalin sisällöistä suurin osa on haettavissa avoimen REST-rajapinnan kautta hyödynnettäväksi muissa verkkopalveluissa ja tietojärjestelmissä. Oletuksena rajapinta tarjoaa tiedot XML-muodossa, mutta tiedot saa myös JSON-muodossa esimerkiksi selainpohjaisia sovelluksia varten.

Rajapinnan hakuosoite on www.suomi.fi/rest/, josta saa hakuosoitteen perään lisättävillä termeillä määritellyt tiedot. Tiedot tarjotaan oletuksena suomeksi, ruotsin- tai englanninkieliset tiedot saa lisäämällä hakuosoitteeseen kielikoodin "sv" tai "en". Esimerkiksi ruotsinkieliset tiedot saa hakuosoitteesta www.suomi.fi/rest/sv/.

Jokaisen kyselyn yhteydessä on annettava kyselyn perään parametri "apikey" ja sen arvona voimassa oleva tunnistekoodi. API key on tilattavissa sivulta REST API keyn tilaus.

Seuraavassa on joitain esimerkkejä rajapinnan käytöstä.

Suomi.fin palveluluokat

Suomi.fin palveluluokat ovat Palvelut aiheittain -osion aiheita, joiden alle portaalin pääasiallinen sisältö on järjestetty. Listauksen kaikista palveluokista saa eri kieliversioina kyselyillä

http://www.suomi.fi/rest/services/?apikey=xxxx
http://www.suomi.fi/rest/sv/services/?apikey=xxxx (ruotsiksi)
http://www.suomi.fi/rest/en/services/?apikey=xxxx (englanniksi)

Tarkemmat tiedot yksittäisen palveluluokan alla olevista palveluluokista, asiasanoista sekä sivun sisällön html-muodossa saa lisäämällä edellä mainitun kyselyn perään palveluluokan nimen. Esimerkiksi Asuminen ja rakentaminen -palveluluokan tiedot saa kyselyllä

http://www.suomi.fi/rest/services/asuminen_ja_rakentaminen/?apikey=xxxx

Palveluluokan alle on sijoitettu erityyppisiä sisältöjä. Näitä ovat palvelulinkit (links) sekä asiointipalvelut ja lomakkeet (forms). Esimerkiksi Asuminen ja rakentaminen -palveluluokkaan kuuluvat koko maata koskevat sisällöt saa kyselyillä

http://www.suomi.fi/rest/services/asuminen_ja_rakentaminen/links/?apikey=xxxx (linkit)
http://www.suomi.fi/rest/services/asuminen_ja_rakentaminen/forms/?apikey=xxxx (asiointipalvelut ja lomakkeet)

Kuntakohtaiset tiedot saa lisäämällä kyselyn perään kunnan nimen. Esimerkiksi Helsingin linkit Asuminen ja rakentaminen -sivulla saa kyselyllä

http://www.suomi.fi/rest/services/asuminen_ja_rakentaminen/links/helsinki/?apikey=xxxx

Maakunnat ja kunnat

Suomi.fistä saa ajantasaisen Kuntaliiton ylläpitämän tiedon maakunnista ja kunnista. Listauksen maakuntaan, esimerkiksi Uusimaahan, kuuluvista kunnista saa kyselyllä

http://www.suomi.fi/rest/counties/uusimaa/?apikey=xxxx

Tiedot esimerkiksi Vihdin kunnasta ja Vihdin palveluista saa kyselyllä

http://www.suomi.fi/rest/municipalities/vihti/?apikey=xxxx

Organisaatioiden lomakkeet

Suomi.fin REST antaa kuntien lomakkeiden lisäksi listauksen julkishallinnon muiden organisaatioiden lomakkeista ja sähköisistä asiointipalveluista, jotka löytyvät Suomi.fistä kautta. Kysely tehdään organisaatiokohtaisesti ja sen perusmuoto on

http://www.suomi.fi/rest/forms/{organisaation_nimi}?apikey=xxxx

Organisaatioiden nimet on listattu rest-kyselyssä /rest/organizations/ joka listaa kaikki järjestelmän tuntemat organisaatiot. Nimet tulee antaa kyselyurliin siinä muodossa, jossa ne restistä saa. Esimerkiksi Kelan lomakkeet ja asiointipalvelut saa kyselyllä

http://www.suomi.fi/rest/forms/kansanelakelaitos_kela?apikey=xxxx

Kyselyihin lisättävät parametrit

Palautettavien tietojen muoto, rajaus ja järjestys voidaan määritellä kyselyn perään lisättävillä parametreillä. Esimerkiksi palvelulinkit Asuminen ja rakentaminen -aiheesta JSON-muodossa saa kyselyllä

http://www.suomi.fi/rest/services/asuminen_ja_rakentaminen/links/?apikey=xxxx&return=json

Kaikki tammikuun 2013 alun jälkeen lisätyt palvelulinkit taas saa kyselyllä

http://www.suomi.fi/rest/links?start_date=2013-01-01&apikey=xxxx

Vastaavasti ennen maaliskuuta 2013 lisätyt palvelulinkit saa kyselyllä

http://www.suomi.fi/rest/links?end_date=2013-02-28&apikey=xxxx

Kyselyn tulokset voi myös pyytää järjesteltynä joko otsikon (sort=title, oletus), päivämäärän (sort=date) tai suosituimmuuden (sort=popularity, vain links ja forms) mukaan. Esimerkiksi kaikki palvelulinkit aakkosjärjestyksessä saa kyselyllä

http://www.suomi.fi/rest/links?sort=title&apikey=xxxx

Vastaavasti päivämäärän mukaan vanhimmasta uusimpaan järjesteltynä linkit saa kyselyllä

http://www.suomi.fi/rest/links?sort=date&apikey=xxxx

Sort-parametria voi tarkentaa parametrillä reverse=true joka vaihtaa sorttausjärjestyksen toisinpäin. Esimerkiksi linkit päivämäärän mukaan järjesteltynä uusimmasta vanhempaan saa kyselyllä

http://www.suomi.fi/rest/links?sort=date&reverse=true&apikey=xxxx

Hakutulosten määrää voi myös rajoittaa limit=xx-parametrillä, joten esimerkiksi kymmenen uusinta linkkiä saa kyselyllä

http://www.suomi.fi/rest/links?sort=date&reverse=true&limit=10&apikey=xxxx

Limit-parametri käsitellään aina viimeiseksi, joten sillä voi vain rajata muiden parametrien määrittelemään tulosjoukkoa.

Vastaavasti kymmenen suosituinta linkkiä saa kyselyllä

http://www.suomi.fi/rest/links?sort=popularity&limit=10&apikey=xxxx

Yhteenveto kaikista kyselytyypeistä

Palveluluokat

www.suomi.fi/rest/services/?apikey=xxxx
www.suomi.fi/rest/services/{palveluluokka|oid}/?apikey=xxxx
www.suomi.fi/rest/services/{palveluluokka|oid}/forms/?apikey=xxxx
www.suomi.fi/rest/services/{palveluluokka|oid}/forms/{kunta|oid}/?apikey=xxxx
www.suomi.fi/rest/services/{palveluluokka|oid}/links/?apikey=xxxx
www.suomi.fi/rest/services/{palveluluokka|oid}/links/{kunta|oid}/?apikey=xxxx
www.suomi.fi/rest/services/{palveluluokka|oid}/laws/?apikey=xxxx

Maakunnat

www.suomi.fi/rest/counties/?apikey=xxxx
www.suomi.fi/rest/counties/{maakunta|oid}/?apikey=xxxx

Kunnat

www.suomi.fi/rest/municipalities/?apikey=xxxx
www.suomi.fi/rest/municipalities/{kunta|oid}/?apikey=xxxx
www.suomi.fi/rest/municipalities/{kunta|oid}/forms?apikey=xxxx
www.suomi.fi/rest/municipalities/{kunta|oid}/links?apikey=xxxx

Organisaatiot

www.suomi.fi/rest/organizations/?apikey=xxxx
www.suomi.fi/rest/organizations/{organisaatio|oid}/?apikey=xxxx
www.suomi.fi/rest/organizations/{organisaatio|oid}/links/?apikey=xxxx

Palvelutietolinkit

www.suomi.fi/rest/links/?apikey=xxxx
www.suomi.fi/rest/links/{kunta|oid}/?apikey=xxxx
www.suomi.fi/rest/links/{palveluluokka|oid}/?apikey=xxxx
www.suomi.fi/rest/links/{oid}/?apikey=xxxx

Lomakkeet

www.suomi.fi/rest/forms/?apikey=xxxx
www.suomi.fi/rest/forms/{kunta|oid}/?apikey=xxxx
www.suomi.fi/rest/forms/{organisaation_nimi}?apikey=xxxx
www.suomi.fi/rest/forms/{palveluluokka|oid}/?apikey=xxxx
www.suomi.fi/rest/forms/{oid|lomaketunniste}/?apikey=xxxx

Asiasanat

www.suomi.fi/rest/keywords/?apikey=xxxx
www.suomi.fi/rest/keywords/{keywordid|langversionid}/?apikey=xxxx

Sisältöä hyödyntävällä sivulla tulee mainita lähde seuraavasti: Tieto on tuotu Väestörekisterikeskuksen tuottamasta Suomi.fi-portaalista. Suomi.fi-toimitus ottaa mielellään vastaan tiedon siitä, millä verkkosivuilla avointa rajapintaa on hyödynnetty.

 
Siirry Kansalaisneuvonta.fi-sivustolle.
Siirry Suomi.fin Työhuone-sivustolle - tietoja ja palveluja viranomaisille.
Siirry Yrityssuomi.fi-verkkopalveluun.