Lintuatlas.fi

Lajitietokeskuksen yleinen rajapinta

Lähes kaikki tieto, mikä on näkyvissä Laji.fi-portaalissa on saatavilla rajapinnan kautta.

Rajapinnan käyttö

Rajapinnan käyttöön tarvitaan oma access token. Tokenin voi hakea itse näiden ohjeiden avulla.

Skeema kertoo mitä eri parametrit ja niiden arvot tarkoittavat. Se on selattavissa osoitteessa https://schema.laji.fi/

Tunnisteiden käyttö

Kaikilla Lajitietokeskuksen tietueilla on pysyvä HTTP-URI -tunniste. Esim. laulujoutsenen tunniste on http://tun.fi/MX.26280 (lyhennettynä koodina MX.26280), Tiiran atlashavaintokokoelman tunniste on http://tun.fi/HR.4412 ja Suomen valtion tunniste on http://tun.fi/ML.206.

Tunnisteiden avulla voi hakea tietoa tunnisteen kohteesta pyytämällä vastaus JSON tai XML-muodossa content negotiationin avulla, tai antamalla formaatti parametrina, esim. http://tun.fi/MX.26280?format=JSON&lang=fi

Endpointit

Rajapinnan tekninen dokumentaatio kertoo miten erilaisia endpointeja käytetään.

Rajapintaa käytettäessä kannattaa antaa parametriksi cache=true. Tämä nopeuttaa hakuja (kaikille käyttäjille) koska se palauttaa enintään 30 minuuttia vanhan tiedon välimuistista.

Endpointeista hyödyllisimmät Lintuatlaksen kannalta ovat:

/taxon

Tämän avulla voi hakea tietoja lajeista ja muista taksoneista. Lintujen (Aves) taksonikoodi on MX.37580.

Atlaksen tulossivustolla näkyvien lajien luettelon saa atlaksen rajapinnan kautta.

Esimerkki: Linnut-taksonin tiedot:

https://api.laji.fi/v0/taxa/MX.37580?lang=fi&langFallback=true&maxLevel=0&includeHidden=false&includeMedia=false&includeDescriptions=false&includeRedListEvaluations=false&sortOrder=taxonomic&access_token=(OMA TOKEN TÄHÄN)

/warehouse

Warehouse-endpointista voi hakea tietoja yksittäisistä havainnoista ja niihin liittyviä tilastoja.

Rajapinnassa document tarkoittaa havaintoerää, gathering documentin sisällä olevaa havaintopaikkaa (1…n kpl, tavallisesti 1) ja unit havaintoa (0…n kpl).

Oleellisia parametreja ovat ainakin:

  • taxonId=MX.37580 (taksoni: linnut)
  • countryId=ML.206 (maa: Suomi)
  • time=2022%2F2025 (aika: atlaksen kesto)
  • atlasClass (pesimävarmuusluokka: sallitut arvot)
  • atlasCode (pesimävarmuusindeksi, sallitut arvot)
  • ykj10kmCenter=668%3A338 (YKJ-ruudun koordinaatit, tässä esimerkissä 668:338)
  • birdAssociationAreaId=ML.1088 (lintuyhdistyksen tunniste, sallitut arvot)
  • coordinateAccuracyMax=10000 (koordinaattien tarkkuus)
  • recordQuality=NEUTRAL,COMMUNITY_VERIFIED,EXPERT_VERIFIED (havaintojen laatu: epävarmat ja virheelliset jätetään pois)
  • completeListTaxonId=MX.37580&completeListType=MY.completeListTypeCompleteWithBreedingStatus%2CMY.completeListTypeComplete (täydelliset lajilistat)
  • pageSize=25&page=1 (datan sivutus)

Sen atlasruudun (10 km yhtenäiskoordinaattiruudun), jossa havainto on, saa selville muuttujista gathering.conversions.ykj10kmCenter.lat ja gathering.conversions.ykj10kmCenter.lon. Havainnon sijainnin keskipiste määrittelee mihin ruutuun havainto lasketaan atlaksessa kuuluvan.

/warehouse/query/unit/list

Tämä endpoint antaa luettelon havainnoista.

Esimerkki: Kaikki atlashavainnot:

https://api.laji.fi/v0/warehouse/query/unit/list?pageSize=100&page=1&cache=true&taxonId=MX.37580&useIdentificationAnnotations=true&includeSubTaxa=true&includeNonValidTaxa=true&countryId=ML.206&time=2022%2F2025&individualCountMin=1&qualityIssues=NO_ISSUES&atlasClass=MY.atlasClassEnumB%2CMY.atlasClassEnumC%2CMY.atlasClassEnumD&recordQuality=NEUTRAL,COMMUNITY_VERIFIED,EXPERT_VERIFIED&access_token=(OMA TOKEN TÄHÄN)

/warehouse/query/unit/aggregate

Tämän avulla havaintoja voi aggregoida, eli saada niistä summia.

Esimerkki: Varmat pesinnät viimeisen kahden viikon ajalta, aggregoituna lajin mukaan, 25 yleisintä lajia:

https://api.laji.fi/v0/warehouse/query/unit/aggregate?aggregateBy=unit.linkings.originalTaxon.speciesNameFinnish&onlyCount=true&taxonCounts=false&pairCounts=false&atlasCounts=false&excludeNulls=true&pessimisticDateRangeHandling=false&pageSize=25&page=1&cache=true&taxonId=MX.37580&useIdentificationAnnotations=true&includeSubTaxa=true&includeNonValidTaxa=true&countryId=ML.206&yearMonth=2022%2F2025&individualCountMin=1&qualityIssues=NO_ISSUES&time=-14%2F0&atlasClass=MY.atlasClassEnumD&recordQuality=NEUTRAL,COMMUNITY_VERIFIED,EXPERT_VERIFIED&access_token=(OMA TOKEN TÄHÄN)

Esimerkki: Täydelliset lajilistat, aggregoituna havainnoijan mukaan, 30 aktiivisinta havainnoijaa:

https://api.laji.fi/v0/warehouse/query/document/aggregate?aggregateBy=document.editorUserIds&onlyCount=true&excludeNulls=true&pessimisticDateRangeHandling=false&pageSize=30&page=1&cache=true&qualityIssues=NO_ISSUES&completeListTaxonId=MX.37580&completeListType=MY.completeListTypeCompleteWithBreedingStatus%2CMY.completeListTypeComplete&access_token=(OMA TOKEN TÄHÄN)

Siirry sivun alkuun