XML-siirrot Suomi.fistä

Huom! Suomi.fin REST-rajapintaan on tullut muutos 20.4.2012. Jokaisen kyselyn yhteydessä on annettava kyselyn perään parametri "apikey" ja sen arvona voimassa oleva tunnistekoodi. Apikey-parametri on tilattavissa sivulta REST apikeyn tilaus.

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/.

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), asiointipalvelut ja lomakkeet (forms) ja lait (laws). 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)
http://www.suomi.fi/rest/services/asuminen_ja_rakentaminen/laws/?apikey=xxxx (lait)

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

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?return=json/?apikey=xxxx

Kaikki elokuun alun jälkeen lisätyt palvelulinkit taas saa kyselyllä

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

Vastaavasti ennen elokuuta lisätyt palvelulinkit saa kyselyllä

http://www.suomi.fi/rest/links?end_date=2010-07-31/?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&reverse=true&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/{palveluluokka|oid}/?apikey=xxxx
www.suomi.fi/rest/forms/{oid|lomaketunniste}/?apikey=xxxx

Lait

www.suomi.fi/rest/laws/?apikey=xxxx
www.suomi.fi/rest/laws/{palveluluokka|oid}/?apikey=xxxx
www.suomi.fi/rest/laws/{finlex-tunniste|oid}/?apikey=xxxx

Asiasanat

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

Uutiset

www.suomi.fi/rest/news/?apikey=xxxx
www.suomi.fi/rest/news/{oid}/?apikey=xxxx

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