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

Documentación de la API Opendata

Volver

Sobre el portal Opendata del AMB

La finalidad de este portal es ofrecer públicamente un conjunto de datos sobre el AMB para permitir su explotación mediante la utilización de la propia API.

En esta página se explica cómo utilizar la API Opendata para buscar y recuperar datos de las diferentes fuentes disponibles dentro del portal del AMB.

Estructuración de la información

El portal Opendata ofrece la información agrupada por colecciones(collections). Para cada colección se podrán realizar búsquedas por sus campos o utilizar la búsqueda de texto libre. El resultado de las consultas se podrá obtener en diferentes formatos para facilitar su utilización. Para acceder a los datos de una colección deberá hacerse por medio de la URL:

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

donde {{collection}} será el nombre de la colección. Una vez hayamos accedido, se mostrarán todos los datos disponibles para la colección.
Actualmente se dispone de datos sobre las siguientes colecciones

Cada colección está asociada a un esquema (schema) donde se definen los tipos de campos y la estructura que tendrán sus contenidos. La consulta del esquema de una colección se hará mediante la URL:

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

Si, por ejemplo, consultamos el esquema de noticias obtendremos la siguiente información:

{ 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" } }

Búsquedas sobre las colecciones

Búsquedas específicas por campos

La API permite realizar búsquedas por los diferentes campos de una colección. Las llamadas se harán de la siguiente forma

http://opendata.amb.cat/{{collection}}/search?{{campo1}}={{valor}}&{{campo2}}={{valor}}&{{campo3}}={{valor}}

donde los campos campo1, campo2, campo3 serán los nombres de los campos de la colección. Si, por ejemplo, queremos filtrar los resultados por el campo titol de noticies, haremos la siguiente consulta:

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

Si el campo que necesitamos filtrar es un campo anidado (está dentro de otro nodo), el nombre del campo será la concatenación de todos sus padres con un "." y el nombre del propio campo. Si, por ejemplo, necesitamos buscar por el campo enllacos_relacionats_nom haremos la siguiente llamada:

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

Búsquedas por texto libre

También es posible realizar búsquedas por texto libre para los campos tipo texto de cada colección. Esta búsqueda se realiza utilizando el campo q en la URL. Por ejemplo, la siguiente consulta buscará la palabra mobilitat dentro de los campos de la colección:

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

Este tipo de búsqueda se podrá combinar con la búsqueda específica por campos. Un ejemplo sería el siguiente

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

Búsquedas por campos de tipo Date

Las búsquedas por campos de tipo Date se realizan siguiendo la nomenclatura dd/mm/yyyy. Un ejemplo sería la siguiente llamada:

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

También se pueden realizar búsquedas por rango de datos utilizando los símbolo <, >, = dentro del valor del campo. Si, por ejemplo, necesitamos recuperar las noticias en las que la fecha debe ser mayor que 25/09/2014, realizaremos la siguiente llamada:

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

Paginación

Por defecto, en todas las búsquedas que realizamos, la aplicación nos retorna los resultados agrupados en 500 elementos. Si nos fijamos en la cabecera de los resultados de una búsqueda podemos identificar los distintos elementos: num: Número de elemento que se muestran en la búsqueda.
count: Número total de elementos que hay en la búsqueda.
start: Primer elemento de la relación que se muestra

Para poder aplicar la paginación en la API deberemos indicar el número de elementos que queremos recuperar (rows) y a partir de qué elemento queremos recuperar los resultados (start):

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

Ordenación

La API permite ordenar los resultados por un campo en concreto de forma ascendente o descendente. En la llamada deberemos especificar por qué campo queremos ordenar y el sentido sort={{camp}},{{asc/desc}}.

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

Retorno de campos específicos en la respuesta

La API permite filtrar los campos retornados en los ítems de la respuesta. De esta manera podemos reducir considerablemente la información de la búsqueda. Si, por ejemplo, necesitamos sólo los campos entradeta y autor, lo haremos por medio del parámetro getFields:

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

Esta funcionalidad solo es válida para los campos de primer nivel, es decir, aquellos que provienen directamente de la raíz del ítem.

Búsqueda por diferentes valores de un mismo campo

Podemos realizar búsquedas por un campo cuyo valor coincida con alguno de los especificados dentro del campo de la búsqueda. Para poder hacerlo tenemos que separar cada valor por el símbolo |:

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

En el ejemplo buscará todos los contenidos donde el campo subambit coincida con algunos de los valores de la query.
Tenemos que tener en cuenta que los valores del parámetro tienen que ser exactos a los valores que buscamos (tienen que coincidir mayúsculas, acentos, signos de puntuación, ...).

Formatos de los datos

Por defecto la API sirve los resultados en formato JSON. También es posible obtener la información de las búsquedas en formato XML, KML, KMZ i CSV. Las llamadas se harán como sigue:

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

donde el campo {{format}} será el tipo de formato que necesitemos. Una búsqueda para formato XML sería de la siguiente manera :

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

Otras utilidades de búsqueda

Obtener los campos relacionados

Algunas colecciones tienen contenidos que están relacionados con contenidos de otras colecciones. Por ejemplo, la colección de actividades tiene contenidos relacionados con equipamientos o publicaciones. Para poder ver esta relación tenemos que añadir a la query el parámetro getRelatedArticles=true:

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

Con la búsqueda anterior obtendremos los contenidos relacionados de cada ítem. Si nos fijamos en el siguiente código veremos como nos aparece el campo related_articles donde nos indicará que un contenido tiene una relación con dos contenidos de publicacions y 8 contenidos 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 quisiéramos ver un contenido relacionado tendríamos que buscar por el campo articleId dentro de la colección correspondiente.

Tanca