Albisteak

Herrietako elkarteak (APIaren erabileraren adibide bat)

Argitalpen-data: 

Beste demo bat prestatu dugu, herritar elkargoen Euskadiko map. Hau egiteko, Euskadiko Elkarteen erregistroan onarritu gara, eta datuak elkartu ditugu Eustat-en Nora zerbitzu geografikoak ematen dituenekin. Horrekin batera, Open Street Map mapa librea ere erabili dugu udalerrien mugak marrazteko..

Emaitza “berotasun mapa” bat da, non gorriz ageri diren elkarte gehien dituzten herriak (biztanlegoa kontuan hartutako proportzioan, alegia), eta berdez, punturik hotzenak nolabait esateko, elkarte gutxiago dauden lekuak.

Elkarteen mapa

Baina mapan datu gehiago ere badaude, eta herri batera joanik, bertako datuak lortuko ditugu, zein elkarte dauden izena emanda erregistroan bertakoak. Kasu honetan, gainera, ez da datuen hustuketa egin dugula, baizik eta APIaren kontra denbora errealean egiten dugun kontsulta bat, eta beherago azaltzen dugu hori.

Esate baterako, hemen dugu Elgoibar, 92 elkarte dituen herria, perretxikuzaleen Karakate mikologia elkartetik hasi eta Parrokiako Abesbatzeraino. Zerrenda hori lortzen dugu erregistrora dei bat eginez APItik. Demagun bihar beste elkarte bat gehitzen dela erregistrora Elgoibarren egoitza duena. Ba, berriz kontsultatu orri hori etzi, eta 93 elkarteko emaitza emango digu.

Elgoibarko elkarteak

Demo honen interfazea sinplea da, ikusten duzuenez. Aurreko adibideetan ere sinpletasunera jo dugu. Horregatik, adibidez, Bilbon aurki daitezkeen 4.000 elkarteak 40 orritan erakusten ditugu. Ez da gauzarik erabilgarriena, baina, tira, demo bat da, eta datuak eta tresnak eskura ditu nahi duenak, bilatzaile bat bezalako gauza bat sortzeko, adibidez. Alde horretatik, saiatuko gara azaltzen nola erabili dugun APIa kasu honetan.

APIaren azalpena

Gure eskaera Euskadi.net-eko API generikoaren kontra egiten dugu, eta XML erako erantzunak jasotzen ditugu handik. API generikoa da, ez berezitua, eta horregatik bilaketa parametroak partikular samarrak dira. Azaltzen saiatuko gara, dena dela.

Oinarrizko URLa hau da: http://opendata.euskadi.net/r01hSearchResultWar/r01hPresentationXML.jsp. URL hori query string bat pasatu behar diogu, nahi ditugun objektuak berreskuratzeko. query_string hori definitzeko, aurrez aldetik hausnarketa egin dugu, ondorio hauetara iristeko:

  • Udalerrien arabera nahi genituen elkarteak. Euskadi.net-eko APIak Eustat-eko lurralde eta udalerri kodeak erabiltzen ditu, beraz haiekin dokumentatu gara.
  • Zein erregistro behar genituen ere bagenekien, elkarte erakoak.
  • Pajinazio sistema bat ere behar genuen, herri batzuek emaitza asko eman ditzaketelako, eta emaitza guztiak batera jaso eta prozesaturik, exekuzio denbora eta indarra kontsumitu genezakeen sisteman. Hori ebitatzea komeni.

Irizpide horietatik eraiki dugu  query string-a, & lotailuarekin elkartuz elementuak. Hauetxek, hain zuzen:

  • r01Lang: hizkuntza
  • r01kQry: Euskadi.net-eko datu eremua (honetara iritsiko gara berriro beherago)
  • r01PgCmd: pajinazio modua
  • r01kSrchSrcId: bilaketa iturriaren identifikatzailea.

Parametro sinpleak dira, salbu eta, beharbada, r01kQry izenekoan, non APIaren indarra (eta konplexutasuna) aurkituko dugun.

Aldagai horien argudioekin eraikitzen dugu query bat, eta harekin Euskadi.net-eko datuak erauzi. Bilaketa, ordenatze eta pajinazio irizpideak pasatzen ditugu, formatu hau erabiliz; ‘identificador_operacion:filtro;’. Adibidez, euskadi.net-en dauden dokumentuak aurkitzeko, aplikatu behar den irizpidea da:  ‘tC:euskadi;’

Euskadi.net-eko APIa oso luzea eta konplexua da detailean sartuz gero, baina laburbilduz, dokumentuak parametro hauetan finkatuz lortu ditugu:

  • tC:euskadi;
  • tF:registros_administrativos;
  • tT:asociacion;

Filtro edo iragazkiak gehitu ditugu, beraz, honela:

  • m:documentLanguage.EQ.es,recTerrytoryCode.EQ.CODIGO_PROVINCIA,recTownCode.EQ.CODIGO_MUNICIPIO;

Ordenatzeko irizpideak:

  • o:documentCreateData.DESC

Pajinazioa eta erregistro kopurua orrikoa:

  • pp:r01PageSize.100

Eta honela pasatzen dizkiogu eskaerak Euskadi.net-i. Ikus ditzagun iragazki horiek:

  • erabiltzen da ‘,’ karakterea bilaketa parametroak definitu eta bereizteko.
  • eskura dauden aldagaiak XMLan daudenak dira.
  • iragazkirako operazio posibleak dira EQ eta LIKE
  • Erabiltzen da ‘.’ parametroa definitzeko, eta horrela documentLanguage.EQ.eu kateak esan nahi duena da, hizkuntza euskara dela: documentLanguage=’eu’

Hori kontuan izanik, Elgoibarko lehen 100 elkarteak lortzeko URL hau erabili behar dugu.

Erantzunean XML-a jasotzen dugunean, bilatu behar dugu ‘results’ etiketa, zeina aurkituko dugun xpath honekin: ‘/searchSession/searchResultsBySource/searchSourceResults/results’

Nabigazio edo pajinazioa antolatzeko, orriaren zenbakia dugu, eta emaitza kopurua ere bai, eta horiek ‘navBar’ etiketak aurkituko ditugu, zeinera iritsiko garen xpath honekin: ‘/searchSession/searchResultsBySource/searchSourceResults/navBar’

Demo hau egiteko software librea erabili dugu, Django deritzon framework-a, hain zuzen, eta APIaren komunikatzeko erabilitako kodea hemen argitaratu dugu.