Cómo usar la API de un portal de datos abiertos: CKAN y DCAT

El botón de descarga de un portal te da un fichero. Su API te da todos los ficheros, todas las actualizaciones y los metadatos que dicen cuándo cambió el fichero por última vez. La buena noticia es que casi nunca te encontrarás con un sistema hecho a medida: los miles de portales públicos que hay en el mundo funcionan con un puñado de plataformas, y en cuanto reconoces la plataforma ya conoces sus URLs.

Lo primero: averiguar qué tienes delante

Hazle al portal una sola pregunta antes de escribir código:

https://portal.example/api/3/action/package_search?rows=0

Si responde un JSON con "success": true, es un CKAN, y todo lo de la sección siguiente te sirve. Esa única petición es la que usamos para clasificar cada portal de nuestro propio registro: cuesta una llamada HTTP y marca la diferencia entre escribir un scraper y escribir tres líneas.

Si responde otra cosa, busca esto por orden:

• /data.json en la raíz: un catálogo DCAT / Project Open Data, el estándar que publica cada agencia federal estadounidense y el que agrega el portal europeo.
• /api/explore/v2.1/catalog/datasets: un portal OpenDataSoft.
• /resource/abcd-1234.json en los enlaces de una ficha de dataset: Socrata.

Si no responde nada, eso también es una respuesta: una parte sorprendente de los portales que aparecen en los directorios públicos está muerta o ha cambiado de dirección, y ninguna API arregla un dominio que ya no resuelve.

CKAN: primero el catálogo, después las filas

CKAN separa el catálogo (qué datasets existen) del datastore (las filas de los que son tabulares). Los dos se leen por HTTP y sin clave.

Buscar en el catálogo:

/api/3/action/package_search?q=calidad+del+aire&rows=50
/api/3/action/package_search?fq=organization:ayuntamiento-x&rows=50

La respuesta trae un array results; cada elemento es un dataset con una lista resources, y cada recurso tiene una url —el CSV de verdad, el GeoJSON de verdad— además de format, size y last_modified. Descargar esas URLs es toda la tubería.

Leer un dataset cuyo identificador ya conoces:

/api/3/action/package_show?id=calidad-aire-horaria

Y cuando el recurso se ha cargado en el datastore de CKAN, puedes consultar filas en lugar de descargar el fichero:

/api/3/action/datastore_search?resource_id=<id>&limit=100
/api/3/action/datastore_search?resource_id=<id>&q=Madrid

Dos avisos prácticos. package_search pagina con start y rows, y la mayoría de los portales limitan rows a 1000: itera, no pidas todo de golpe. Y el datastore es opcional: muchos CKAN solo alojan el fichero, así que comprueba datastore_active: true en el recurso antes de contar con él.

DCAT: un fichero que lo describe todo

Un catálogo DCAT no es una API de consulta. Es un único documento —/data.json, o una serialización RDF en catalog.rdf o catalog.ttl— que lista todos los datasets con su título, su editor, su licencia, su frecuencia de actualización y las URLs de sus distribution. Lo descargas una vez, lo filtras en local y ya está.

Eso lo convierte en la opción menos vistosa y la más fiable: sin límite de peticiones, sin paginación y sin versión de API que seguir. Es también la forma en que los catálogos se federan, y por eso un dataset publicado por una diputación aparece en data.europa.eu sin que nadie copie el fichero.

El precio es la frescura y la profundidad. El documento describe los datasets; no dice nada de las filas que hay dentro, y cada portal lo regenera cuando le conviene.

OpenDataSoft y Socrata: las filas son la API

Estas dos plataformas están construidas al revés: cada dataset se puede consultar, con filtros, agregaciones y exportaciones como parámetros de la URL.

OpenDataSoft, en su versión actual:

/api/explore/v2.1/catalog/datasets                        listar los datasets
/api/explore/v2.1/catalog/datasets/<id>/records?limit=20
/api/explore/v2.1/catalog/datasets/<id>/records?where=year>2020&group_by=region
/api/explore/v2.1/catalog/datasets/<id>/exports/csv       todo el conjunto

Socrata usa SoQL, que se lee como SQL metido en una cadena de consulta:

/resource/abcd-1234.json?$where=year>2020&$select=region,count(*)&$group=region
/resource/abcd-1234.csv?$limit=50000&$offset=0

Las dos limitan el tráfico anónimo y las dos ofrecen un token de aplicación gratuito que sube el límite. Si vas a bajar decenas de miles de filas, pide la URL de exportación en lugar de paginar: un fichero grande es más barato para ti y para el portal.

Cuando no hay API

Algunos de los datasets más valiosos viven detrás de una tabla HTML, un directorio FTP o un formulario de «solicítelo por correo». Por orden de preferencia: busca el fichero que el JavaScript de la página descarga por debajo (la pestaña de red del navegador lo enseña en segundos), comprueba si algún instituto de estadística publica la misma serie con una API de verdad y solo entonces plantéate pedirlo. Nuestra guía sobre cómo pedir información pública cubre el caso en que el dato existe pero no está publicado.

Antes de republicar lo que has descargado

Que la API sea abierta no significa que la licencia lo sea, y las dos cosas se guardan en sitios distintos. CKAN guarda license_id y license_title en el dataset; DCAT guarda una license en cada distribución; OpenDataSoft y Socrata la guardan en los metadatos del dataset. Lee ese campo antes de que los datos salgan de tu portátil: la atribución suele ser la única condición, es trivial de cumplir y queda muy mal no hacerlo, y qué exige de verdad cada licencia es una guía aparte.

La versión en inglés de esta guía está en How to use an open-data portal’s API.