Eustaten APIaren gida teknikoak Eustaten APIari buruzko oinarrizko informazioa ematen du: sarbide puntuak (endpoint-ak), eskaeren egitura (GET eta POST), hizkuntza parametroak eta erantzun formatuak (JSON, CSV, XLSX). APIaren funtzionamendua ulertzeko lehen urratsa da.
Sarrera
Eustaten datu-bankua (EDB) estatistika-datuak kontsultatzeko tresna indartsu eta malgua da, eta kontsultaren emaitza xehetasun handiz pertsonalizatzeko aukera ematen du.
Oinarrizko mailan, eskuragarri dauden datu guztien artean erabiltzaileak behar dituen datu zehatzak hautatzeko aukera ematen du, neurrirako taula bat eskainiz; adibidez, udalerri bakar bateko datuak hautatzeko aukera ematen du, Euskal AEko 251 udalerriak dauden taula batetik.
Erabiltzaile aurreratuagoentzat, halaber, pibote-aukerak, askotariko kalkuluak, kategoriak ezabatzea, etiketen testuak aldatzea, irteera-formatuak eta abar ematen ditu.
Horrela, ateratzen den taula edo grafikoa iragazketa- eta pertsonalizazio-maila handiarekin aurkez daiteke; hala ere, pertsonalizazio horrek prozesu neketsua eskatzen du, proba-errorea ere eskatzen duena, eta etorkizunean haraino itzultzea zaila izan daiteke puntu berera iritsi nahi bada.
Testuinguru horretan, baliagarria izan dakiguke "gordetako kontsulta" bat sortzea.
Kontzeptua eta funtzioa
Gordetako kontsulta bat url bat baino ez da –esteka bat, interneteko helbide bat– zeinek EDBko taula batera eramaten gaituen, guk asmatu bezala, haren iragazketarekin eta egin dizkiogun pertsonalizazio guztiekin.
Aldi berean, gogoko gisa balio du –nabigatzailean gorde ahal duguna–, esteka gisa –dokumentu batean sar dezakeguna– eta gure intereseko taula batera itzultzeko denbora asko aurrezteko –ez dugu hautaketa- eta eraldaketa-prozesu osoa errepikatuko–.
Nola gorde kontsulta bat
Jakina, hautaketa bat gordetzeko aukera bakarrik agertuko zaigu aukera bat egin dugularik. Hau da, EDBan eskuragarri dauden guztien artean jada serie bat hautatu dugu, gure intereseko kategoriak eta aldiak jada hautatu ditugu, eta emaitza pantailan badugu aurkeztu.
Une horretan, eskura izango dugu “Gorde zure” aukera.
Une horretan, eta "Bukatu" botoiari emanez bakarrik (berehala joango gara erabilgarri dauden “eguneratze-aukeretara”), jada agertuko zaigu pantailan “Gordetako kontsulta”-ren esteka.
Edozein nabigatzailetan url hori exekutatuz, hautaketa eta eraldaketa guztiak jasotzen dituen taulara iritsiko gara, egin ditugun bezalaxe.
Eguneratze-aukerak
EDBa gordailu bizia da. Kasu anitzetan, gordetako kontsulta batera itzultzen garenean, serieari aldi berriak gehitu zaizkiola gerta daiteke. Eguneratze-aukerek aukera ematen dute zehazteko zer gertatuko den aldi berriekin, halakorik balego, gordetako kontsultara berriz sartzeko unean.
Hiru dira aukerak:
1.- Kontsulta eguneratu hasiera-puntu mugikor batekin eta beti aldi kopuru berarekin.
Aukera hori aktibatzen badugu, gure taulak beti aldi-kopuru berbera izango du, eta erabilgarri dagoen azkenean amaituko da. Aukera egokia da, adibidez, beti serie bateko azken 10 aldiak nahi baditugu.
2.- Kontsulta eguneratu hasiera-puntu finko batekin, aldi berriak gehituz.
Aukera hori aktibatzen badugu, gure taularen hasierako aldia beti berbera izango da, hautaketa gordetzean aukeratu genuena, baina, seriean aldi berririk badago, pantailan agertuko dira.
3.- Ez eguneratu kontsulta; pantailako aldi berberak erakutsi.
Aukera hori aktibatzen badugu, pantailan ikusten dugun emaitza berera itzuliko gara beti, kontsulta gordetzeko unean, serie horretan aldi berririk egon arren.
Formatu-aukerak
Azkenik, "gordetako kontsultak" funtzionalitateak irteerako formatu bat zehazteko aukera ematen digu.
Besterik adierazi ezean, formatua izango da “pantailan ikusten den bezala”, eta, beraz, gordetako kontsultak pantaila berri batera eramango gaitu, zeina izanen baita sortzeko unekoaren berdin-berdina (hautatutako eguneratze-aukera aplikatuta).
Hala ere, testuinguru zehatzetan interesgarriak izan daitezkeen formatu hauek guztiak ere eskaintzen ditu:
Formatu horiek aukera ematen dute EDBaren berrerabilera aurreratuak egiteko, hala nola kalkulu-orri batetik edo web-aplikazio batetik gordetako kontsulta eskatzeko.
Sarrera
Eustatek 2.000 taula baino gehiago biltzen dituen bere Datu Bankua kontsultatzeko API bat du martxan.
API honek datu estatistiko eguneratuak programazio bidez eskuratzeko aukera ematen du, web bidezko deskargaren alternatiba automatizatu gisa. API honi esker, posible da:
datuak beti eguneratuta bistaratzea, adibidez web orri batean taula edo grafiko moduan
datuak zuzenean R, Python edo Jupyter Notebooks bezalako tresnetara inportatzea, ondoren tratatzeko eta aztertzeko
APIek (Aplikazioen Programazio Interfazeek) sistema desberdinen arteko komunikazioa ahalbidetzen dute. APIra egindako eskaera batek hiru elementu nagusi izaten ditu:
-web helbide nagusia (endpoint)
-deia egiteko funtzio bat, HTTP metodo baten bidez (GET, POST, etab.)
-datuak filtratzeko, ordenatzeko edo pertsonalizatzeko aukera ematen duten parametro multzoa
Eustaten APIaren URL helbideen (endpointen) oinarrizko egitura honako hau da:
Jarraian, APIko sarrerako puntuetara deitzeko modua zehazten da, baita datuak kontsultatzeko behar diren metodoak eta parametroak ere.
Datu-bankuko taulen zerrenda
Datu-bankuaren URLra deitzen baduzu GET funtzioarekin, taula guztien zerrenda agertuko zaizu JSON formatuan. Datu bankuaren URL helbideak egitura hau du:
https://www.eustat.eus/bankupx/api/v1/{hizkuntza}/DB
{hizkuntza} parametroa zehaztu behar da. eu jarriz gero, taulen zerrenda euskeraz azalduko zaizu:
- https://www.eustat.eus/bankupx/api/v1/eu/DB
Erantzunaren itxura:
{
"id": "PX__fe_inem06.px",
"type": "t",
"text": "Euskal AEko erregistratutako langabezia, lurralde eremuaren eta sexuaren arabera. 1997 - 2022",
"updated": "2023-01-09T15:04:41"
},
{
"id": "PX__feinem_inem06.px",
"type": "t",
"text": "Euskal AEko erregistratutako langabezia, lurralde eremuaren eta sexuaren arabera",
"updated": "2021-02-17T10:04:22"
}
JSON formatuan azaltzen den erantzunak atributu hauek dakartza:
| Atributua | Deskribapena |
| id | Taularen kode identifikatzailea |
| type | t= Taula |
| text | Taularen izenburua (edukiaren deskribapena) |
| udpated | Taula azken aldiz eguneratu den eguna eta ordua |
Taula baten metadatuak
Taula baten URLari GET funtzioarekin dei eginez gero, taulako metadatuak itzuliko dizkizu JSON formatuan. Taularen identifikazio kodea ezagutzen baduzu, URLa kontsulta dezakezu parametro hauekin:
https://www.eustat.eus/bankupx/api/v1/{hizkuntza}/DB/[id]
{hizkuntza} parametroa hizkuntzari dagokio. [id] parametroa taularen kode identifikatzaileari dagokio.
Metadatuek izenburu bat dute ("title") hasieran eta ondoren taulan azaltzen diren aldagaien zerrenda.
Adibidez:
https://www.eustat.eus/bankupx/api/v1/eu/DB/PX_050403_cpra_tab_a_25.px
Erantzunaren itxura:
{
"title": "Euskal AEko 16 urte eta gehiagoko biztanleria landunaren asteko orduen batez bestekoa, lurralde, sexu, sektore ekonomiko eta hiruhilekoaren arabera (orduak). 2015 - 2025",
"variables": [
{
"code": "territorio histórico",
"text": "lurralde historikoa",
"values": [
"_T",
"01",
"48",
"20"
],
"valueTexts": [
"Euskal AE",
"Araba/Álava",
"Bizkaia",
"Gipuzkoa"
]
},
{
"code": "sexo",
"text": "sexua",
"values": [
"_T",
"1",
"2"
],
"valueTexts": [
"Guztira",
"Gizona",
"Emakumea"
]
},
{
"code": "sector económico",
"text": "sektore ekonomikoa",
"values": [
"_T",
"01",
"02",
"03",
"04"
],
"valueTexts": [
"Guztira",
"Nekazaritza, abeltzaintza, basozaintza eta arrantza",
"Industria",
"Eraikuntza",
"Zerbitzuak"
]
},
{
"code": "trimestre",
"text": "hiruhilekoa",
"values": [
"10",
"20",
"30",
"40",
"50"
],
"valueTexts": [
"Urteko batez bestekoa",
"1. Hiruhilekoa",
"2. Hiruhilekoa",
"3. Hiruhilekoa",
"4. Hiruhilekoa"
]
},
{
"code": "periodo",
"text": "aldia",
"values": [
"2015",
"2016",
"2017",
"2018",
"2019",
"2020",
"2021",
"2022",
"2023",
"2024",
"2025"
],
"valueTexts": [
"2015",
"2016",
"2017",
"2018",
"2019",
"2020",
"2021",
"2022",
"2023",
"2024",
"2025"
],
"time": true
}
]
"Variables" objetuek lau atributu dituzte:
| Atributua | Deskribapena |
| code | Aldagaiaren kodea |
| text | Aldagaiaren izena |
| values | Aldagaiaren balioen zerrenda, kodeekin |
| valueTexts | Aldagaiaren balioen zerrenda, testuekin |
Taula bateko datuak
Taula bateko datuak lortzeko, kontsulta bat egin behar diozu (JSON formatuan) interesatzen zaizun taularen URLari. Metadatuak lortzeko erabiltzen den sarbide-puntu bera da, baina oraingoan POST funtzioa erabiltzen da.
Kontsulta guztiak honako testu honekin hasten dira: {query: [{...}]}. Filtro hauek erabiltzen dira:
| Filtroa | Deskribapena |
| item | Filtratu nahi diren balioen hautaketa |
| top | Lortu nahi den azken "x" balioen kopurua hautatzeko. Normalean, aldia/urtea aldagaiarekin erabiltzen da |
Adibidez:
{
"query": [
{
"code": "componente",
"selection": {
"filter": "item", // ¿ "componente" izeneko aldagaiaren filtroa
"values": [
"200" // ¿ aukeratutako balioa
]
}
},
{
"code": "tipo de serie",
"selection": {
"filter": "item", // ¿ "tipo de serie" izeneko aldagaiaren filtroa
"values": [
"10", // ¿ aukeratutako balioak
"30"
]
}
},
{
"code": "periodo",
"selection": {
"filter": "top", // ¿ "top" filtroa, "periodo" izeneko aldagaiaren azken "x" baloreak lortzeko
"values": [5] // ¿ azken 5 baloreak eskatzen dira
}
}
],
"response": {
"format": "json-stat" // ¿ irteerako formatua (json-stat dago lehenetsia)
}
}
Kontsulta hau egin ahal izateko, taulak zer aldagai eta balio dituen jakin behar da. Taula bakoitzaren aldagai eta balioen informazioa bi modutara lor daiteke:
1) Metadatuak kontsultatuz, 3 atalean adierazten den bezala 3. Taula baten metadatuak.
2) Datu-bankuko aldagaiak eta balioak hautatzeko laguntzailea (erabiltzailearen interfazea) erabiliz. Taula jakin baten hautaketa-laguntzailearen URL helbideak egitura hau du:
https://www.eustat.eus/bankupx/pxweb/{hizkuntza}/DB/-/{id}
Adibidez: https://www.eustat.eus/bankupx/pxweb/eu/DB/-/PX_170112_cpib_pib_a_01.px
Taula guztien zerrenda helbide honetan kontsulta daiteke: https://www.eustat.eus/bankupx/pxweb/eu/DB/-/
Jarraian, hautaketa-laguntzailea erabiliz POST kontsulta bat egiteko urratsak azalduko ditugu:
Nola hautatu aldagaiak eta balioak
Balio konkretu batzuk aukeratu nahi ditugu honako taula honetan: "Euskal AEko barne produktu gordina (BPG-eskaintza), lurralde historiko, jarduera-adar (A-38), datu-mota eta neurri-motaren arabera. 1995 - 2023".
Taula helbide honetan dago:
https://eu.eustat.eus/bankupx/pxweb/eu/DB/-/PX_170112_cpib_pib_a_01.px
Egin klik Taula hau eskuragarri egin zure aplikazioan atalean. Hor azalduko dira APIaren bidez datuak lortzeko beharrezkoak diren URLa eta kontsulta.
Interfazeak APIan erabiliko den kodea sortzen eta editatzen laguntzen dio erabiltzaileari. Kontsulten kodea sortzeko pentsatuta dago, eta ez produkzioan erabiltzeko.
Irteerako JSON fitxategiak irakurtzeko, formatu hori prozesatu dezakeen programa edo lengoaia bat erabili behar da. Tutorialak eta kode-adibideak sortu ditugu erabiltzaileei Eustaten APIaren erabilera errazteko R lengoaian, Pythonen eta Javascript-en
Irteera-formatuak
APIak 5 formatutan itzul ditzake tauletako datuak:
-JSON-stat, 1.2 bertsioa (formatu lehenetsia)
-CSV (testu laua)
-CSV2 (formatu egokiena taula dinamikoekin lan egiteko)
-CSV3 (CSV2 bezala, baina kodeekin testuaren ordez)
-XLSX (Excel)
Datuak erraz eta modu malguan prozesatzeko, JSON-stat formatua gomendatzen dugu.