Usted está aquí

Inicio / Desarrolladores

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 (Application Programming Interface) hacen referencia a los procesos, funciones y métodos que ofrece una biblioteca de programación, como capa de abstracción, para que sea usada por otro programa informático.

En el portal Open Data BCN podemos distinguir tres tipos:

  • API 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 desarrolladas por las propias fuentes de información

Tanto la API de gestión del catálogo, como la de consulta sobre los recursos CSV se 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. Incluyendo el parámetro callback la respuesta se devuelva en formato JSON para su uso con Javascript.

2.1. API de gestión del catálogo

Se puede acceder mediante la API a los datasets y recursos publicados en el portal Open Data BCN.

Se trata de la API que ofrece la tecnología CKAN para gestionar el catálogo de datasets. La documentación completa se puede encontrar en este enlace.

La URL base para la API es https://opendata-ajuntament.barcelona.cat/data/api/ i se puede acceder a través de la URL https://opendata-ajuntament.barcelona.cat/data/api/action/, a la que se tendrá que añadir el nombre del método al que queremos acceder.

Estos métodos son públicos y no requieren de ningún tipo de identificación ni token siendo algunos ejemplos:

  • 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 del dataset a partir del id del dataset y entre estos, el resource_id de los recursos
    Ejemplo: https://opendata-ajuntament.barcelona.cat/data/api/3/action/package_show?id=arbrat-zona
  • datastore_search: devuelve la información de cada recurso.
    Ejemplo: https://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search?resource_id=f7134b6f-95ce-4b83-bacd-6f411bd9c1f0
    y si además quisieramos buscar, por ejemplo, el valor=14 dentro del recurso:
    https://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search?resource_id=f7134b6f-95ce-4b83-bacd-6f411bd9c1f0&q=14

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

Así mismo, para facilitar la interoperabilidad entre catálogos de datos publicados en la web usamos la extensión DCAT.

Subir

2.2. APIs de consulta sobre recursos CSV

El filtro API CKAN disponible permite seleccionar los datasets con esta interfaz habilitada.

Estas interfaces permiten actuar sobre un recurso CSV concreto. Con el fin de que la plataforma muestre 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. Los recursos con API CKAN habilitada se pueden seleccionar mediante el filtro del catálogo 'API CKAN disponible'.

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: https://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, que es del tipo: https://opendata-ajuntament.barcelona.cat/data/es/dataset/nom/resource/identificador ya la incorpora directamente.

identificador es el ID del recurso y 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: https://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:

https://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: https://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:
https://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:

  • Geoservicios WMS y WMTS de la Infraestructura de Datos Espaciales del Ayuntamiento de Barcelona

3. Tokens

Los tokens de acceso son unos identificadores que contienen las credenciales de seguridad para iniciar una sesión, pudiendo identificar un usuario, grupos, permisos y en algunos casos, una aplicación concreta. En el caso de Open Data BCN, se identifica el usuario.

Pueden encontrar aquí/strong> toda la información referente a la obtención y el uso.

Así mismo, el filtro del catálogo llamado Token requerido permite seleccionar los datasets que contienen recursos con esta opción habilitada, los cuales muestran en el botón de 'Descargar', un icono con forma de llave.

4. Limitación del número de accesos a datasets y recursos

Para ofrecer la máxima disponibilidad y calidad del servicio, se aplicaran los límites de acceso detallados a continuación en las búsquedas on-line de datasets y en las descargas de recursos:

  • Datasets:
    Búsqueda on-line: 30 peticiones/minuto

  • Recursos:*
    Descarga: 1 petición/segundo o 60 peticiones/minuto
    Acceso via API: 30 peticiones/minuto

Estos límites son susceptibles de modificación para ofrecer siempre el mejor servicio a los usuarios.
En el caso de que se llegue al límite de accesos, se indicará devolviendo el código 503.

5. GITHUB del Ajuntament de Barcelona

En el GITHUB del Ajuntament de Barcelona se publican las extensiones de CKAN y Drupal que se han desarrollado para implementar nuevas funcionalidades del portal:

  • CKAN:
    • odatabcn: personalización de la apariencia del catálogo y otras funcionalidades.
    • federagobes: generación del fichero en formato .RDF del catálogo de Open Data BCN para federar los datasets con el portal datos.gob.es.
  • Drupal:
    • opendata_tokens: generación, almacenamiento y regeneración de los tokens de acceso.

6. Programación

  • Cómo transformar un archivo de extensión .csv inicialmente en formato WIDE a un archivo en formato LONG.

Describimos con un ejemplo cómo se puede transformar un archivo publicado en formato WIDE a uno publicado en formato LONG en lenguaje de programación Python.

#!/usr/bin/env python
# -*- coding: utf-8 -*-

#Para utilizar el script, llamar indicando el número de id_vars(columnas fijas) Ejemplo de 2 id_vars: python wide_to_long.py 2
import pandas as pd
import sys

df = pd.read_csv("in_WIDE.csv")
numero_ids = int(sys.argv[1])

id_vars = []

for i in range(numero_ids):
	id_vars.append(df.columns[i])

df = pd.melt(df, id_vars=id_vars, var_name='Concepte', value_name='Valor')
id_vars.append('Concepte')
id_vars.append('Valor')
df = df.reindex_axis(id_vars, axis=1)

dt = df.dtypes
print (dt)
print(df)

df.to_csv("out_LONG.csv", index = False)


7. 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:

8. 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 Contáctenos