api-juhend.pdf

Type: Document | Status: ready
← All sources

1

Statistika andmebaasi API API võimaldab statistika andmebaasi andmeid masinloetaval kujul kasutada ja uuendada teistes rakendust es. Osa statistika andmebaasi puudutavast informatsioonist on API vahendusel saadaval GET-päringutega, kuid andmetabelites asuvaid andmeid saab pärida vaid POST-päringutega. POST-päringu sisus on JSON-vormingus kirjeldatud, millist osa tabeli andmetest soovitakse ja millises vormingus vastust soovitakse. Järgnevalt on näidispäringute abil kirjeldatud, kuidas API vahendusel informatsiooni küsida. Näidispäringud on eestikeelse andmebaasi kohta. Ingliskeelseteks päringuteks tuleb aadressis sisalduv keeletunnus et asendada tunnusega en . API kaudu kättesaadavad andmebaasid GET-päringu URL: https://andmed.stat.ee/api/v1/et
Päringu URL määrab vastuse keele. Vastuses on JSON-vormingus loetelu ühe või mitme andmebaasi tunnuse (dbid ) ja nimetusega ( text ). Andmebaasi sisujaotused ja andmetabelid GET-päringu URL: https://andmed.stat.ee/api/v1/et/stat https://andmed.stat.ee/api/v1/et/stat/majandus https://andmed.stat.ee/api/v1/et/stat/majandus/hinnad https://andmed.stat.ee/api/v1/et/statsql
https://andmed.stat.ee/api/v1/et/statsql/majandus
https://andmed.stat.ee/api/v1/et/statsql/majandus/valiskaubandus/kaupade_vk
Päringu URL määrab keele, andmebaasi ja sisujaotuse. Vastuses on JSON-vormingus loetelu selle taseme all olevatest alajaotustest ja andmetabelitest. Iga loetelu elemendi kohta on esitatud tunnus (id ), tüüp (type ) ja nimetus ( text ). Tüüp l tähistab sisujaotust ( level ), tüüp t tähistab andmetabelit ( table ). Andmetabelite korral on vastuses esitatud ka andmete viimase muutmise kuupäev ja kellaaeg (updated ).

2

Andmetabeli kirjeldus GET-päringu URL: https://andmed.stat.ee/api/v1/et/stat/IA001 https://andmed.stat.ee/api/v1/et/statsql/VKK32
Päringu URL määrab keele, andmebaasi ja andmetabeli. Vastuses on JSON-vormingus loetelu tabeli nimetuse ( title ) ja muutujate ( variables ) andmetega. Iga muutuja kohta on kirjeldatud kood ( code ), nimetus ( text ), väärtuste koodid ( values ) ja väärtuste nimetused (valueTexts ). Kui tegemist on aegrea perioode sisaldava muutujaga, on määratud time: true . Kui tegemist on elimineeritava muutujaga, on määratud elimination: true . Elimineerimine tähendab võimalust, et selle muutuja väärtust ei pea tingimata määrama.

3

Andmed andmetabelist Näide 1 POST-päringu URL: https://andmed.stat.ee/api/v1/et/stat/IA001 Päringu URL määrab keele, andmebaasi ja andmetabeli. POST-päringu sisu JSON-vormingus: { "query": [ { "code": "Kaubagrupp", "selection": { "filter": "item", "values": [ "1" ] } } ], "response": { "format": "json-stat2" } } Näide 2 POST-päringu URL: https://andmed.stat.ee/api/v1/et/statsql/VKK32 Päringu URL määrab keele, andmebaasi ja andmetabeli. POST-päringu sisu JSON-vormingus: { "query": [ { "code": "PART_COUNTRY", "selection": { "filter": "item", "values": [ "TOTAL" ] } }, { "code": "ContentsCode", "selection": { "filter": "item", "values": [ "TRD_VAL" ] } } ], "response": { "format": "json-stat2" } }

POST-päringu sisus olev objekt query määrab, millistele andmetabeli muutujate väärtustele peavad vastuses sisalduvad andmed vastama. Muutuja kohta tuleb määrata kood (code ) ja väärtuste valimise ( selection ) filter ( filter ) ning valitavad väärtused (values ). Filter määrab, kuidas valitavad väärtused on antud. Toetatud filtrid on: item – sisaldab parameetris values kõiki soovitud väärtusi all – sisaldab parameetris values valikut wildcard
Näiteks „01*“ tähendab kõiki 01-ga algavaid väärtusi, "*" tähendab kõiki väärtusi. top – sisaldab parameetris values arvu, mis määrab, mitu esimest väärtust valitakse Kui muutuja on ajamuutuja, valitakse määratud arv viimaseid perioode. Kui mõne muutuja kohta ei ole midagi määratud, valitakse väärtused automaatselt järgmiste reeglite alusel.

  1. Kui muutuja on elimineeritav, valitakse muutujas t elimineerimise väärtus (tavaliselt kokku-väärtus).
  2. Kui muutuja ei ole elimineeritav, valitakse kõi k selle muutuja väärtused. 4

POST-päringu sisus olev objekt response ei ole kohustuslik, aga see on vajalik juhul, kui soovitakse kasutada vaikevormingust (json-stat2) erinevat vastuse vormingut. Valida saab järgmiste vastuse vormingute vahel:

  1. csv
  2. csv2
  3. csv3
  4. json
  5. json-stat
  6. json-stat2 (vaikimisi)
  7. px
  8. sdmx
  9. xlsx Vastuse sisu ja struktuur olenevad valitud vastuse vormingust. Otsing GET-päringu URL: https://andmed.stat.ee/api/v1/et/stat?query=hinnaindeks https://andmed.stat.ee/api/v1/et/stat?query=hinnaindeks* https://andmed.stat.ee/api/v1/et/statsql?query=bilanss https://andmed.stat.ee/api/v1/et/stat?query=hinnaindeks%20tegevusala https://andmed.stat.ee/api/v1/et/stat?query=t%C3%B6%C3%B6tuse%20m%C3%A4%C3%A4r https://andmed.stat.ee/api/v1/et/statsql?query=v%C3%A4%C3%A4rtus Päringu URL määrab keele, andmebaasi ja otsisõna(d). Otsisõnad peavad olema URLi sobivaks kodeeritud, et täpitähed jms toimiksid. Vastuses on JSON-vormingus otsingutulemuste loetelu. Vaikimisi otsitakse otsisõnale täpset vastet. Lisades otsisõna lõppu tärni, saab otsida sõnade algusest. Mitme otsisõna korral annab päring tulemuseks vastused, mis sisaldavad kõiki otsisõnu ( AND otsing). Otsingutulemuste loetelu iga elemendi kohta on esitatud tunnus ( id ), sisujaotus (path ), pealkiri ( title ), otsinguskoor (score ) ja andmete viimase muutmise kuupäev ja kellaaeg (published ). API kasutamise piirangud API tekitatud koormuse tõttu on seadistatud kasutamise piirangud selle kohta, kui palju andmeväärtusi ühe päringuga küsida saab ning kui palju päringuid ühelt ja samalt IP-aadressilt kindlas ajaühikus lubatakse. Päringute arvu piirangu ületamisel annab päring vastuse HTTP koodiga 429 Too Many Requests . Kehtivate piirangute info on kättesaadav aadressil https://andmed.stat.ee/api/v1/et?config.