Esteu aquí

Desenvolupadors


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 són interfícies que especifiquen com els diferents components de programes informàtics haurien d'interaccionar. Es tracta d'un conjunt de funcions i procedimients oferts per ser utilitzats per un altre programa per tal d'interactuar amb el programa en qüestió. Podem distingir tres tipus d'APIs oferides al portal Open Data BCN:

  • APIs 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 ofertades per les fonts d'informació i desenvolupades a mida

Tant l'API de gestió del catàleg de dades obertes, 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. Per a aquests mètodes, es pot incloure el paràmetre callback per a que la resposta es retorni en format JSONP per al seu ús amb Javascript.

2.1. APIs de gestió del catàleg

Es tracta de l'API oferida pel producte CKAN per tal de gestionar el catàleg de datasets. A aquesta API s'accedeix des de la URL http://opendata-ajuntament.barcelona.cat/data/api/action/, a la que s'ha d'afegir el nom del mètode al que volem accedir.

Aquesta API pot tenir interès per als ciutadans per a conèixer quina informació es troba disponible al portal d'Open Data BCN i els datasets que es van afegint. Es pot accedir mitjançant l'API a la mateixa informació accessible al web d'Open Data BCN.

La crida a aquests mètodes no requereix l'ús d'un token ni cap altre mètode d'identificació: són mètodes públics.

Exemples d'aquests mètodes són els següents:

  • 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 d'un recurs

Podeu trobar exemples de consultes i el llistat complet de mètodes a la guia API de CKAN.

Pujar

2.2. APIs de consulta sobre recursos CSV

Es tracta de mètodes genèrics que permeten actuar sobre un recurs CSV concret. Per tal de que la plataforma oferti 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 l'utilització de l'API de consulta és a nivell de recurs CSV individual, no de dataset del catàleg. Actualment hi ha uns 1.000 recursos al catàleg d'Open Data BCN que es poden consultar amb aquesta API.

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:

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 el 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' utilitzariem la següent URL: http://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 la munta l'aplicació directament i és del tipus:
http://opendata-ajuntament.barcelona.cat/data/ca/dataset/nom/resource/identificador

on identificador és l'ID del recurs. Per tant, 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 al portal

Per a trobar els noms del camps al portal per tal de poder utilitzar l'API de consulta només hem d'anar a la previsualització del recurs CSV. Per exemple anem al recurs Fonts_201610.csv del dataset Fonts públiques de beure de Barcelona i ens fixem en les capçaleres de la previsualització del recurs: INVENTARI_NOM, INVENTARI_TIPUS, INVENTARI_CARRER, INVENTARI_NUMERO_CARRER, INVENTARI_COORDENADA_X, INVENTARI_COORDENADA_Y podrem fer les consultes tal i com s'explica en els aptartats següents.

2.2.3 datastore_search

URL: http://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 cridada 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 cridada:

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

2.2.4 datastore_search_sql

URL: http://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 cridada 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 cridada:

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

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

4. Altres

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