Avaandmete kasutamine
- Andmeteenuste kasutamine
- Metaandmed
- Rest API
- Odata API
- Andmete varieeruvus
- Versiooniuuendused
- Odata andmete kasutamine Microsoft Excelis
Andmeteenuste kasutamine
Andmestikud on koos metaandmetega kättesaadavad andmeteenustena Rest API ja Odata API vahendusel. Rest API, mille tehnoloogiaks on PostgREST, on varustatud standardiseeritud OpenAPI kirjeldusega läbi Swaggeri kasutajaliidese.
Rest API on eeskätt mõeldud tarkvaraarendajatele, kes soovivad andmeid töödelda enda arendatud vahendite abil. Spetsiifiliste API päringute tegemisel on abiks PostgREST dokumentatsioon. Samuti sobib Odata API masinliidestega andmete tarbimiseks.
Rest API päringute puhul on piiratud päringuga tagastatavate andmeridade arv. Seega on soovitav pärida andmeid osade kaupa ehk jaotada lehekülgedeks. Juhised selleks saab PostgREST dokumentatsioonist.
Odata API kaudu on andmestikud laetavad otse analüüsitarkvarasse, kus on lihtne andmeid filtreerida, sorteerida ja laadida soovi korral ainult alamhulka andmetest. Odata API vastab OData v4 standardile.
CSV formaadis faili alla laadimisel tuleb samuti silmas pidada, et faili kirjutatavate andmeridade arv on piiratud. CSV fail luuakse Rest API päringu tulemusel ja sellesse kirjutatakse värskeimatest andmetest alustades hetkel kehtivad andmekirjed kuni piirangu saabumiseni (päringu täpsustus on ?order=StatisticsDate.desc&Valid=eq.true).
Metaandmed
Metaandmed on API-de kaudu kättesaadavad samamoodi nagu andmestikud - eraldi metadata andmeteenustena. Andmeteenuste metadata ja metadata_odata erinevus seisneb kirjelduse (description) välja tüübis: metadata teenuses on see struktureeritud JSON-objekt, metadata_odata teenuses aga lihttekst (varchar).
Andmestikud on avaandmete valdkondade kaupa jagatud skeemidesse. Skeemi nimetus on valdkonna inglisekeelne nimetus (näiteks covid19, flu). Metadata andmeteenused on kättesaadavad kõikidest skeemidest.
Metadata andmeteenuse kirjeldus on toodud allolevas tabelis.
| Andmeväli | Kirjeldus | Näide |
|---|---|---|
| schemaname | Avaandmete valdkonna nimi, näiteks COVID-19 või gripp. | covid19, flu |
| table | Andmestiku inglisekeelne tehniline nimi ehk API-de kaudu pakutava andmeteenuse nimi. Identsifitseerib andmestiku andmekoosseisu. | opendata_flu_vaccination_location_agegroup |
| column | Andmevälja nimetus, mille kohta kirjeldus antakse. | StatisticsDate |
| type | Viitab, kas kirjeldus antakse andmestiku (table) või andmevälja (column) kohta. | table, column |
| datatype | Andmevälja andmetüüp. | bigint, character varying(100) |
| description | Andmekirjeldus eesti ja inglise keeles JSON vormingus. Eestikeelne kirjeldus on tähistatud lühendiga et ja inglisekeelne kirjeldus lühendiga en. | {"et": "Statistika kuupäev, mis leitakse immuniseerimise kuupäeva järgi.","en": "Statistics date found by immunization date."} |
Andmestiku andmekoosseisu identifitseerib andmeteenuse tehniline inglisekeelne nimetus, mis on leitav andmeväljalt table. Selle välja järgi andmeid filtreerides saab kätte huvipakkuva andmestiku kirjelduse koos andmekoosseisu kirjeldusega.
Rest API
Skeemid
Rest API päringu süntaks soovitud skeemi on järgmine:
https://rest-avaandmed.tehik.ee/skeemi-inglisekeelne-nimetusNäited:
https://rest-avaandmed.tehik.ee/covid19/
https://rest-avaandmed.tehik.ee/flu/Nginx pöördproxy teisendab PostgREST API päringu URL-i selle osa, mis on pärast kaldkriipsu, skeemi "Accept-Profile" päiseks. Curl näitel teisendatakse https://rest-avaandmed.tehik.ee/flu/ järgmiselt:
curl "https://rest-avaandmed.tehik.ee" -H "Accept-Profile: flu"PostgREST ütleb, kui skeemi ei eksisteeri ja annab info tagasi, millised skeemid on lubatud.
Päring skeemi, mida ei ole olemas:
https://rest-avaandmed.tehik.ee/test/Vastus:
{"code":"PGRST106","details":null,"hint":null,"message":"The schema must be one of the following: covid19, flu"}Lubatud päringu tüübid
PostgRESTis on lubatud ainult GET tüüpi päringud.
Failide väljastamine
Nginx-s on reegel, mis teisendab andmestiku nime lõpus .csv ja .json PostgRESTi päringu päiseks.
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_hospitalization.json
teeb sedasama mis
curl --location 'https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_hospitalization' --header 'Accept: application/json' --header 'Content-Type: application/json'https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_hospitalization.csv
teeb sedasama mis
curl --location 'https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_hospitalization' --header 'Accept: text/csv' --header 'Content-Type: text/csv'Pagineerimine ehk lehekülgedeks jaotamine
Andmestiku andmekirjete ehk ridade arvu teada saamiseks tuleb teha päring järgmise süntaksiga (andmestiku opendata_covid19_vaccination_season_location_agegroup_gender näitel):
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?select=countPostgRESTi puhul on korraga päritavate andmete hulk piiratud. Piirang sõltub kasvavast andmemahust ja kasutajate arvust ja võib aja jooksul väiksemaks muutuda, mistõttu ei nimeta me siin konkreetset ridade arvu.
Andmestiku osade kaupa pärimiseks on kaks võimalust:
- headeritega või
- querystring parameetritega.
Näide headeriga päringust, mis tagastab esimesed 6 kirjet:
curl --location 'https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender' --header 'range: 0-5' --header 'Range-Unit: items'Näide querystring parameetriga päringust, mis tagastab alates 6. kirjest 5 kirjet:
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?limit=5&offset=5Täpsemalt saab pagineerimise kohta lugeda PostgREST dokumentatsioonist.
Filtreerimine
Toome mõned näited päringute kohta teatud ajavahemiku ja tõeväärtuse leidmiseks. Täpsem info on leitavad PostgREST dokumentatsioonist.
Näide päringu süntaksist, kui on soov saada kõiki andmekirjeid – nii kehtivaid kui ka kehtetuid – ühe kuupäeva kohta, näiteks 23.04.2025:
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?and=(StatisticsDate.gte.2024-04-23,StatisticsDate.lte.2024-04-23)Näide päringust, kui on soov saada kehtivad andmekirjed ühe kuupäeva kohta, näiteks 23.04.2025:
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?and=(StatisticsDate.gte.2024-04-23,StatisticsDate.lte.2024-04-23)&Valid=eq.trueNäide päringust, kui on soov saada kehtivad andmekirjed teatud ajavahemiku kohta alustades hiliseimast kuupäevast ja kirjutatuna CSV formaadis faili, näiteks 01.01.2025 kuni 01.04.2025:
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender.csv?and=(StatisticsDate.gte.2025-01-01,StatisticsDate.lte.2025-04-01)&order=StatisticsDate.desc&Valid=eq.trueSelle päringu tulemusena laetakse filtreeritud ja sorteeritud andmed CSV formaadis failina alla. Sama päringut saab kasutada APIs, kui eemaldada .csv.
Näide päringust kehtivate andmete kohta seisuga 23.04.2025 Hiiu maakonnas:
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?and=(StatisticsDate.gte.2024-04-23,StatisticsDate.lte.2024-04-23)&Valid=eq.true&LocationCounty=eq.Hiiu%20maakondNäide päringust kehtivate andmete kohta seisuga 23.04.2025 kõikides maakondades, va Hiiu maakonnas:
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?and=(StatisticsDate.gte.2024-04-23,StatisticsDate.lte.2024-04-23)&Valid=eq.true&LocationCounty=neq.Hiiu%20maakondSorteerimine
Näide päringu süntaksist, kui on soov järjestada päringu vastus muutmise aja järgi alustades varaseimast muudatusest (order=ModifiedAt.asc):
https://rest-avaandmed.tehik.ee/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?and=(StatisticsDate.gte.2024-04-23,StatisticsDate.lte.2024-04-23)&Valid=eq.true&order=ModifiedAt.ascTäpsemalt saab lugeda sorteerimise kohta siit.
Muud täiendavad võimalused
PostgREST võimaldab andmeväljade ümbernimetamist, pärida ainult teatud veerge ja muuta päringu vastuses andmetüüpi.
Odata API
Skeemid
Odata API päringu süntaks soovitud skeemi on järgmine:
https://odata-avaandmed.tehik.ee/odata/skeemi-inglisekeelne-nimetusNäited:
https://odata-avaandmed.tehik.ee/odata/covid19
https://odata-avaandmed.tehik.ee/odata/fluVigade korral Odata API ei hoiata ja annab lihtsalt vastuseks veakoodi 500.
Lubatud päringu tüübid
Odata APIs on lubatud ainult GET tüüpi päringud.
Pagineerimine ehk lehekülgedeks jaotamine
Andmestiku andmekirjete ehk ridade arvu teada saamiseks tuleb teha päring järgmise süntaksiga (andmestiku opendata_covid19_vaccination_season_location_agegroup_gender näitel):
https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender/$countOdata API jaotab päritavad andmed automaatselt 4096 rea kaupa lehekülgedeks. Iga päringu sisu lõpus on järgmise lehekülje link.
.nextLink": "https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?$format=json&$skiptoken=gsrgsjjoTP/8,4096Päringu näide, mis tagastab esimesed 4096 kirjet JSON formaadis:
https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?$format=jsonKui päringu lõppu mitte lisada $format=json, siis vaikimisi tagastatakse päringu vastus XML formaadis.
Filtreerimine
Odata API operaatorite kohta leiab infot Odata standardi dokumentatsioonist.
Näide päringu süntaksist, kui on soov saada kõiki andmekirjeid – nii kehtivaid kui ka kehtetuid – ühe kuupäeva kohta, näiteks 23.04.2025:
https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?$format=json&$filter=StatisticsDate%20ge%202024-04-23%20and%20StatisticsDate%20le%202024-04-23Näide päringust, kui on soov saada kehtivad andmekirjed ühe kuupäeva kohta, näiteks 23.04.2025:
https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?$format=json&$filter=StatisticsDate%20ge%202024-04-23%20and%20StatisticsDate%20le%202024-04-23%20and%20Valid%20eq%20trueNäide päringust kehtivate andmete kohta seisuga 23.04.2025 Hiiu maakonnas:
https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?$format=json&$filter=StatisticsDate%20ge%202024-04-23%20and%20StatisticsDate%20le%202024-04-23%20and%20Valid%20eq%20true%20and%20LocationCounty%20eq%20%27Hiiu%20maakond%27Näide päringust kehtivate andmete kohta seisuga 23.04.2025 kõikides maakondades, va Hiiu maakonnas:
https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?$format=json&$filter=StatisticsDate%20ge%202024-04-23%20and%20StatisticsDate%20le%202024-04-23%20and%20Valid%20eq%20true%20and%20LocationCounty%20ne%20%27Hiiu%20maakond%27Sorteerimine
Näide päringu süntaksist, kui on soov järjestada päringu vastus muutmise aja järgi alustades varaseimast muudatusest ($orderby=ModifiedAt%20asc):
https://odata-avaandmed.tehik.ee/odata/covid19/opendata_covid19_vaccination_season_location_agegroup_gender?$format=json&$filter=StatisticsDate%20ge%202024-04-23%20and%20StatisticsDate%20le%202024-04-23%20and%20Valid%20eq%20true%20&$orderby=ModifiedAt%20ascTäpsemalt saab lugeda sorteerimise kohta siit.
Muud täiendavad võimalused
Odata API täiendavad võimalused leiab siit.
Andmete varieeruvus
Avaandmed avaldatakse värskeima teadaoleva infoga. Andmed põhinevad tervishoiuteenuse osutajate poolt tervise infosüsteemi saadetud dokumentidel (saatekirja vastused, teatised jm). Tervishoiuteenuse osutajate kvaliteedikontrolli (sealhulgas andmekvaliteedi kontrolli) käigus. tuvastatud vigade korral saadetakse tervise infosüsteemi parandatud dokumendid, mispuhul võivad andmed ajas tagantjärele muutuda. Muudatused on üldjuhul väikesed.
Versiooniuuendused
Avaandmete teenused on kestvas arenduses, mistõttu võivad ajas muutuda metoodika ja andmekoosseis. Andmestike kasutamisel ja automaatsel töötlemisel tuleb tabelarvutuse puhul tähelepanu pöörata veerunimedele ja JSON vormingus andmeteenuste puhul andmevälja (column) nimetustele. Suuremate muudatuste korral andmete struktuuris luuakse vanade andmeteenuste kõrvale uued ning võimalusel jäetakse alles paralleelkasutus.
Odata andmete kasutamine Microsoft Excelis
Odata andmed on kodeeritud UTF-8 formaadis.
Andmeteenuste tarbimisel Microsoft Exceliga on soovituslik kasutada Power Query redaktorit, mis võimaldab töödelda suuremaid andmestikke ja soovi korral andmeid enne allalaadimist filtreerida:
Microsoft Exceli tavatabeli ridade arvu piirang on 1 048 576.
Power Query andmelaadimiste juures ei ole otsest ridade arvu piirangut.
Power Query Web connector võimaldab loodud Exceli failis allikandmete uuendamist nii, et tehtud aruanded, filtrid ja andmetöötlused jäävad alles.
Suuremamahulise andmeanalüüsi tarbeks saab Odata andmeid töödelda spetsiaaltarkvaraga (BI tools) nagu Microsoft Power BI, Tableau Desktop jt.
Kuidas andmestikku Microsoft Excelisse laadida?
Vali “Andmed” menüüst “Too andmed” ning avanenud valikust “Muudest allikatest” ning sealt “OData kanalist”.
Avanenud aknas “OData kanal” tuleb valida “Põhiline” ning URL lahtrisse sisestada Odata API võrguaadress, näiteks COVID-19 andmete kasutamiseks https://odata-avaandmed.tehik.ee/odata/covid19/. Seejärel vajutada “OK”.
Järgnevas aknas on näha Odata API kaudu saada olevad andmestikud, millest valida huvipakkuv. Edasi “Laadi”.
Toimub andmete laadimine ning laetud tulemus kuvatakse Excelis.
Kui andmed on sisse laetud ja soov andmestikku värskendada, siis tuleb valida “Andmed” menüüst “Värskenda kõik”.
