Rajapinnan käyttöönotto paikkatietojärjestelmissä havaintohakuportaalista tilatun API-avaimen avulla

Lajitietokeskuksen API-rajapintaan yhdistetään paikkatietojärjestelmästä käyttämällä rajapintakyselyä linkkinä, johon lisätään paikkatietomääritelmät ja API-avaimet. Jos käytät Viranomaisportaalista tai aineistopyyntöjärjestelmästä tilattua permissionToken -avainta, sinun ei tarvitse erikseen määritellä hakusuodattimia, sillä tieto havaintohakuportaalista tehdystä havaintohausta sisältyy saamaasi API-avaimeen.

(Avoimen rajapinnan käyttäjien tulee aina määritellä käytetyt hakuparametrit ja halutut lisätietokentät rajapintalinkissä. Tekniset ohjeet yhteyden muodostamiseen Lajitietokeskuksen avoimeen rajapintaan ja rajapintakyselyiden tekoon löydät täältä.)

Viranomaisportaalista tai aineistopyyntöjärjestelmästä tilattavan permissionToken-avaimen lisäksi tarvitset henkilökohtaisen access_token -avaimen. Jos sinulla ei vielä ole omaa access tokenia (et ole aiemmin käyttänyt Lajitietokeskuksen rajapintaa) voit tilata sen sähköpostiisi tämän linkin kautta. Lisää oma sähköpostiosoitteesi muodossa

{ "email": "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=xxx

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

Rajapinnan 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ä 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. ja vaihdetaan Encoding/Koodaus: System tai AutomaticValitaan 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):

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.