DATUEN APIAK Detalles

Zer da API bat

API bat (application programming interface) aplikazioak programatzeko interfaze bat da. Hau da, aplikazioak integratzeko softwarearen garapenean erabiltzen diren erabilera orokorreko funtzio eta prozeduren multzo bat da.

Open Data Bizkaitik bi API mota eskaintzen ditugu:

  • Katalogoa kudeatzeko API: katalogoaren, errekurtsoen, datu-multzoen edo dataseten, etiketen, gaien eta abarren informazioa kontsultatzeko eta kudeatzeko balio du.
  • CSV errekurtsoei buruzko kontsultarako API: errekurtso baten CSV baten barruan dagoen informazioa kontsultatu eta iragazteko aukera ematen duen API.

CSV errekurtsoak kontsultatzeko APIak eta katalogoaren kudeaketakoak web REST zerbitzu gisa eskaintzen dira, JSON formatuan.

Metodo gehienei zuzenean dei dakieke URLaren bidez, beharrezkoak diren parametroak gehituz. Metodo horietarako deian callback parametroa sar daiteke, erantzuna JSONP formatuan itzul dadin, ondoren Javascript bidez erabiltzeko.

Katalogoa kudeatzeko API

Hau da dataseten katalogoa kudeatzeko CKAN aplikazioak eskaintzen duen API. API horretara URL bidez sar gaitezke, “API sarbide-puntuan” adierazten den bezala, sartu nahi dugun metodoaren izena erantsita.

API honen bidez, berrerabiltzaileek informazio bera eskura dezakete Open Data Bizkaia atarian bertan argitaratutako errekurtso, dataset, etiketa, gai eta abarrei buruz.

API honekin erabil daitezkeen metodoetako batzuk honako hauek dira:

  • current_package_list_with_resources: egungo dataset guztien zerrenda itzultzen du bere errekurtsoekin
  • package_search: bilatu dataset jakin bat katalogoaren barruan
  • resource_search: katalogoaren barruan errekurtso jakin bat bilatzea
  • package_show: dataset baten metadatuak itzultzen ditu
  • resource_show: errekurtso baten metadatuak itzultzen ditu
  • group_list: atariko gaiak zerrendatzen ditu

CSV errekurtsoei buruzko kontsultarako API

API horri esker, atariko CSV errekurtso jakin batean jardun daiteke. CSV bat aplikaziora igotzen denean, barruan taula bat sortzen da errekurtso horretarako datastorearen datu-basean. CSV errekurtsoei buruzko kontsultarako API datastorearen API da, hain zuzen ere, taula horietan zuzenean kontsultak egiteko aukera ematen duena.

Open Data Bizkaia atariak endpoint bat eskaintzen du plataformako CSV guztientzat. Horri esker, errekurtso baten barruan informazioa bila daiteke, deiari parametro gisa gehitzen zaizkion bilaketa-irizpide batzuk definituz.

Endpoint hau honako hau da (datastore_search):
https://www.opendatabizkaia.eus/es/api/3/action/datastore_search

Aipatu behar da /es/parametroa gaztelaniari egiten diola erreferentzia, eta/eu/erabili ahal izango dela euskararako eta/en/ ingeleserako, baldin eta errekurtsoa hizkuntza horietako bakoitzean erabilgarri badago.

Errekurtso jakin bat kontsultatzeko orduan, parametro gisa definitu behar da kontsulta egin nahi den errekurtsoaren IDa.

Zein da errekurtso baten identifikatzailea

Errekurtso baten identifikatzailea (ID) lortzeko, kontuan izan behar duzu atariko errekurtsoen URLa mota honetakoak direla:
https://www.opendatabizkaia.eus/eu/katalogoa/izenburua-dataset/errekurtsoa/identifikatzailea

Identifikatzailea errekurtsoaren IDa da. Horrela, atariko errekurtsoetan nabigatuz gero, errekurtsoen identifikatzaileak lor ditzakezu, identifikatzaile (ID) horrekin APIri kontsulta egiteko.

Adibidez, "Ondasun Higiezinak (2019 – 2022)" errekurtsoari dagokionez, saguaren eskuineko botoia sakatuz "CSV deskargatu" atalaren gainean, eta "kopiatu esteka-helbidea" aukeratuz, honako URL hau lortuko da, errekurtsoaren identifikatzailea duena: https://www.opendatabizkaia.eus/eu/dump/58f8c26e-996a-42e3-a49e-ef1e8e754ce6/bienes-inmuebles-2019-2022?format=csv

Nola lortu errekurtso baten eremuen izenak

Errekurtso baten eremuen izenak lortzeko eta APIrekin kontsultak egin ahal izateko, CSV errekurtsoaren aurrebistaratzea baino ez dugu ikusi behar.

Adibidez, "Ondasun Higiezinak (2019-2022)" errekurtsoa atzitzen badugu eta datuen esploratzailearen ikuspegiari erreparatzen badiogu, ikusiko dugu errekurtsoaren goiburuak honako hauek direla: SOZIETATEA_EU/SOCIEDAD_EU, SOZIETATEA_CAS/SOCIEDAD_CAS, EKITALDIA/EJERCICIO, etab.

Nola lortu errekurtso baten eremuen izenak

Errekurtsoaren IDa eta eremu horiek edukita, kontsultak egin ahal izango ditugu, "Nola erabiltzen den API kontsultak egiteko" Atalean azaldu dugun bezala.

Nola erabiltzen den API kontsultak egiteko

Kontsultak egiteko endpointa honako hau da:
https://www.opendatabizkaia.eus/es/api/3/action/datastore_search

Hauek dira endpoint honekin erabil daitezkeen parametroak:

  • resource_id (string - Nahitaezkoa) - Bilatu nahi dugun CSV errekurtsoaren ID.
  • filters (hiztegia) - Bete beharreko baldintzak. Adibidea: {" SOZIETATEA_EU/SOCIEDAD_EU ": "%BFA%"}.
  • q (string edo hiztegia) - full text bilaketa. Eremu guztietan bilatzeko string bat zehaztu daiteke, edo eremu zehatzetan bilatzeko hiztegi bat, adib. {"key1": "a", "key2": "b"}.
  • distinct (boolean) - errenkada desberdinak bakarrik itzultzen ditu.
  • plain (boolean)- Kontsulta testu laua balitz bezala tratatzen du.
  • language (string) - Kontsultaren hizkuntza full text-an.
  • limit (int) - Gehieneko emaitza-kopurua. Lehenetsita, 100 emaitza itzultzen dira.
  • offset (int) - Jauzi egin beharreko emaitzen kopurua. Emaitzen orrikatze bat egiteko erabilgarria.
  • fields (string) - Erantzunean sartuko diren eremuen zerrenda. Lehenetsita, eremu guztiak CSVko ordena berean itzultzen dira.
  • sort (string) - Zein eremutarako ordenatu behar den, komen bidez bereizita: “SOZIETATEA_EU/SOCIEDAD_EU, SOZIETATEA_CAS/SOCIEDAD_CAS ".
  • include_total (boolean) - Erregistro bateragarrien zenbaketa osoa itzultzen du (aukerakoa, lehenetsita: True).

Nola lortu errekurtso baten datu eguneratuak

Errekurtso baten sarrera bati dagozkion datu berrienak datu-multzo batetik lortzeko, errekurtso horren azken errekurtso eguneratua hautatu behar da. "Last_modified" metadatuak informazio hori ematen du eskaeraren erantzunaren barruan, eta egungo datatik gertuen dagoena hautatzeko aukera ematen du.

Horrela, berrerabiltzaileak datu-multzo jakin bateko errekurtso guztiak biltzen dituen eta eguneratuena hautatzen duen funtzio bat garatzen ari den aplikazioan inplementatu dezake.

Azkenik, eguneratutako azken errekurtsoa eskura duzunean, datastorearen APIri kontsulta egin behar diozu, lehen deskribatutako tratamenduan berreskuratutako errekurtsoaren identifikatzaile (ID) -arekin. Eta azken eskaera horretan datastoreko APIri nahi izanez gero, iragazkiak bezalako parametroak pasa daitezke.