Kehittäjille

API

Sivuston tiedot ovat vapaasti käytettävissä myös koneluettavana. Sama data kuin sivuilla, samoista lähteistä ja samoilla tarkistuspäivillä.

Lyhyesti

Sivuston koko tietosisältö on saatavana koneluettavana JSON-muodossa osoitteesta /api/v1/. Ei avainta, ei rekisteröitymistä, ei käyttörajaa. Käyttö on sallittua myös kaupallisesti, kun lähde mainitaan (CC BY 4.0).

Päätepisteet

Osoite	Sisältö	Laajuus	Koko
`/api/v1/kalalajit.json`	Kaikki kalalajit: tuntomerkit, säädökset ja ennätykset	53 riviä	61.1 kt
`/api/v1/saannot.json`	Pyyntimitat ja rauhoitusajat lajeittain	53 riviä	17.4 kt
`/api/v1/kalavedet.json`	Kalavesialueet kalakantatietoineen	63 riviä	69.5 kt
`/api/v1/luvat.json`	Kalastuslupien hinnat lupakaupoista	27 riviä	7.0 kt
`/api/v1/tilastot.json`	Luken saalistilastot lajeittain	21 riviä	27.3 kt
`/api/v1/koekalastus.json`	Koekalastushavainnot (arat lajit karkeistettu)	35 riviä	16.7 kt
`/api/v1/jarvet.json`	Suomen järvet: sijainti, pinta-ala ja syvyydet	29 584 riviä	2961.2 kt

/api/v1/index.json luettelee samat päätepisteet koneluettavassa muodossa — sovelluksen ei tarvitse kovakoodata listaa.

Miten sitä käytetään

Jokainen päätepiste on tavallinen JSON-tiedosto, jonka saa haettua millä tahansa HTTP-kirjastolla. Selainsovellukset voivat hakea suoraan: CORS on sallittu kaikille alkuperille.

curl https://suomenkalat.fi/api/v1/saannot.json

Vastaus on aina samanmuotoinen: ensin metatiedot (kuvaus, lisenssi, lahteet, tarkistettu) ja viimeisenä data. Näin sovellus voi näyttää lähteen ja tarkistuspäivän käyttäjälle ilman että tietoja tarvitsee etsiä muualta.

Lupaus rakenteen pysyvyydestä

Osoitteen /api/v1/ kenttiä ei poisteta eikä nimetä uudelleen. Uusia kenttiä voi tulla lisää, ja se ei riko lukijaa, joka jättää tuntemattomat kentät huomiotta. Jos rakennetta joskus joudutaan muuttamaan rikkovasti, syntyy /api/v2/ ja tämä versio jää voimaan.

Data päivittyy silloin kun sivustokin: lupahinnat tarkistetaan koneellisesti viikoittain, säädökset ja kalavesitiedot käsin lähteitä vasten. Jokaisessa vastauksessa on tarkistettu-päivä, jolloin sovellus voi kertoa käyttäjälle tiedon iän.

Ehdot

Lisenssi CC BY 4.0: saa käyttää, muokata ja jakaa myös kaupallisesti, kun lähteeksi mainitaan Suomenkalat.fi.
Alkuperäislähteet on säilytettävä. Osa aineistosta on peräisin viranomaisilta (SYKE, Luonnonvarakeskus) omilla lisensseillään. Ne on merkitty jokaisen vastauksen lahteet-kenttään, ja merkinnän on kuljettava mukana.
Ei käyttörajaa, mutta tiedostot ovat staattisia ja välimuistitettuja: hae kukin päätepiste kerran ja säilytä se, älä kysele samaa tiedostoa toistuvasti.
Säädöstiedot ovat valtakunnallisia vähimmäisvaatimuksia. Jos rakennat sovellusta, joka kertoo käyttäjälle saako kalan ottaa, näytä myös kehotus tarkistaa alueelliset rajoitukset osoitteesta kalastusrajoitus.fi. Alueelliset säännöt ovat usein tiukempia kuin valtakunnalliset.

Arkojen lajien suojaus

Taimenen, lohen, nieriän, harjuksen ja jokihelmisimpukan havaintopaikat on karkeistettu vesistötasolle myös API:ssa — koordinaatit yhden desimaalin tarkkuudella ja koskien nimet korvattuna joen nimellä. Tunnistat ne sijainti_karkeistettu-kentästä.

Tämä on tarkoituksellinen rajoitus, ei puute aineistossa: tarkkojen kutupaikkojen julkaiseminen vahingoittaisi kantoja. Älä yritä täydentää niitä muista lähteistä sovellukseesi.

Puuttuuko jotain?

Jos tarvitset kentän tai päätepisteen, jota ei ole, kerro siitä — osoite on info@rapusaari.com. Sivuston data on laajempaa kuin tässä julkaistu osa, ja rajaus on tehty sen mukaan mikä on valmiiksi tarkistettua.