NB! Neljapäeval 05.12.2024 alates 14.00 toimub APIde uuuendused ja andmeteenused on maas 6-10 tundi. Teenuse katkestus võib mõjutada Tableau rakenduste tööd. Palume vabandust ebamugavuste pärast!
Üldinfo
Keskkonna ja ilma valdkonna andmeteenusete keskkond on loodud avaandmete direktiivist tulenevate väärtuslike andmestikele esitatavate nõuete täitmiseks ning sisaldab keskkonna ja ilma valdkonna andmeteenuseid. Andmeteenuste väljundvorminguks on json ja andmed on mõeldud tarbimiseks peamiselt masin-masin liidese kaudu. Keskkond on aktiivses arenduses ja täieneb jooksvalt väärtuslike andmestikega. Hetkel on valmis arendatud meteoroloogia ja hüdroloogia valdkonnas hüdroloogilise seire andmestikust tunniandmete andmeteenused ja kliimaandmestikust jaama, elemendi, kuu, ööpäeva, tunni ja 10-minuti andmeteenused. Keskkonna valdkonna andmetest on avalikustatud keskkonnaseire andmed (API täiendamisel) ja avalikustatakse Eesti looduse infosüsteemi andmed ning keskkonnakasutuse aastaaruandluse (jäätmed, välisõhk, veekasutus) andmed KOTKAS-est.
NB! Seoses jõudlusest tulenevatemahupiirangutega tuleb f_kliima päringutes kasutada päeva, tunni ja minuti päringutes filtreid nagu on allolevates näidetes. Ühe päringu mahupiirang on 20 000 rida ja kui on vaja rohkem andmeid siis tuleb kasutada pagineerimist (juhised).
Teenuse vaatamiseks internetilehitsejaga inimsõbralikus vormis on soovituslik lisada Chrome-ile laiendus JSON formatter või kasutada Mozilla Firefox-i või MS EDGE-i
OpenAPI definitsioon:
JuurURL https://keskkonnaandmed.envir.ee annab OpenAPI formaadis teenuse kirjelduse.
Kliima andmete jaoks leia sektsioonist "definitions" prefiksiga "f_kliima_" algavad teenused (nt metaandmete teenused f_kliima_element ja f_kliima_jaam_vaatlus, või perioodi pikkusega mõõtmisi väljastavad teenused f_kliima_kuu, f_kliima_paev, f_kliima_tund, f_kliima_minut)
Hüdroloogilise seire jaoks leia sektsioonist "definitions" teenus nimega "f_hydroseire".
Keskkonnaseire jaoks leia sektsioonist "definitions" teenus nimega "f_keskkonnaseire".
EELISe andmestike on palju seega tuleb enne vaadata levitusi ja valida sobib tabel.
Kliima andmeteenus
Kliimaandmestike levitused sisaldavad elemente, jaamu, kuu, päeva, tunni ja 10-minuti andmeid. Näitena: teenust f_kliima_paev võib ilma lisaargumentideta kasutada ainult metaandmeid andvaid teenusete puhul. Mõõtetulemuste andmete jaoks tuleb ALATI piirata päringut filtritega. Näiteks ajaga (küsides konkreetse aasta ja kuu andmeid).
Brauserist (aadressiribale)
|
|
Ülaltoodud näites on nõutud ("equal" abil) täpset aastat (2023), ("greater than" abil) kahte kuud aasta lõpust (11 ja 12), ("lesser than" abil) 7 päeva kuu algusest, ühte elementi (DRH08) kahes jaamas (Ruhnu ja Kihnu).
Loe lisaks: https://postgrest.org/en/stable/api.html#horizontal-filtering-rows
Curl (ja muud programeeritavad vahendid)
|
|
Arendajal (API tarbijal) võtta kasutusse HTTP päis "Accept-Profile: apijahialad" (See "apijahialad" on andmebaasi-skeem, mida läbi API avalikustataks). Kui tulevikus avalikustatakse mitut skeemi, siis pole määratud, mida API annab ja see võib olla eksitav. Tulevased konfiguratsiooni muudatused ja arendused võivad seda veelgi segada ning seega peaks tarbija selle päise abil soorituse enda suunas ära tagama). Loe lisaks: https://postgrest.org/en/stable/api.html#switching-schemas
Täiendavalt on hea kasutustava kohaselt lisada soovitud vastuse formaat (JSON) ehk header "Accept: application/json". On ka teisi formaate (csv), aga need on piiratud juhtude jaoks. Loe lisaks: https://postgrest.org/en/stable/api.html#response-format. JSONi etteandmine on meede tulevikukindluse jaoks.
Tulemus
|
|
Hüdroloogilise seire andmeteenus
Teenust f_hydroseire võib ilma lisaargumentideta kasutada ainult metaandmeid andvaid teenusete puhul. Mõõtetulemuste andmete jaoks tuleb ALATI piirata päringut filtritega. Näiteks ajaga (küsides konkreetse aasta ja kuu andmeid).
NB! Hetkel on saadaval f_hydroseire teenuses paari aasta andmed, kuid plaanis on avalikustada kõik andmed ja vastavad arendustööd on teostamisel.
Brauserist (aadressiribale)
Ülaltoodud näites on nõutud ("equal" abil) täpset aegrea nime ("WL min") ja ("greater than" ja "lesser than" abil) ajalõiku
Loe lisaks: https://postgrest.org/en/stable/api.html#horizontal-filtering-rows
Curl (ja muud programeeritavad vahendid)
|
Arendajal (API tarbijal) võtta kasutusse HTTP päis "Accept-Profile: apijahialad" (See "apijahialad" on andmebaasi-skeem, mida läbi API avalikustataks). Kui tulevikus avalikustatakse mitut skeemi, siis pole määratud, mida API annab ja see võib olla eksitav. Tulevased konfiguratsiooni muudatused ja arendused võivad seda veelgi segada ning seega peaks tarbija selle päise abil soorituse enda suunas ära tagama). Loe lisaks: https://postgrest.org/en/stable/api.html#switching-schemas
Täiendavalt on hea kasutustava kohaselt lisada soovitud vastuse formaat (JSON) ehk header "Accept: application/json". On ka teisi formaate (csv), aga need on piiratud juhtude jaoks. Loe lisaks: https://postgrest.org/en/stable/api.html#response-format. JSONi etteandmine on meede tulevikukindluse jaoks.
Tulemus
|
|
Keskkonnaseire andmeteenus
Hetkel on Keskkonnaseire andmeteenuses probleeme pagineerimisega (limit ja offset), seega tuleks andmete pärimisel kindlasti kasutada filtreid.
Teenust f_keskkonnaseire võib ilma lisaargumentideta kasutada ainult metaandmeid andvaid teenusete puhul. Mõõtetulemuste andmete jaoks tuleb ALATI piirata päringut filtritega. Näiteks seiretöö, näitaja ja ajaga (küsides konkreetse seiretöö ja kuu andmeid).
NB! Hetkel on saadaval teenuses olulisemad andmed, kuid plaanis on täiendada andmekooseisu (lisandub juurde AKP andmed + kodeeringud) ja vastavad arendustööd on teostamisel.
Brauserist (aadressiribale)
Ülaltoodud näites on nõutud ("equal" abil) täpset seiretöö koodi alusel ("seiretoo_kood") ja ("greater than or equal" ja "lesser than" abil) ajalõiku
Loe lisaks: https://postgrest.org/en/stable/api.html#horizontal-filtering-rows
Curl (ja muud programeeritavad vahendid)
Analoogselt Meteoroloogiliste ja Hüdroloogiliste andmetega.
EELISe andmeteenus
Hetkel on EELISe infosüsteemi andmestike API-de loomine aktiivses arenduses, seega võib esineda andmestike ja levituste kirjelduses ebatäpsusi. Ehk võib olla rohkem avalike levitusi ja mõned avalikud levitused ei pruugi olla ajutiselt kättesaadavad.
EELISe infosüsteemi APIsid on ca 250 ja välja on toodud kahe API näited (f_rahvalad ja f_rahvalad_dok). Mõlemas tabelis on alla 20 000 rea seega pole otseselt vaja pagineerimist kasutada ja ilma filtriteta saab andmed alla laadida täies mahus, kuid see on soovituslik (Loe lisaks: https://postgrest.org/en/stable/api.html#horizontal-filtering-rows).
EELISe andmestike API-d on üles ehitatud selliselt, et on põhitabel (f_rahvalad) ja sellega seostuvad kirjed on seosetabelites (f_rahvalad_dok, f_rahvalad_invmojutegur jne). Reeglina soovitakse pärida põhitabelis mingi objekt/kirje ja sellega seostuvad kirjed seosetabelist aga saab ka küsida täies mahus ainult seosetabelit ja põhitabelit.
Brauserist (aadressiribale)
Näites on päritud rahvusvaheliste alade põhitabelist täpset objekti ("equal" abil) KKR koodi alusel (Kurese loodusala kirje).
|
https://keskkonnaandmed.envir.ee/f_rahvalad?kkr_kood=eq.RAH0000556 |
Põhitabeli kirjet koos seosetabeli kirjetega saab pärida nii:
|
https://keskkonnaandmed.envir.ee/f_rahvalad?select=*,dok:f_rahvalad_dok(*)&kkr_kood=eq.RAH0000556 |
Lisaks selles levituse tabelis kahte erinevat tüüpi dokumendid, seega tuleks kasutada järgmisi päringuid, et leida huvipakkuvad dokumendid
Rahvusvahelise alaga seotud õigusaktid
|
https://keskkonnaandmed.envir.ee/f_rahvalad?select=*,dok:f_rahvalad_dok(*)&kkr_kood=eq.RAH0000556&dok.on_linnuala_kohta=eq.0 |
Linnualaks (SPA) määramise siseriiklik õiguslik alus
Curl (ja muud programeeritavad vahendid)
Analoogselt Meteoroloogiliste, Hüdroloogiliste ja teiste andmetega.
Lisainfo
Kõik muud võimalused (pagineerimine, valikulised veerud) on kirjas PostgREST manualis (https://postgrest.org/en/stable/api.html).
Andmeid ei saa API kaudu muuta ega kustutada (raamistik võimaldaks ja näited on juhendis toodud, aga süsteemselt määratud õigused ei luba).
Juhistes on toodud ka pöördumise autentimise võimalus, aga antud API on avalik ja JWT kasutamine pole vajalik.