API de Datos Detalles

Qué es una API

Una API (application programming interface) es una interfaz de programación de aplicaciones. Es decir, es un conjunto de funciones y procedimientos de uso general que se utilizan en el desarrollo de software para la integración entre aplicaciones.

Desde Open Data Bizkaia proporcionamos dos tipos de API:

  • API de gestión del catálogo: API que sirve para consultar y gestionar la información del catálogo, de los recursos, conjuntos de datos o datasets, etiquetas, temas, etc.
  • API de consulta sobre los recursos CSV: API que permite consultar y filtrar la información contenida dentro de un CSV de un recurso.

Tanto las API de consulta de recursos CSV así como las de gestión del catálogo se ofrecen como Servicios Web REST en formato JSON.

Se pueden invocar a la mayoría de los métodos también directamente mediante la URL, añadiendo los parámetros que sean necesarios. En la llamada a estos métodos se puede incluir el parámetro callback para que la respuesta se devuelva en formato JSONP para su posterior uso con Javascript.

API de gestión del catálogo

Esta es la API que ofrece el aplicativo CKAN para gestionar el catálogo de datasets. Podemos acceder a esta API a través de la URL tal y como se indica en el apartado “Punto de acceso API”, añadiendo el nombre del método al que queremos acceder.

Los reutilizadores pueden, mediante esta API, acceder a la misma información sobre recursos, datasets, etiquetas, temas, etc. publicada en el propio portal Open Data Bizkaia.

Algunos de los métodos que se pueden utilizar con esta API son los siguientes:

  • current_package_list_with_resources: devuelve un listado de todos los datasets actuales con sus recursos
  • package_search: búsqueda de un dataset determinado dentro del catálogo
  • resource_search: búsqueda de un recurso determinado dentro del catálogo
  • package_show: devuelve los metadatos de un dataset
  • resource_show: devuelve los metadatos de un recurso
  • group_list: lista los temas del portal

API de consulta sobre los recursos CSV

Esta API permite actuar sobre un recurso CSV concreto del portal. Cuando se sube un CSV a la aplicación, se crea de forma interna una tabla en la base de datos del datastore para este recurso. La API de consulta sobre recursos CSV es precisamente la API del datastore, que permite realizar consultas directamente sobre estas tablas.

Desde el portal Open Data Bizkaia se facilita un endpoint para todos los CSV de la plataforma, que permite buscar información dentro de un recurso mediante la definición de una serie de criterios de búsqueda que se añaden como parámetros a la llamada.

Este endpoint es el siguiente (datastore_search):
https://www.opendatabizkaia.eus/es/api/3/action/datastore_search

Comentar que el parámetro /es/ hace referencia al idioma castellano, pudiéndose utilizar /eu/ para el caso de euskera y /en/ para inglés, siempre que el recurso tenga disponibilidad en cada uno de esos idiomas.

A la hora de consultar un recurso en concreto, debe definirse como parámetro el identificador (ID) del recurso sobre el que se quiere hacer la consulta.

Cuál es el identificador de un recurso

Para obtener el identificador (ID) de un recurso debe tener en cuenta que las URL de los recursos en el portal son del tipo:
https://www.opendatabizkaia.eus/es/catalogo/nombre-dataset/recurso/identificador

Donde identificador es el ID del recurso en cuestión. Con lo cual simplemente navegando por los recursos del portal puede obtener los identificadores de los recursos para realizar la consulta a la API con ese identificador (ID).

Por ejemplo, sobre el recurso “Bienes inmuebles (2019 – 2022)” pulsando el botón derecho del ratón sobre el apartado “Descargar CSV” y escogiendo la opción “Copiar dirección de enlace”, se obtendrá la siguiente URL que incluye el identificador del recurso: https://www.opendatabizkaia.eus/es/dump/58f8c26e-996a-42e3-a49e-ef1e8e754ce6/bienes-inmuebles-2019-2022?format=csv

Cómo obtener los nombres de los campos de un recurso

Para obtener los nombres de los campos de un recurso y poder realizar consultas con la API, únicamente tenemos que acceder a la previsualización del recurso CSV.

Por ejemplo, si accedemos al recurso " Bienes inmuebles (2019-2022)" y nos fijamos en la vista del explorador de datos, podremos ver que el recurso tiene unas cabeceras que en este caso en cuestión son: SOZIETATEA_EU/SOCIEDAD_EU, SOZIETATEA_CAS/SOCIEDAD_CAS, EKITALDIA/EJERCICIO, etc.

Cómo obtener los nombres de los campos de un recurso

Teniendo el identificador (ID) del recurso y estos campos podremos realizar consultas, tal y como explicamos en el apartado “Cómo se utiliza la API para hacer consultas”.

Cómo se utiliza la API para hacer consultas

El endpoint para realizar consultas es el siguiente:
https://www.opendatabizkaia.eus/es/api/3/action/datastore_search

Los parámetros que se pueden utilizar con este endpoint son:

  • resource_id (string - obligatorio) - identificador (ID) del recurso CSV sobre el que queremos buscar.
  • filters (diccionario) - condiciones que se han de cumplir. Ejemplo: {" SOZIETATEA_EU/SOCIEDAD_EU ": "%BFA%"}.
  • q (string o diccionario) - búsqueda en full text. Se puede especificar un string para buscarlo en todos los campos o un diccionario para buscar en campos concretos, p.e: {"key1": "a", "key2": "b"}.
  • distinct (boolean) - retorna sólo las filas diferentes.
  • plain (boolean) - trata la consulta como si fuese un texto plano.
  • language (string) - lenguaje de la consulta en full text.
  • limit (int) - número máximo de resultados. Por defecto retorna 100 resultados.
  • offset (int) - número de resultados que se deben saltar. Útil para hacer una paginación de resultados.
  • fields (string) - listado de campos que se incluirán en la respuesta. Por defecto retorna todos los campos con el mismo orden que en el CSV.
  • sort (string) - nombre de los campos para los que ordenar separados por comas: " SOZIETATEA_EU/SOCIEDAD_EU, SOZIETATEA_CAS/SOCIEDAD_CAS ".
  • include_total (boolean) - Devuelve el recuento total de registros coincidentes (opcional, por defecto: true).

Cómo obtener los datos actualizados de un recurso

Para obtener los datos más recientes correspondientes a una entrada de un recurso de un conjunto de datos se debe seleccionar el último recurso actualizado del mismo. El metadato "last_modified" proporciona dicha información dentro de la respuesta a la petición y permite seleccionar aquel más cercano a la fecha actual.

Así, el reutilizador puede implementar en la aplicación que está desarrollando una función que recorra todos los recursos de un determinado conjunto de datos y seleccione el más actualizado.

Por último, una vez disponga del último recurso actualizado, debe realizar una consulta a la API del datastore con el identificador (ID) del recurso en cuestión recuperado en el tratamiento anteriormente descrito. Y si se desea en esta última petición a la API del datastore se puede pasar parámetros como filtros.