Desenvolupadors

• Introducció
• APIs
  
  • API de gestió del catàleg
  • APIs de consulta sobre recursos CSV
    • Com s'obté l'ID del recurs
    • Com trobar els noms dels camps dels recursos
    • datastore_search
    • datastore_search_sql
  • APIs pròpies de l'Ajuntament
• Tokens
• Limitació del nombre d'accessos a datasets i recursos
• GITHUB de l'Ajuntament de Barcelona
• Programació
• Enllaços d'interés
• Altres

1. Introducció

Aquesta secció del portal Open Data BCN està destinada a aportar informació útil per als desenvolupadors d'aplicacions i públic objectiu amb un perfil tècnic.

2. APIs

Les APIs (Application Programming Interface) fan referència als processos, funcions i mètodes que ofereix una biblioteca de programació, a manera de capa d'abstracció, perquè sigui emprada per un altre programa informàtic.

Al portal Open Data BCN podem distingir-ne tres tipus:

• API de gestió del catàleg: Aquesta API serveix per a consultar i gestionar la informació del catàleg, com datasets, recursos, etiquetes, etc...
• APIs de consulta sobre recursos CSV: Permet consultar i filtrar la informació continguda dins d'un CSV concret
• APIs pròpies de l'Ajuntament: Són APIs desenvolupades per les pròpies fonts d'informació.

Tant l'API de gestió del catàleg, com la de consulta sobre els recursos CSV s'ofereixen com a serveis web REST en format JSON (d'entrada i de sortida).

Molts dels mètodes també es poden cridar directament per URL afegint els paràmetres necessaris. Incloent el paràmetre callback la resposta es retorna en format JSON per al seu ús amb Javascript.

2.1. API de gestió del catàleg

Es pot accedir mitjançant l'API, als datasets i recursos publicats al portal Open Data BCN.

Es tracta de l'API que ofereix la tecnologia CKAN per tal de gestionar el catàleg de datasets. La documentació completa es pot trobar en aquest enllaç.

La URL base per l'API és https://opendata-ajuntament.barcelona.cat/data/api/ i s'hi accedeix des de l'URL https://opendata-ajuntament.barcelona.cat/data/api/action/, a la que s'haurà d'afegir el nom del mètode al que volem accedir.

Aquests mètodes són públics i no requereixen cap tipus d'identificació ni token sent alguns exemples:

• current_package_list_with_resources: retorna el llistat de datasets actuals i els seus recursos
• package_search: fa una cerca dins del catàleg de datasets
• resource_show: retorna les metadades del dataset a partir de l'id del dataset i entre elles el resource_id dels recursos
  Exemple: https://opendata-ajuntament.barcelona.cat/data/api/3/action/package_show?id=arbrat-zona
• datastore_search: retorna la informació de cada recurs.
  Exemple: https://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search?resource_id=f7134b6f-95ce-4b83-bacd-6f411bd9c1f0
  i si a més volguéssim buscar, per exemple, el valor=14 dins el recurs:
  https://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search?resource_id=f7134b6f-95ce-4b83-bacd-6f411bd9c1f0&q=14

Podeu trobar més informació a la guia API de CKAN.

Tanmateix, per facilitar la interoperabilitat entre catàlegs de dades publicades a la web utilitzem l'extensió DCAT.

Pujar

2.2. APIs de consulta sobre recursos CSV

El filtre API CKAN disponible permet seleccionar els datasets amb aquesta interfície habilitada.

Aquestes interfícies permeten actuar sobre un recurs CSV concret. Per tal que la plataforma mostri aquest servei, el recurs s'ha de pujar al portal d'Open Data BCN amb un format i codificació adequats. Quan es puja un CSV a la plataforma, es crea de manera interna una taula a base de dades d'aquest recurs. Aquest emmagatzemament dins de CKAN s'anomena datastore. L'API del datastore ens permet fer consultes directament sobre aquestes taules.

Cal destacar que la utilització de l'API de consulta és a nivell de recurs CSV individual, no de dataset del catàleg. Els recursos amb API CKAN habilitada es poden seleccionar mitjançant el filtre del catàleg 'API CKAN disponible'.

Només hi ha dos endpoints comuns per a tots els CSV de la plataforma que permeten cercar dins del recurs en funció dels criteris de cerca afegits com a paràmetres a la crida o fent una consulta SQL:

• datastore_search: https://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search
• datastore_search_sql: https://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search_sql

Els endpoints són únics per a tots els recursos de la plataforma, per a fer una consulta sobre un recurs concret, hem de definir com a paràmetre o dins de la consulta l'ID del recurs sobre el que volem consultar.

Per exemple, per a fer una consulta sobre el recurs de l'any 2017 del dataset '50 Noms més freqüents dels habitants de Barcelona per dècada de naixement i sexe' utilitzaríem el següent URL: https://opendata-ajuntament.barcelona.cat/data/api/action/datastore_search?resource_id=51b78472-cd11-4426-912a-1d26240491e7

2.2.1 Com s'obté l'ID del recurs

L'URL del recurs, que és del tipus https://opendata-ajuntament.barcelona.cat/data/ca/dataset/nom/resource/identificador ja l'incorpora directament.

identificador és l'ID del recurs i, tan sols hem de navegar pel portal i seleccionar el recurs en qüestió per a obtenir l'ID a partir de l'URL.

2.2.2 Com trobar els noms dels camps dels recursos

Els noms del camps del recursos es poden consultar, sempre que estiguin habilitats, al desplegable Definició de camps o a la previsualització. Altrament, caldrà descarregar el recurs.

2.2.3 datastore_search

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

Paràmetres d'entrada:

• resource_id (string - obligatori) - id del recurs CSV sobre el que volem cercar
• filters (diccionari) - condicions que s’han de complir. Exemple: {“direccio”: “%carrer%”}
• q (string o diccionari) - cerca en full text. Es pot especificar un string per a cercar-lo a tots els camps o un diccionari per a cercar a camps concrets, p.e: {“key1”: “a”, “key2”: “b”}
• distinct (boolean) - retorna sols les files diferents
• plain (boolean) - tracta la consulta com si fos text pla
• language (string) - llenguatge de la consulta en full text
• limit (int) - número màxim de resultats. Per defecte retorna 100 resultats.
• offset (int) - número de resultats que s’han de saltar. Útil per fer una paginació de resultats.
• fields (string) - llistat de camps que s’inclouràn a la resposta. Per defecte retorna tots els camps amb el mateix ordre que al CSV
• sort (string) - noms dels camps per els que ordenar separats per comes: “nom, codi desc”

Exemple de crida a datastore_search

Volem cercar les fonts públiques de beure que es troben al carrer Mallorca. Per fer-ho, primer necessitem conèixer l'ID del recurs i després el nom del camp sobre el que volem cercar. Aquesta informació la podem obtenir de la pàgina de previsualització del recurs al portal.

Paràmetres d'entrada:

• resource_id: És l'ultima part de l'URL del recurs (21f7a4df-2e73-45f8-8c6d-0b3db8c21527)
• q: El consultem als camps de la previsualització del recurs {“INVENTARI_CARRER” : “Mallorca”}

URL de crida:

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}
Pujar

2.2.4 datastore_search_sql

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

Les consultes d'aquest tipus tenen un timeout limitat per tal de que no es produeixin atacs DOS no intencionats.

Paràmetres d'entrada:

• sql (string) - SELECT que es vol executar sobre les dades. El nom de la taula sobre la que es fa la consulta és l’ID del recurs.

Exemple de crida a datastore_search_sql

Volem cercar a les fonts públiques de beure les que es troben al carrer Mallorca. Necessitem conèixer l'ID del recurs (que és el nom de la taula) i el nom del camp per el que volem filtrar.

Paràmetres d'entrada:

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

URL de crida:

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 pròpies de l'Ajuntament

Les APIs pròpies són les proporcionades per els equips que gestionen les fonts d'informació. Aquestes APIs s'enllacen des del Portal d'Open Data BCN però no es mantenen o validen des del mateix equip que gestiona el portal. Al portal es tracten com un recurs més, com si fos un enllaç a un fitxer CSV o RDF.

A hores d'ara, al catàleg Open Data BCN s'ofereixen els següents recursos de tipus API:

• Geoserveis WMS i WMTS de la Infraestructura de Dades Espacials de l'Ajuntament de Barcelona

3. Tokens

Els tokens d'accés contenen les credencials de seguretat per iniciar una sessió, podent identificar un usuari, grups, permisos i en alguns casos, una aplicació concreta. En el cas d'Open Data BCN, s'identifica l'usuari.

Podeu trobar aquí tota la informació referent a l'obtenció i l'ús.

Tanmateix, el filtre del catàleg anomenat Token requerit permet seleccionar els datasets que contenen recursos amb aquesta opció habilitada, els quals mostren al botó de 'Descarregar' una icona amb forma de clau.

4. Limitació del nombre d'accessos a datasets i recursos

Per tal d'oferir la màxima disponibilitat i qualitat del servei, s'aplicaran els límits d'accés detallats a continuació a les cerques on-line de datasets i a les descàrregues de recursos:

• Datasets:
  Cerca on-line: 30 peticions/minut

• Recursos:
  Descàrrega: 1 petició/segon o 60 peticions/minut
  Accés via API: 30 peticions/minut

Aquests límits són susceptibles de modificació per tal d'oferir sempre el millor servei als usuaris.
En el cas de que s'arribi el límit d'accessos, s'indicarà retornant el codi 503.

5. GITHUB de l'Ajuntament de Barcelona

Al GITHUB de l’Ajuntament de Barcelona es publiquen les extensions de CKAN i Drupal que s'han desenvolupat per implementar noves funcionalitats del portal:

• CKAN:
• odatabcn: personalització en l'aparença del catàleg i altres funcionalitats.
• federagobes: generació del fitxer en format .RDF del catàleg de l'Open Data BCN per federar els datasets amb el portal datos.gob.es.
• Drupal:
• opendata_tokens: generació, emmagatzematge i regeneració dels tokens d'accés.

6. Programació

• Com transformar un arxiu d'extensió .csv inicialment en format WIDE en un arxiu en format LONG.

Descrivim amb un exemple com es pot transformar un arxiu publicat en format WIDE a un publicat en format LONG en llenguatge de programació Python.

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

#Per 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. Enllaços d'interés

El portal de dades obertes de la Unió Europea té una secció de Desenvolupadors on ofereix enllaços a clients per a l'API de CKAN:

• Python
• Javascript
• Java
• PHP
• Ruby

8. Altres

• Al portal Open Data BCN disposem d'un apartat de FAQs amb preguntes freqüents sobre l'Open Data BCN i l'ús de les dades
• Podeu enviar qualsevol dubte o consulta a través de Contacteu-nos