Asociacionismo en Euskadi (uso avanzado del API)

Hemos preparado otra demo, usando datos de fuentes distintas. El mapa del asociacionismo en Euskadi.

Basándonos en el Registro de Asociaciones de Euskadi disponible entre los datasets de Open Data Euskadi, combinamos los datos extraídos del mismo con el listado de municipios del servicio geográfico Nora del Eustat y con los límites municipales disponibles en Open Street Map, el gran mapa libre.

El resultado es un “mapa de calor”, donde aparecen en rojo más oscuros las localidades con mayor número de asociaciones por habitante, y en verde las zonas más frías, con menos asociacionismo, por así decirlo.

Pero el mapa va un poco más allá: clicando en un municipio dado, obtenemos el listado de asociaciones con sede en tal localidad, su nombre, y también su objeto. En este caso, no es un volcado de datos que hayamos hecho, sino una consulta en tiempo real al API.

Por ejemplo, los datos de Elgoibar, con 92 asociaciones registradas, desde la micológica Karakate al Coro Parroquial. Este listado lo obtenemos en tiempor real en consulta desde el API del registro. Si surge una nueva asociación en Elgoibar y se añade al registro la semana que viene, la consulta a la misma página os dará con 93 asociaciones.

El interfaz de la aplicación demo es, como en ejemplos anteriores que hemos hecho, muy simple. Las casi 4.000 asociaciones que hay en Bilbao las mostramos paginadas en 40 páginas. No es lo más usable, obviamente. Ahora bien, ahí están las herramientas y los datos, y si alguien quiere hacer un buscador, lo puede hacer

Explicación del API

La consulta que hacemos nosotros, concretamente, se hace accediendo al registro de asociaciones usando el API genérico de euskadi.net. Este API nos ofrece resultados en formato XML. Al no ser un API específico, cuesta un poco dar con los parámetros concretos para realizar la búsqueda. Pero trataremos de explicarlos.

La url de base es http://opendata.euskadi.net/r01hSearchResultWar/r01hPresentationXML.jsp y a esta url tenemos que pasarle un query string para recuperar los objetos que nos interesan. Para elaborar este query_string hemos tenido en cuenta lo siguiente:

• Nos interesaba recuperar las asociaciones por municipio. El API de euskadi.net utiliza los códigos del Eustat para identificar los municipios, utilizando el código de provincia y el código de municipio.
• Tenemos que conocer también cuales son los registros que queremos recuperar y también de que tipo son. En este caso estamos hablando de registros_administrativos del tipo asociación.
• Por último, es necesario elaborar algun tipo de sistema de páginación, ya que hay localidades que pueden devolver muchos resultados, y una petición de este tipo seria muy costosa en tiempo de ejecución y consumo de recursos.

A la hora de construir el query string tenemos que tener en cuenta cual es el formato que utiliza la API de euskadi.net. Por defecto, como en cualquier petición http, los diferentes campos del query_string se definen entre el carácter ‘&’. La API de euskadi.net recibe estos parámetros:

• r01Lang: Idioma de la consulta
• r01kQry: query que se aplicará en el entorno de datos de euskadi.net (volveremos a este parámetro, pues es el más interesante para la demo que nos ocupa)
• r01PgCmd: modo de paginación
• r01kSrchSrcId: Identificador de la fuente de búsqueda.

La mayor parte de los argumentos no tienen mucho secreto, pero es en el parámetro r01kQry donde nos encontramos con la potencia (y complejidad) del API.

Con la cadena que pasamos en este argumento, el sistema de euskadi.net construye una query con la que recupera datos. En esta cadena pasamos los criterios de búsqueda, criterios de ordenación, criterios de paginación… Para generar estos criterios utilizamos el formato ‘identificador_operacion:filtro;’. Por ejemplo, para buscar documentos en euskadi.net el criterio a aplicar es ‘tC:euskadi;’

La documentación del API de Euskadi.net es prolija y lo cierto es que lleva trabajo desentrañar sus misterios. Pero, resumiendo, en este caso, hemos aplicado estos criterios de selección de documentos:

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

Los siguientes criterios de filrado:

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

Criterios de ordenacion:

• o:documentCreateData.DESC

Y citerios de paginación y número de resultados:

• pp:r01PageSize.100

Si se observan los criterios de filtrado, ordenación y paginación, se podrá ver como se le pasan valores al sistema interno de euskadi.net.

Analicemos los criterios de filtrado:

• Se utiliza el caracter ‘,’ para definir los distintos parámetros de búsqueda.
• Los atributos disponibles para filtrado son los que aparecen en el XML
• Las operaciones disponibles para filtrar son EQ y LIKE
• Se utiliza el caracter ‘.’ para definir el parámetro, de esta manera la cadena documentLanguage.EQ.es es equivalente a documentLanguage=’es’

Teniendo en cuenta todo ello la petición para recuperar las primeras 100 asociaciones de Elgoibar tenemos que pedir esta URL (abrir para verla entera).

Una vez  recuperado el XML tendremos que navegar hasta la etiqueta ‘results’ a la que podremos acceder con el xpath ‘/searchSession/searchResultsBySource/searchSourceResults/results’

Para organizar la navegación/paginación tendremos disponibles el número de página y el número de resultados como atributo de la etiqueta navBar que podremos acceder en el xpath ‘/searchSession/searchResultsBySource/searchSourceResults/navBar’

En nuestra aplicación demo, hemos usado el framework de software libre Django, y el código que se encarga de la comunicación con el API, lo hemos publicado aquí.