Avoin: https://ogcapi.laji.fi/
Viranomaiset: https://ogcapi.laji.fi/virva
Yllä video, joka näyttää lyhyesti rajapinnan perustoiminnallisuudet ja yhdistämisen QGIS-ohjelmistoon. Lisää tietoa rajapinnan ja QGIS:n yhteentoimivuudesta täältä.
HUOM: Rajapinnan osoite on https://ogcapi.laji.fi vuodesta 2025 alkaen. Lisäksi rajapinnan yhteyteen avattiin myös viranomaisille tunnistautumista vaativa osio (https://ogcapi.laji.fi/virva) karkeistamattomalle datalle.
Mikä on OGC API Features?
Osoitteen ogcapi.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. Niitä voi esimerkiksi käyttää suoraan selaimessa.
Kyselyjen muotoilu:
Huom! Kyselyt muotoillaan hieman eritavalla paikkatieto-ohjelmistoihin (esim. QGIS). Alla esimerkkejä siitä, miten niitä käytetään ohjelmallisesti / selaimessa.
Huom! All Data as Center Points -aineistoon kyselyiden muodostominen on hiukan erilaista, sillä kyseisessä aineistoissa data haetaan eri tietokannasta. Katso esimerkkejä alempaa.
https://ogcapi.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.
https://ogcapi.laji.fi/collections listaa kaikki rajapinnan aineistot (collections).
https://ogcapi.laji.fi/collections/satakunta_points näyttää tietoja ”satakunta_points” -nimisestä aineistosta.
https://ogcapi.laji.fi/collections/satakunta_points/items näyttää ”satakunta_points” -nimisen aineiston havainnot.
https://ogcapi.laji.fi/collections/satakunta_points/items?Elioryhma=Linnut näyttää kaikki lintuhavainnot aineistosta ”satakunta_points”.
https://ogcapi.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. offset-parametrilla voit määrittää, kuinka monennesta havainnosta haluat aloittaa 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://ogcapi.laji.fi/, mutta edistyneempään käyttöön on alla esimerkkejä.
Listaa kaikki aineistot:
http://ogcapi.laji.fi/collectionsYleiskatsaus aineistoon:
https://ogcapi.laji.fi/collections/pohjois_savo_pointsNäytä aineiston sarakkeet (joiden perusteella rajapinnan tuloksia voi rajata)
https://ogcapi.laji.fi/collections/pohjois_savo_points/queryablesSelaa havaintoja selainnäkymässä
https://ogcapi.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://ogcapi.laji.fi/collections/pohjois_savo_points/items?offset=40&limit=20Lataa tulokset Comma Separated Value -taulukkoformaatissa (CSV). Tällöin data on yhteensopiva mm. Excelin kanssa.
https://ogcapi.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://ogcapi.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än bounding boxia.
https://ogcapi.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://ogcapi.laji.fi/collections/pohjois_savo_points/items?Suomenkielinen_nimi=liito-orava&Kunta=Siilinj%C3%A4rviRajaa hakutuloksia päivämäärän perusteella.
https://ogcapi.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://ogcapi.laji.fi/collections/pohjois_savo_points/items?limit=100&sortby=-Alkuperainen_nimiHae havaintoja ETRS-TM35-FIN -koordinaattijärjestelmässä.
https://ogcapi.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://ogcapi.laji.fi/collections/pohjois_savo_points/items?Havaintoeran_tunniste=http://tun.fi/HR.3691/OBS747597086Edistyneet CQL-kyselyt:
CQL (Common Query Language) -kyselyillä voi laajentaa kyselyjä vielä monipuolisemmaksi, jos perus filtterit eivät riitä. Tällöin kyselyn filter-lang -parametri määrittää, että nyt halutaan käyttää monimutkaisempaa CQL-kyselykieltä.
Alla esimerkki aineistosta ’pohjois_savo_points’, josta etsitään kaikki havainnoit joiden nimessä on sana ’haukka’. 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://ogcapi.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’.
Etsi ensimmäiset 200 lintua, joiden alkuperäinen nimi on joko ”merikotka” tai ”kuikka”.
https://ogcapi.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ää yleisiä esimerkkejä CQL-rajauksista löydät englanniksi mm. pyogcapin dokumentaatiosta.
Erikoisaineisto ”All Data as Center Points” -aineisto
Koska virva-rajatuissa aineistoissa on vain reilu 6 miljoonaa havaintoa, tämän aineiston kautta on saatavilla kaikki laji.fi:ssä näkyvät havainnot. Tämä toimii hieman hitaammin, kuin muut aineistot, sillä se tekee lennosta suoraan rajapintakyselyn REST-rajapintaamme (https://api.laji.fi/explorer/#!/Warehouse/get_warehouse_query_unit_list) samalla muotoillen sen suomenkieliseksi ja yhteensopivaksi paikkatieto-ohjelmistoihin.
Koska Lajitietokeskuksessa on yli 50 miljoonaa havaintoa, olemme lisänneet kyselyihin ylärajan max 1 000 000 havaintoa kerrallaan. Käyttääksesi aineistoa, sinun tulee siis lisätä kyselyyn filttereitä (esim. lajin, paikan, ajan tai muun muuttujan suhteen).
Voit asettaa filttereitä hieman muita aineistoja rajatummin. Esimerkiksi ”LIKE” tai ”ILIKE” filtterit eivät tähän aineistoon toimi. Käytä sen sijaan yksinkertaisia attribuuttifilttereitä =, !=, >, >=, <=, < tai bbox, limit, offset – rajauksia. Useamman arvon samassa filtterille voi erottaa pilkuilla, jolloin rajapinta etsii osumat jomman kumman arvon kanssa.
HUOM! bbox-filtteri toimii EUREF-TM35FIN tai WGS84 -koordinaateilla.
HUOM! Voit käyttää simppeleitä attribuuttifilttereitä (esim. Suomenkielinen_nimi=tuulihaukka) tai täsmälleen samoja filttereitä, kuin REST-rajapintaankin, sillä rajapinta välittää ei-suomenkieliset filtterit sellaisenaan eteenpäin.
Sallitut rajaukset tähän aineistoon:
| Property name | Description | Type | Allowed values/range/examples |
| Havainnon_tunniste | Id | string | e.g. ’http://tun.fi/JX.337955#5’ or ‘JX.337955#5’ |
| Tieteellinen_nimi Suomenkielinen_nimi Ruotsinkielinen_nimi Englanninkielinen_nimi Alkuperainen_nimi Elioryhma | Name as text | string | e.g. ‘parus major’ OR ‘Linnut’ |
| Paikan_tarkkuus_metreina_max | Accuracy in meters | integer | e.g. ‘100’ |
| Havainnon_luotettavuus | enumeration | Use names or Finnish labels: https://laji.fi/api/warehouse/filters/recordQuality | |
| Yksilomaara_tulkittu | Minimum number of occurrences. Default 1. If 0, include negative observations. | integer | e.g. ‘10’ |
| Eliomaakunta | string | e.g. Uusimaa (U) OR Uusimaa. | |
| Aineiston_tunniste | string | e.g. HR.95 OR http://tun.fi/HR.95 | |
| Pesintapaikka | Boolean | True OR False | |
| Maarittaja | string | Alpo Turunen | |
| Elinvaihe | enumeration | Use names or Finnish labels: https://laji.fi/api/warehouse/filters/lifeStage | |
| Taksonin_tunniste | string | e.g. http://tun.fi/MX.38910 OR MX.38910 | |
| Havaintotapa | enumeration | Use names or Finnish labels: https://laji.fi/api/warehouse/filters/recordBasis | |
| sukupuoli | enumeration | Use names or Finnish labels: https://laji.fi/api/warehouse/filters/sex | |
| Havaintoeran_tunniste | string | http://tun.fi/JX.337716 OR JX.37716 | |
| Karkeistuksen_syy | Use names or Finnish labels: https://laji.fi/api/warehouse/filters/secureReason | ||
| Aika | Filter using event date. Date can be a full date or part of a date, for example 2000, 2000-06 or 2000-06-25. Time can be a range, for example 2000/2005 or 2000-01-01/2005-12-31. Relative days ”last N days” can be used: 0 is today, -1 is yesterday and so on; for example -7/0 is a range between 7 days ago and today. Multiple values are seperated by ’,’. When multiple values are given, this is an OR search. | string | e.g. 2020-01-01/2020-12-31 OR 2023-05-10 |
| Kunta | string | e.g. Helsinki | |
| Havainnoijat | string | e.g. Alpo Turunen | |
| avainsanat | string | e.g. 2 n | |
| Aineiston_laatu | enumeration | Use names or Finnish labels: https://laji.fi/api/warehouse/filters/collectionQuality | |
| Uhanalaisuusluokka | enumeration | Use ids or values: https://laji.fi/api/metadata/ranges/MX.iucnStatuses?lang=fi | |
| Sensitiivinen_laji | boolean | True OR False | |
| Valtion_maalla | boolean | True OR False | |
| Ensisijainen_biotooppi | enumeration | Use ids or values: https://laji.fi/api/metadata/ranges/MY.habitatEnum?lang=fi | |
| Hallinnollinen_asema | enumeration | Use ids or values: https://laji.fi/api/metadata/ranges/MX.adminStatusEnum?lang=fi | |
| Atlasluokka | enumeration | Use ids or values: https://laji.fi/api/metadata/ranges/MY.atlasClassEnum?lang=fi | |
| Atlaskoodi | enumeration | Use ids or values: https://laji.fi/api/metadata/ranges/MY.atlasCodeEnum?lang=fi | |
| Lataus_pvm | Filter using the date data was loaded to Data Warehouse. Format is yyyy-MM-dd or UNIX EPOCH timestamp in seconds. Returns entries loaded later or on the same date/timestamp. | string | 2025-08-28 00:00:00 OR 2025-08-28 |
Seuraavien muuttujien perusteella ei voi rajata kyselyjä ”All Data as Center Points” -aineistossa, sillä rajapinta ei toistaiseksi tue niitä:
Keruu_aloitus_pvm, Keruu_lopetus_pvm, Havainnon_lisatiedot, ETRS_TM35FIN_WKT, Sijainti, Keruutapahtuman_lisatiedot, Taksonominen_jarjestys, Maaran_yksikko, Lajiturva, geometry, Esiintyman_tila, Aineisto, Seurantapaikan_tila, Seurantapaikan_tyyppi, Vastuualue, Paikallinen_tunniste, Yhdistetty, Maara, Maarittaja, Aineiston_tunniste
Hankaluuksia?
- Jos saat virheilmoituksia QGIS:ssä, kokeile laittaa sama kysely nettiselaimen osoitekenttään. Selain näyttää virheviestit paremmin.
- Kannattaa käyttää kyselyissä ID-tunnuksia arvojen sijaan, sillä ne eivät sisällä erikoismerkkejä.
- Ongelmatilanteissa ota yhteyttä helpdesk @ laji.fi.
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ä.