Lajitietokeskuksen REST-rajapinta yhdistetään paikkatietojärjestelmään käyttämällä rajapintakyselyä linkkinä, johon lisätään paikkatietomääritelmät ja API-avaimet. Alla vielä ohjeet, kuinka yhdistät rajapinnan QGIS-paikkatieto-ohjelmistoon.
API-avaimet
API-avaimia on kahdenlaisia: permissionToken ja access_token.
- permissionToken: Saatavilla vain viranomaisportaalista tai aineistopyyntöjärjestelmästä. Tämä avain antaa pääsyn käyttörajoitettuihin aineistoihin, jos olet sellaisiin oikeutettu. Tämä avain on hakukohtainen sisältäen hakufiltterit, joten rajauksia ei tarvitse erikseen määritellä kyselyyn.
- access_token: Henkilökohtainen avain, joka tarvitaan kaikkiin rajapintapyyntöihin. Jos sinulla ei ole avainta, voit tilata sen sähköpostiisi alla olevien ohjeiden mukaan.
Rajoitetun aineiston avain permissionToken
Käyttörajoitetut aineistot ovat käytettävissä vain Viranomaisportaalista tai aineistopyyntöjärjestelmästä pyydetyn API-avaimen avulla.
Jos haluat permissionToken-avaimen käyttöösi, tee ensin haluamasi aineistohaku viranomaisportaalissa. Aineistoa täytyy rajata vähintään yhdellä hakuehdolla, mutta havaintomäärällä ei ole ylärajaa kuten havaintolatauksissa.
Klikkaa seuraavaksi Lataa aineisto -valikosta kohtaa Pyydä API-avain. Aineistonkäyttö tulee perustella samoin kuin aineistolatauksen yhteydessä. API-avain on voimassa valintasi mukaan kolme kuukautta tai yhden vuoden pyynnön tekemisestä. Jos aineiston käyttötarve jatkuu pidempään, on tehtävä uusi aineistohaku ja pyydettävä avain uudelleen.
Tämän jälkeen voit klikata Lähetä ja kopioida API-avaimesi talteeen.
Henkilökohtainen access_token
Henkilökohtaisen access_tokenin voit tilata sen sähköpostiisi tämän linkin kautta. Lisää oma sähköpostiosoitteesi muodossa
my.email@example.com
linkin takaa löytyvään valkoiseen tekstikenttään ja klikkaa ”Try it out”. Näin saat oman henkilökohtaisen access_token -avaimen sähköpostiisi. Lisätietoa englanniksi
GeoJSON-linkin muodostaminen
Värikoodattu esimerkkikysely, joka kertoo rajapintalinkin eri osien merkitykset:
Tämä esimerkki palauttaa havaintojen alkuperäiset geometriat WGS84-koordinaattijärjestelmässä. Jos havaintoja on alun perin tallennettu eri geometriatyyppeinä (pisteet, alueet, viivat), rajapinta palauttaa kolme erillistä karttatasoa. Jos haluat esimerkiksi keskipisteet, vaihda ORIGINAL_FEATURE tilalle CENTER_POINT. Tällöin saat rajapinnasta vain yhden karttatason.
Kopioitava esimerkki API-avaimen sisältävästä linkistä. Lisää ”xxx”-tilalle omat API-avaimet (permissionToken ja access_token) ja tarvittaessa sivutus (paging).
https://api.laji.fi/v0/warehouse/query/unit/list?format=GeoJSON&featureType=ORIGINAL_FEATURE&crs=WGS84&permissionToken=xxx&access_token=xxxKun olet muodostanut rajapintalinkin omien tarpeidesi mukaan, voit kopioida sen ja hakea sen avulla lajihavaintotiedot mihin tahansa paikkatietojärjestelmään tai karttapalveluun, joka tukee GeoJSON-formaatin lukua rajapinnasta. Muista, että tekemäsi haku saattaa sisältää käyttörajoitettua aineistoa, joten olet vastuussa rajapintalinkin käytöstä käyttöehtojen mukaisesti. Älä jaa API-avaimiasi tai niitä sisältävää linkkiä tai rajapinnasta haettua havaintotietoa muille kuin asianosaisille.
Huom! Jos sinulla ei ole permission_tokenia, voit silti käyttää rajapintaa. Tällöin joudut määrittelemään kaikki rajaukset suoraan kyselyyn, etkä saa käyttöösi rajoittamattomia havaintoja. Esimerkiksi:
https://api.laji.fi/v0/warehouse/query/unit/list?format=GeoJSON&featureType=ORIGINAL_FEATURE&crs=WGS84&createdDateYear=2024&access_token=xxxRajapinnan käyttöönotto QGIS -paikkatieto-ohjelmistossa
Rajapinnan käyttäjä voi muodostaa kyselyn api.laji.fi -rajapinnasta ja linkittää vastauksen QGIS:iin GeoJSON-muodossa, jolloin QGIS hakee kyseisen linkin mukaisen karttatason karttanäkymään.
Älä tee havaintotietoihin korjauksia tai muita muutoksia paikkatieto-ohjelmistoissa. Nämä korjaukset eivät päädy Lajitietokeskukseen, joten jos haet sieltä havaintoja uudelleen, muutokset eivät ole käytettävissä. Korjaukset kannattaa tehdä paikallisesti omaan aineistoon, tai Laji.fi:n laadunvalvontatyökalulla.
Rajapintayhteyden muodostaminen
Valitaan QGIS-projektin ylävalikosta Layer – Add Layer – Add vector Layer
Valitaan aukeavasta ikkunasta Protocol/Protokolla: HTTPS, Cloud, etc.
Valitaan Type/Tyyppi -valikosta GeoJSON ja lisätään rajapintalinkki URI-osoitepalkin kohdalle. Lopuksi painetaan Add/Lisää.
Esimerkki käytettävästä URI-osoitteesta (lisää tarvittaessa sivutus, koska muuten rajapinta palauttaa vain 100 ensimmäistä havaintoa):
https://api.laji.fi/v0/warehouse/query/unit/list?format=GeoJSON&featureType=ORIGINAL_FEATURE&crs=WGS84&permissionToken=xxx&access_token=xxx
Jos havaintoja on alun perin tallennettu eri geometriatyyppeinä (pisteet, alueet, viivat), QGIS hakee rajapinnasta kolme erillistä karttatasoa. Jos haluat esimerkiksi keskipisteet, vaihda ORIGINAL_FEATURE tilalle CENTER_POINT. Tällöin saat rajapinnasta vain yhden karttatason.
Kun aineisto on latautunut, voit tallentaa sen normaaliin tapaan osaksi QGIS-projektiasi, jolloin rajapinnan kautta haettu karttataso päivittyy aina QGIS:n käynnistyksen yhdessä. Rajapintayhteyden voi myös päivittää F5-painikkeella. Tarvittaessa voit tehdä aineistosta paikallisen kopion tietokoneellesi klikkaamalla tasoa hiiren oikealla ja valitsemalla Export → Save Features as… ja samalla muuttaa tiedostomuodon esim. Shapefile tai GeoPackage -muotoon.