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.

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:

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:

• Activitats:

  http://opendata.amb.cat/activitats/search

• Notícies:

  http://opendata.amb.cat/noticies/search

• Municipis:

  http://opendata.amb.cat/municipis/search

• Publicacions:

  http://opendata.amb.cat/publicacions/search

• Estudis:

  http://opendata.amb.cat/estudis/search

• Estudis de mobilitat:

  http://opendata.amb.cat/estudis/search/?tipus_estudi=Mobilitat

• Estudis metropolitans:

  http://opendata.amb.cat/estudis/search?rows=15&tipus_estudi=metropolitans

• Estudis de sostenibilitat:

  http://opendata.amb.cat/estudis/search?rows=15&tipus_estudi=sostenibilitat

• Projectes i obres:

  http://opendata.amb.cat/projectes_obres/search

• Infraestructures:

  http://opendata.amb.cat/infraestructures/search

• Tràmits:

  http://opendata.amb.cat/tramits/search

• Projectes de cooperació:

  http://opendata.amb.cat/cooperacio/search

• Equipaments:

  http://opendata.amb.cat/equipaments/search

• Platges:

  http://opendata.amb.cat/equipaments_platja/search

• Parcs:

  http://opendata.amb.cat/equipaments/search?subambit=Parcs

• Plans urbanístics:

  http://opendata.amb.cat/pla_urbanistic/search

• Datasets:

  http://opendata.amb.cat/datasets/search

• Perfil del contractant - procediments oberts:

  http://opendata.amb.cat/perfil_contractant_procediment_obert/search

• Perfil del contractant - procediments negociats:

  http://opendata.amb.cat/perfil_contractant_procediment_negociat/search

• Activitats del taxi:

  http://opendata.amb.cat/activitats_taxi/search

• Notícies del taxi:

  http://opendata.amb.cat/noticies_taxi/search

• Notes de premsa:

  http://opendata.amb.cat/notes_premsa/search

• Dades meteorològiques de les platges:

  http://opendata.amb.cat/dades_meteorologiques/search

• Dades de l'estat de les platges:

  http://opendata.amb.cat/dades_estat_platja/search

• Instal·lacions de la platja del Prat de Llobregat

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_prat

• Instal·lacions de la platja de Montgat

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_montgat

• Instal·lacions de la platja de Gavà

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_gava

• Instal·lacions de la platja de Castelldefels

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_castelldefels

• Instal·lacions de la platja de Barcelona

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_barcelona

• Instal·lacions de la platja de Badalona

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_badalona

• Instal·lacions de la platja de Viladecans

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_viladecans

• Instal·lacions de la platja de Sant Adrià de Besòs

  http://opendata.amb.cat/serveis_platges/search?platja_key=platja_sadria

• Serveis per a empreses:

  http://opendata.amb.cat/serveis_empreses/search

• Prestador de serveis:

  http://opendata.amb.cat/prestador_serveis/search

• Workshops del PDU:

  http://opendata.amb.cat/workshops_pdu/search

• Vehicles del taxi:

  http://opendata.amb.cat/vehicles_taxi/search

• Directori del taxi:

  http://opendata.amb.cat/directori_taxi/search

• Parades de taxi:

  http://opendata.amb.cat/parades_taxi/search

• Punts d'interès:

  http://opendata.amb.cat/punts_interes/search

• Serveis dels parcs:

  http://opendata.amb.cat/serveis_parcs/search

• Ocupació pública:

  http://opendata.amb.cat/ocupacio_publica/search

• Projectes oberts:

  http://opendata.amb.cat/projectes_oberts/search

• Publicacions taxi:

  http://opendata.amb.cat/publicacions_taxi/search

• Punts serveis:

  http://opendata.amb.cat/punts_serveis/search

• Serveis platges:

  http://opendata.amb.cat/serveis_platges/search

• Workshops oberts:

  http://opendata.amb.cat/workshops_oberts/search

• Workshops passatges:

  http://opendata.amb.cat/workshops_passatges/search

• Contactes:

  http://opendata.amb.cat/contactes/search

• Menú site:

  http://opendata.amb.cat/menu_site/search

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:

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

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:

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:

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:

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

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

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:

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:

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

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

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:

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

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ó, ...).

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:

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

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:

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.

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