AMB - Àrea Metropolitana de Barcelona - www.amb.cat

Documentació de l'API Opendata

Tornar

Sobre el portal Opendata de l'AMB

La finalitat d'aquest portal és la d'oferir públicament un conjunt de dades sobre l'AMB per tal de permetre la seva explotació mitjançant la utilització de la pròpia API.

En aquesta pàgina s'explicarà com utilitzar l'API d'opendata per cercar i recuperar les dades de les diferents fonts disponibles dins el portal de l'AMB.

Estructuració de la informació

El portal d'Opendata ofereix la informació agrupada per col·leccions (collections). Per cada col·lecció es podrà realitzar cerques pels seus camps o utilitzar la cerca de text lliure. El resultat de les consultes es podran obtenir en diferents formats per tal de facilitar la seva utilització. Per accedir a les dades d'una col·lecció es farà mitjançant la URL:

http://opendata.amb.cat/{{collection}}/search

on {{collection}} serà el nom de la col·lecció. Un cop hi accedim ens mostrarà totes les dades disponibles per la col·lecció.
Actualment es disposen dades sobre les següents col·leccions:

Cada col·lecció està associada a un esquema (schema) on es defineixen els tipus de camps i l'estructura que tindran els seus continguts. Per consultar l'esquema d'una col·lecció es farà mitjançant la URL:

http://opendata.amb.cat/{{collection}}/schema

Si, per exemple, consultem l'esquema de notícies obtindrem la següent informació:

{ num: 1, count: 1, items: { _id: "54533d61e57214ab3e8411cc", collectionName: "noticies", schema: { _id: "String", text: "String", entradeta: "String", imatge_principal: { imatge_principal_alternatiu: "String", imatge_principal_peu: "String", imatge_principal_nom: "String", imatge_principal_fitxer: "String", imatge_principal_autor: "String" }, subambit: "String", autor: "String", destacat_titol: "String", tema: "String", lang: "String", ambit: "String", enllacos_relacionats: [ { enllacos_relacionats_descripcio: "String", enllacos_relacionats_extern: "String", enllacos_relacionats_intern: "String", enllacos_relacionats_nom: "String" } ], titol: "String", documents_relacionats: [ { documents_relacionats_fitxer: "String", documents_relacionats_nom: "String", documents_relacionats_descripcio: "String" } ], destacat_entradeta: "String", imatges_relacionades: [ { imatges_relacionades_peu: "String", imatges_relacionades_autor: "String", imatges_relacionades_fitxer: "String", imatges_relacionades_nom: "String", imatges_relacionades_alternatiu: "String" } ], video: { video_alternatiu: "String", video_codi_youtube: "String", video_autor: "String", video_fitxer: "String", video_nom: "String" }, data_noticia: "Date", date_updated: "Date" }, date_updated: "2014-10-31T07:42:25.263Z" } }

Cerques sobre les col·leccions

Cerques específiques per camps

L'API permet realitzar cerques pels diferents camps d'una col·lecció. Les crides es faran de la següent manera:

http://opendata.amb.cat/{{collection}}/search?{{camp1}}={{valor}}&{{camp2}}={{valor}}&{{camp3}}={{valor}}

on els camps camp1, camp2, camp3 seran els noms dels camps de la col·lecció. Si, per exemple, volem filtrar els resultats per el camp títol de notícies, farem la següent consulta:

http://opendata.amb.cat/noticies/search?titol=metropolitans

Si el camp que necessitem filtrar és un camp anidat (es troba dins d'un altre node), el nom del camp serà la concatenació de tots els seus nodes pares amb un "." i el nom del propi camp. Si, per exemple, necessitem cercar per el camp enllacos_relacionats_nom farem la següent crida:

http://opendata.amb.cat/noticies/search?enllacos_relacionats.enllacos_relacionats_nom=premsa&titol=metropolitans

Cerques per text lliure

També és possible realitzar cerques per text lliure pels camps de tipus text de cada col·lecció. Aquesta cerca es fa utilitzant el camp q en la URL. Per exemple, la següent consulta cercarà el mot mobilitat dins els camps de la col·lecció:

http://opendata.amb.cat/noticies/search?q=mobilitat

Aquest tipus de cerca la podrem combinar amb la cerca específica per els camps. Un exemple seria el següent:

http://opendata.amb.cat/noticies/search?enllacos_relacionats.enllacos_relacionats_nom=premsa&titol=metropolitans&q=mobilitat

Cerques per camps de tiups Date

Les cerques per els camps de tipus Date es fan seguint la nomenclatura dd/mm/yyyy. Un exemple seria la següent crida:

http://opendata.amb.cat/noticies/search?enllacos_relacionats.enllacos_relacionats_nom=premsa&titol=metropolitans&q=mobilitat&data_noticia=25/09/2014

També es permet realitzar cerques per rang de dates utilitzant els símbols <,>,= dins el valor del camp. Si, per exemple, necessitem recuperar les notítices on la seva data ha de ser més grant que la 25/09/2014, farem la següent crida:

http://opendata.amb.cat/noticies/search?enllacos_relacionats.enllacos_relacionats_nom=premsa&titol=metropolitans&q=mobilitat&data_noticia=>25/09/2014

Paginació

Per defecte, en totes les cerques que realitzem, l'aplicació ens retorna els resultats agrupats en 500 elements. Si ens fixem en la capçalera dels resultats d'una cerca podem identificar els diferents elements:
num: Número d'elements que es mostren en la cerca.
count: Número total d'elements que hi ha en la cerca.
start: Primer element del llistat que es mostra

Per poder aplicar la paginació en l'api haurem d'indicar el número d'elements que volem recuperar (rows) i a partir de quin element volem recuperar els resultats (start):

http://opendata.amb.cat/parades_autobus_cetramsa/search?rows=500&start=1000

Ordenació

L'api permet odrdenar els resultats per un camp en concret de forma ascendent o descendent. En la crida haurem d'especificar per quin camp volem ordenar i la direcció sort={{camp}},{{asc/desc}}.

http://opendata.amb.cat/noticies/search?titol=metropolitans&sort=autor,asc

Retornar camps específics en la resposta

L'api permet filtrar els camps retornats en els ítems de la resposta. D'aquesta manera podem reduïr de manera considerable la informació de la cerca. Si, per exemple, necessitem només els camps entradeta i autor, ho farem mitjançant el paràmetre getFields:

http://opendata.amb.cat/noticies/search?q=mobilitat&getFields=entradeta,autor

Aquesta funcionalitat només és vàlida per als camps de primer nivell, és a dir, aquells que provenen directament de l'arrel de l'ítem.

Cerca per diferents valors en un mateix camp

Podem realitzar cerques per un camp on el seu valor coincideixi amb algun dels especificats dins el camp de la cerca. Per poder-ho fer hem de separar cada valor per el símbol |:

http://opendata.amb.cat/activitats/search?subambit=Residus|Sostenibilitat|Aigua

En l'exemple ens cercarà tots aquells continguts on el camp subambit coincideixi amb algun dels valors de la query.
Hem de tenir en compte que els valors del paràmetre han de ser exactes als valors que cerquem (han de coincidir majúscules, accents, signes de putnuació, ...).

Formats de les dades

Per defecte l'API serveix els resultats en format JSON. També és possible obtenir la informació de les cerques en format XML, KML, KMZ i CSV. Les crides es faran de la següent manera:

http://opendata.amb.cat/{{collection}}/search/{{format}}?{{camp1}}={{valor}}&{{camp2}}={{valor}}&{{camp3}}={{valor}}

on el camp {{format}} serà el tipus de format que necessitem. Una cerca per format XML seria de la següent manera:

http://opendata.amb.cat/noticies/xml/search?enllacos_relacionats.enllacos_relacionats_nom=premsa&titol=metropolitans&q=mobilitat

Altres utilitats de cerca

Obtenir els camps relacionats

Algunes col·leccions tenen continguts que estan relacionats amb continguts d'altres col·leccions. Per exemple, la col·lecció d'activitats té continguts relacionats amb equipaments o publicacions. Per poder veure aquesta relació hem d'afegir a la query el paràmetre getRelatedArticles=true:

http://opendata.amb.cat/activitats/search?tema=residus&getRelatedArticles=true

Amb la cerca anterior obtindrem els continguts relacionats de cada ítem. Si ens fixem en el següent codi veurem com ens apareix el camp related_articles on ens indicarà que un contingut té una relació amb dos continguts de publicacions i 8 continguts de equipaments_platja.

related_articles: { publicacions: [ { articleId: "754258" }, { articleId: "754270" } ], equipaments_platja: [ { articleId: "421174" }, { articleId: "452516" }, { articleId: "452423" }, { articleId: "493853" }, { articleId: "421165" }, { articleId: "452101" }, { articleId: "452113" }, { articleId: "452451" } ] }

Si volguéssim veure un contingut relacionat hauríem de cercar pel camp articleId dins la col·lecció corresponent.

Tanca