Osoitteen geoapi.laji.fi rajapinta (API) perustuu OGC API Features -standardiin, jota voidaan pitää uudempana versiona OGC Web Feature Service (WFS) -rajapinnasta. Alun perin OGC API Features tunnettiin nimellä WFS3.0, mutta uudenlaisen teknisten ratkaisujen vuoksi OGC päätti muuttaa standardin nimeä. Uudet OGC API:t ovat yhteentoimivampia, modernimpia ja helpompia käyttää, kuin aikaisemmat WFS-palvelut. Niiden käyttämiseksi voi olla hyvä ymmärtää muutamia peruskäsitteitä.
Esimerkiksi OGC API Features -kyselyssä:
https://geoapi.laji.fi/ on aloitussivu (landing page). Tämä on siis se URL, jonka kopioimalla kaikki rajapinnan aineistot saa helposti liitettyä paikkatieto-ohjelmistoon, kuten QGIS:iin. Katso esimerkkikuva alempaa.
https://geoapi.laji.fi/collections listaa kaikki rajapinnan aineistot (collections).
https://geoapi.laji.fi/collections/satakunta_points näyttää tietoja ”satakunta_points” -nimisestä aineistosta.
https://geoapi.laji.fi/collections/satakunta_points/items näyttää ”satakunta_points” -nimisen aineiston havainnot.
https://geoapi.laji.fi/collections/satakunta_points/items?Elioryhma=Linnut näyttää kaikki lintuhavainnot aineistosta ”satakunta_points”.
https://geoapi.laji.fi/collections/satakunta_points/items?Elioryhma=Linnut&f=json näyttää kaikki lintuhavainnot aineistosta ”satakunta_points” formaatissa GeoJSON.
Kuten ylemmistä esimerkeistä huomaa, hakua voi rajata kaikilla aineiston parametrillä, sekä muutamalla muutta. Näistä yksi esimerkki oli parametri f, joka muuttaa tuloksen formaatin HTML:stä GeoJSON:iin.
Myös muita lisäparametrejä on. Käytä bbox– tai datetime-parametreja rajataksesi dataa maantieteellisesti tai päivämäärän ja kellonajan perusteella.
Limit-parametria voidaan käyttää rajaamaan palautettavien kohteiden enimmäismäärää. Oletuksena rajapinta käyttää sivutusta (pagination), jolloin yhdelle sivulla kohteita palautuu vain 10000 kerrallaan, mutta sivujen määrää ei ole rajattu. Page-parametrilla voit määrittää, miltä sivulta haluat dataa jos havaintoja on enemmän kuin yhden sivun, eli 10000 havainnon verran.
Yleensä nopein tapa tarkistaa data on kirjoittaa kysely suoraan verkkoselaimeen. Tällöin dataa voi tarkastella GeoJSON- tai HTML-muodossa riippuen f-parametrista. Muussa käytössä rajapinnan voi linkittää suoraan paikkatietosovelluksiin (esim. QGIS & ArcGIS) tai dataa voi hakea mm. komentorivin tai ohjelmointikielten avulla.
Esimerkkikyselyjä rajanpintaan
Rajapinnan peruskäyttöön paikkatieto-ohjelmistoissa riittää vain osoite https://geoapi.laji.fi/, mutta edistyneempään käyttöön on alla esimerkkejä.
Listaa kaikki aineistot:
http://geoapi.laji.fi/collectionsYleiskatsaus aineistoon:
https://geoapi.laji.fi/collections/pohjois_savo_pointsNäytä aineiston sarakkeet (joiden perusteella rajapinnan tuloksia voi rajata)
https://geoapi.laji.fi/collections/pohjois_savo_points/queryablesSelaa havaintoja selainnäkymässä
https://geoapi.laji.fi/collections/pohjois_savo_points/itemsEsimerkki rajapinnan sivujen käytöstä. Tässä esimerkissä skipataan ensimmäiset 40 havaintoa ja rajataan hakutulos 20 havaintoon.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?offset=40&limit=20Lataa tulokset Comma Separated Value -taulukkoformaatissa (CSV). Tämä on yhteensopiva mm. Excelin kanssa.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?f=csvRajaa hakutuloksia maantieteellisestä bbox-parametrilla. Huom. oletuksena rajapinta pyytää WGS84-koordinaatteja. (Vinkki: koordinaatteja tähän tarkoitukseen saa helposti mm. QGIS-ohjelmistosta tai esimerkiksi http://bboxfinder.com/ sivustolta.)
https://geoapi.laji.fi/collections/pohjois_savo_points/items?bbox=27.610016,62.895687,27.629242,62.906087&limit=1000Rajaa hakutuloksia maantieteellisesti käyttämällä ETRS-TM35FIN -koordinaattijärjestelmää.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?bbox=535839.3305,6971988.3231,536460.5330,6972763.5737&limit=1000&bbox-crs=https://www.opengis.net/def/crs/EPSG/0/3067Etsi kaikki liito-oravat Siilinjärveltä.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?Suomenkielinen_nimi=liito-orava&Kunta=Siilinj%C3%A4rviRajaa hakutuloksia päivämäärän perusteella.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?datetime=2024-04-10T14:11:00ZNäytä ensimmäiset 100 hakutulosta ja lajittele ne sarakkeen ’Alkuperainen_nimi’ perusteella öökkösjärjestykseen, sillä ennen sarakkeen nimeä on pieni miinusmerkki.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?limit=100&sortby=-Alkuperainen_nimiHae havaintoja ETRS-TM35-FIN -koordinaattijärjestelmässä.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?crs=https://www.opengis.net/def/crs/EPSG/0/3067Hae tietty havaintoa sen havaintoerän tunnisteen perusteella.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?Havaintoeran_tunniste=http://tun.fi/HR.3691/OBS747597086Hae dataa useammasta aineistosta (eläinryhmästä) samaan aikaan. Ei vielä tuettu 8.7.2024.
http://geoapi.laji.fi/collections/search?collections=pohjois_savo_points,etela_savo_polygons&limit=1Edistyneet CQL-kyselyt:
Paikkatieto-ohjelmissa näille kyselyille on omat työkalunsa, joten peruskäytössä CQL-kyselyjen muodostamista URL:in sekaan ei tarvitse osata. Tässä kuitenkin muutamia esimerkkejä.
Etsi kaikki havainnot aineistosta ’pohjois_savo_points’, joiden nimessä on sana ’haukka’. Kyselyssä filter-lang -parametri määrittää, että nyt halutaan käyttää monimutkaisempaa CQL-kyselykieltä (Common Query Language). Filterillä ILIKE haetaan kaikki arvot, joiden kentässä on merkkijono ’haukka’. Merkintä ’%20’ kuvastaa välilyöntiä ja ’%27’ puolestaan heittomerkkiä. Yksittäinen prosenttimerkki ’%’ sanan haukka molemmin puolin kuvaa mitä tahansa merkkejä, joihin annettu merkkijono voi yhdistyä. Tällöin nimi voi olla esimerkiksi nuolihaukka tai vaikka abchaukkaabc.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?filter-lang=cql-text&filter=Alkuperainen_nimi%20ILIKE%20%27%haukka%%27Etsi kaikki havainnot aineistosta ’pohjois_savo_points’, joiden nimessä ei ole sanaa haukka. Huomaa lisäparametri ’NOT’.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?f=html&filter-lang=cql-text&filter=Alkuperainen_nimi%20NOT%20ILIKE%20%27%haukka%%27Etsi ensimmäiset 200 lintua, joiden alkuperäinen nimi on joko ”merikotka” tai ”kuikka”.
https://geoapi.laji.fi/collections/pohjois_savo_points/items?f=html&limit=200&filter-lang=cql-text&filter=Alkuperainen_nimi%20IN%20(%27merikotka%27,%27kuikka%27)Lisää esimerkkejä CQL-rajauksista löydät englanniksi mm. pygeoapin dokumentaatiosta.
Lisäohjeet
Konkreettisia esimerkkejä rajapinnan käytöstä QGIS-paikkatieto-ohjelmistossa tai Python- tai R-ohjelmointikielillä ”Aineistojen käyttö OGC API -rajapinnan kautta” -sivulla.
Sarakkeiden kuvaukset ja nimet löydät täältä.