Usted está aquí

Desarrolladores

1. Introducción

Esta sección del portal Open Data BCN está destinada a aportar información útil para los desarrolladores de aplicacions y el público objetivo con un perfil técnico.

2. APIs

Las APIs son interfaces que especifican cómo los diferentes componentes de programas informáticos deberían interaccionar. Se trata de un conjunto de funciones y procedimientos ofrecidos para ser utilizados por otro programa con el fin de interactuar con el programa en cuestión. Podemos distinguir tres tipos de APIs ofrecidas en el portal Open Data BCN:

  • APIs de gestión del catálogo: Esta API sirve para consultar y gestionar la información del catálogo, como datasets, recursos, etiquetas, etc...
  • APIs de consulta sobre recursos CSV: Permite consultar y filtrar la información contenida dentro de un CSV concreto
  • APIs propias del Ayuntamiento: Son APIs ofertadas por las fuentes de información y desarrolladas a medida

Tanto la API de gestión del catálogo de datos abiertos, como la de consulta sobre los recursos CSV ofrecen como servicios web REST en formato JSON (de entrada y de salida).

Muchos de los métodos también se pueden llamar directamente por URL añadiendo los parámetros necesarios. Para estos métodos, se puede incluir el parámetro callback para que la respuesta se devuelva en formato JSONP para su uso con Javascript.

2.1. APIs de gestión del catálogo

Se trata de la API ofrecida por el producto CKAN para gestionar el catálogo de datasets. Se puede acceder a esta API a través de la URL http://opendata-ajuntament.barcelona.cat/data/api/action/ a la que se ha de añadir el nombre del método al que queremos acceder.

Esta API puede tener interés para los ciudadanos para conocer qué información se encuentra disponible en el portal de Open Data BCN y los datasets que se van añadiendo. Se puede acceder mediante la API a la misma información accesible en la web de Open Data BCN.

La llamada a estos métodos no requiere el uso de un token ni ningún otro método de identificación: son métodos públicos.

Ejemplos de estos métodos son los siguientes:

  • current_package_list_with_resources: devuelve el listado de datasets actuales y sus recursos
  • package_search: realiza una búsqueda dentro del catálogo de datasets
  • resource_show: devuelve los metadatos de un recurso

Puede encontrar ejemplos de consultas y el listado completo de métodos en la guía API de CKAN.

Subir

2.2. APIs de consulta sobre recursos CSV

Se trata de métodos genéricos que permiten actuar sobre un recurso CSV concreto. Con el fin de que la plataforma ofrezca este servicio, el recursos se ha de subir al portal de Open Data BCN con un formato y codificación adecuados. Cuando se sube un CSV en la plataforma, se crea de manera interna una tabla en la base de datos de este recurso. Este almacenamiento dentro de CKAN se llama datastore. La API del datastore nos permite hacer consultas directamente sobre estas tablas.

Cabe destacar que el uso de la API de consulta es a nivel de recurso CSV individual, no del dataset del catálogo. Actualmente hay unos 1.000 recursos en el catálogo de Open Data BCN que se pueden consultar con esta API.

Sólo hay dos endpoints comunes para todos los CSV de la plataforma que permiten buscar dentro del recurso en función de los criterios de búsqueda añadidos como parámetros a la llamada o haciendo una consulta SQL:

Los endpoints son únicos para todos los recursos de la plataforma, para hacer una consulta sobre un recurso concreto, debemos definir como parámetro o dentro de la consulta el ID del recurso sobre el que queremos consultar.

Por ejemplo, para hacer una consulta sobre el recurso del año 2017 del dataset '50 Nombres más frecuentes de los habitantes de Barcelona por década de nacimiento y sexo' utilizaríamos la siguiente URL: http://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search?resource_id=51b78472-cd11-4426-912a-1d26240491e7

2.2.1 Cómo se obtiene el ID del recurso

La URL del recurso la monta la aplicación directamente y es del tipo: http://opendata-ajuntament.barcelona.cat/data/es/dataset/nom/resource/identificador

donde identificador es el ID del recursos. Por tanto, tan sólo hemos de navegar por el portal y seleccionar el recurso en cuestión para obtener el ID a partir de la URl.

2.2.2 Cómo encontrar los nombres de los campos en el portal

Para encontrar los nombres de los campos en el portal para poder utilizar la API de consulta tan sólo hemos de acceder a la previsualización del recurso CSV. Por ejemplo, vamos al recurso Fonts_201610.csv del dataset Fuentes públicas de beber de Barcelona y nos fijamos en las cabeceras de la previsualización del recurso: INVENTARI_NOM, INVENTARI_TIPUS, INVENTARI_CARRER, INVENTARI_NUMERO_CARRER, INVENTARI_COORDENADA_X, INVENTARI_COORDENADA_Y podremos hacer las consultas tal y cómo se explica en los apartados siguientes

2.2.3 datastore_search

URL: http://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search

  • resource_id (string - obligatorio) - id del recurso CSV sobre el que queremos buscar
  • filters (diccionario) - condiciones que se han de cumplir. Ejemplo: {“direccio”: “%carrer%”}
  • 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: “nom, codi desc”

Ejemplo de llamada a datastore_search

Queremos buscar las fuentes públicas de beber que se encuentran en la calle Mallorca. Para hacerlo, primero necesitamos conocer el ID del recurso y después el nombre del campo sobre el que queremos buscar. Esta información la podemos obtener de la página de previsualización del recurso en el portal.

Parámetros de entrada:

  • resource_id: Es la última parte de la URL de recurso (21f7a4df-2e73-45f8-8c6d-0b3db8c21527)
  • q: Lo consultamos en los campos de la previsualización del recurso {“INVENTARI_CARRER” : “Mallorca”}

URL de llamada:

http://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search?resource_id=21f7a4df-2e73-45f8-8c6d-0b3db8c21527&limit=5&q={%22INVENTARI_CARRER%22:%22%Mallorca%%22}

Subir

2.2.4 datastore_search_sql

URL: http://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search_sql

Las consultas de este tipo tienen un timeout limitado para que no se produzcan ataques DOS no intencionados.

Parámetros de entrada:

  • sql (string) - SELECT que se quiere ejecutar sobre los datos. El nombre de la tabla sobre la que se hace la consulta es el ID del recurso.

Ejemplo de llamada a datastore_search_sql

Queremos buscar en las fuentes públicas de beber las que se encuentran en la calle Mallorca. Necesitamos conocer el ID del recurso (que es el nombre de la tabla) y el nombre del campo por el que queremos filtrar.

Parámetros de entrada:

  • sql: SELECT * from "21f7a4df-2e73-45f8-8c6d-0b3db8c21527" WHERE "INVENTARI_CARRER" LIKE '%MALLORCA%'

URL de llamada:
http://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search_sql?sql=SELECT%20*%20from%20%2221f7a4df-2e73-45f8-8c6d-0b3db8c21527%22%20WHERE%20%22INVENTARI_CARRER%22%20LIKE%20%27%MALLORCA%%27

2.3. APIs propias del Ayuntamiento

Las APIs propias son las proporcionadas por los equipos que gestionan las fuentes de información. Estas APIs se enlazan desde el Portal de Open Data BCN pero no se mantienen o validan desde el mismo que equipo que gestiona el portal. En el portal se tratan como un recurso más, como si fuera un enlace a un archivo CSV o RDF.

Actualmente, en el catálogo Open Data BCN se ofrecen los siguientes recursos de tipo API:

3. Enlaces de interés

El portal de datos abiertos de la Unión Europea tiene una sección de Desarrolladores donde ofrece enlaces a clientes para la API de CKAN:

4. Otros

  • En el portal Open Data BCN disponemos de una sección de FAQs con preguntas frecuentes sobre el Open Data y el uso de los datos
  • Podéis enviar cualquier duda o consulta a través de Ayúdenos a mejorar