API REST Zaragoza (v2)

La API REST Zaragoza es un servicio pensado para reutilizadores que pone a su disposición los diferentes conjuntos de datos que publica el Ayuntamiento de Zaragoza. Ofrece diferentes formatos y operaciones para la consulta de los mismos. Incluye el API de Catálogo y el API de datos.
Acceso a la API REST

La versión actual de la API REST del Ayuntamiento de Zaragoza es la versión 2. La anterior versión seguirá estando disponible pero no recibirá nuevas actualizaciones.

Primeros pasos

  • Darse de alta en el servicio. Este alta es opcional pero tiene una serie de ventajas que se describen a continuación:
    • Podrá dar de alta las urls que está utilizando para que nos podamos poner en contacto con usted antes de realizar modificaciones y conozcamos sus implicaciones.
    • Dar de alta las aplicaciones que desarrolla utilizando nuestros datos. Aparecerán publicadas en el Catálogo de aplicaciones.
    • Modificar sus datos de usuario/usuaria, así como obtener su apikey en caso de que la necesite haciendo click en Modificar datos.
    • Recibir Novedades y nuevos conjuntos de datos públicados.
  • Consultar los diferentes formatos en los que publicamos los conjuntos de datos.
  • Acceder a nuestro Catálogo de Datos Abiertos y buscar el conjunto de datos que le interese.
  • Acceder a la API REST a través servicio interactivo Swagger y realice consultas de prueba de los diferentes conjuntos de datos directamente sobre la misma.
  • Consultar varios ejemplos en nuestro Github.

¿Qué es Swagger?

Swagger es una herramienta web para describir, producir, consumir y visualizar servicios REST.
Su ventajas son la actualización de la documentación del sistema conforme se actualice el servicio, de modo que la documentación de los métodos, parámetros y modelo esté integrada en el código del servicio permitiendo que las APIs estén siempre sincronizadas. Y su facilidad de uso.

Con este servicio se pretende ofrecer interacción directa con nuestra API y los diferentes conjuntos de datos a través de una interfaz amigable.

Interacción y operaciones de la API REST Zaragoza

Se puede consultar:

  • Descripción sobre la operación.
  • Formatos de respuesta.
  • Parámetros a utilizar.
  • Códigos HTTP de respuesta.
  • Pruebas Se pueden ejecutar operaciones mostrándose el resultado.

Formatos de respuesta

Los conjuntos de datos públicados en la API REST Zaragoza pueden obtenerse en diferentes formatos.

Si se accede a un recurso de la API a través del navegador y este tiene asociada una visualización en HTML se redirigirá a dicha visualización.

Hay dos opciones para indicar el tipo de respuesta que se desea:

  • Mediante el parametro 'Accept' en los headers de la petición:
    Ejemplo: Accept:application/rdf+xml
  • Indicando el formato mediante su extensión en la petición:
    Ejemplo: https://www.zaragoza.es/sede/servicio//turismo/restaurante.rdf
Formato Header 'Accept' Extensión de formato
JSON application/json .json
GeoJSON application/geo+json .geojson
XML application/xml .xml
CSV text/csv .csv
JSONLD application/ld+json .JSONLD
RDF application/rdf+xml .rdf
Turtle application/x-turtle .turtle
N3 application/rdf+n3 .n3

Párametros API

La API ofrece una serie de párametros para personalizar la petición obteniendo mejores resultados:

Parámetro Descripción
fl Listado de atributos separados por comas que se desea obtener en la respuesta.
srsname Sistema de referencia preferido para obtener las coordenadas de geolocalización:
  • utm30 (por defecto)
  • wsg84 (sistema utilizado por Google)
  • etrs89
start Posicion del primer registro que se obtendra a partir del total de registros totalCount de la petición.
rows Número de filas/registros que se obtendrán de la petición.
sort Ordenación ascendente asc o descentente desc de los registros obtenidos a partir del atributo dado previamente.
q Consulta mediante FIQL para permitir filtros y condiciones en las consultas utilizando una sintaxis con URIs amigables.
point Punto (coordenadas) a partir del cual se desea obtener los registros de forma circunferencial a dicho punto mediante una distancia dada. Por defecto 500 metros.
distance Distancia (en metros) a la que se encuentran los resultados obtenidos a través de paramétro point. Por defecto 500 metros.
Ejemplo de petición con parámetros API

Consulta: Nombre y teléfono de los 5 restaurantes más cercanos a las coordenadas wsg84 de la Basílica de Ntra. Sra. del Pilar en un radio de 250 metros en formato json y ordenados de forma descendente por el nombre.

GET https://www.zaragoza.es/sede/servicio/restaurante.json?fl=title,tel&srsname=wgs84&rows=5&sort=title%20desc&q=title==A*&point=-0.878516,41.656772&distance=250
Puedes consultar otros ejemplos desde nuestro repositorio de GitHub.

Códigos HTTP de Respuesta

HTTP Status Code Reason
200 Operación realizada correctamente
304 Registro no modificado desde la última petición, soporte ETAG/If-None-Match y Last_Modified/If-Modified-Since
404 En la respuesta se obtiene una descripción del error
400 En la respuesta se obtiene una descripción del error
500 Error en la petición

API de Catálogo de conjuntos de datos

Acceso a la API de catálogo que describe los conjuntos de datos que configuran el mismo:

GET https://www.zaragoza.es/sede/servicio/catalogo/api.json

Ejemplos de peticiones

Vistos los formatos soportados, los diferentes conjuntos de datos, códigos de respuesta y atributos normalizados pasamos a visualizar un par de ejemplos en los que se realiza una petición de listado de registros y otra del detalle de uno concreto con sus respuestas. En nuestro repositorio de github zaragoza-sedeelectronica se pueden encontrar ejemplos más complejos tanto de peticiones como de ejemplos HTML.

Ejemplo de listado

Consulta: Listado de 100 monumentos con las propiedades: title, horario y geometry (coordenadas en utm30) en JSON y XML.

GET https://www.zaragoza.es/sede/servicio/monumento.[json,xml]?rows=100&fl=title,horario,geometry

{
    "totalCount": 175,
    "start": 0,
    "rows": 100,
    "result": [{
            "title": "Museo del Foro de Caesaraugusta",
            "horario": "Cerrado hasta nuevo aviso. [...]",
            "geometry": {
                "type": "Point",
                "coordinates": [676934.75, 4613880.67]
            }
        }, {
            "title": "Centro de Historias de Zaragoza. Antiguo Convento de San Agustín",
            "horario": "Martes a sábado de 10 a 14h y 17 a 21h [...]",
            "geometry": {
                "type": "Point",
                "coordinates": [677408.53, 4613410.17]
            }
        },
        ...
    ]
}
<resultado>
    <totalCount>175</totalCount>
    <start>0</start>
    <rows>100</rows>
    <result>
        <monumento>
            <title>Museo del Foro de Caesaraugusta</title>
            <horario>
                Cerrado hasta nuevo aviso. [...]
            </horario>
            <geometry>
                <type>Point</type>
                <coordinates>676934.75,4613880.67</coordinates>
            </geometry>
        </monumento>
        <monumento>
            <title>
                Centro de Historias de Zaragoza. Antiguo Convento de San Agustín
            </title>
            <horario>
                Martes a sábado de 10 a 14h y 17 a 21h [...]
            </horario>
            <geometry>
                <type>Point</type>
                <coordinates>677408.53,4613410.17</coordinates>
            </geometry>
        </monumento>
    </result>
</resultado>

Ejemplo de detalle

Consulta: Detalle del monumento con identificador 2: Museo del Foro de Caesaraugusta en JSON y XML

GET https://www.zaragoza.es/sede/servicio/monumento/2.[json,xml]

{
    "id": 2,
    "title": "Museo del Foro de Caesaraugusta",
    "description": "El Foro es el centro neurálgico de la vida en una ciudad romana: es el principal lugar de reunión donde se desarrolla la vida político-administrativa, económica y religiosa. El recinto forense se organiza a partir de un gran espacio abierto, rodeado de uno o varios pórticos circundantes, en torno al cual se distribuyen los edificios más significativos: la Curia, dedicada a usos políticos y administrativos; la Basílica, donde se resuelven asuntos jurídicos; y el Templo principal de la ciudad. Junto a ellos están las tabernas, locales dedicados a usos comerciales, y seguramente habría otros edificios relacionados con la administración (archivos, acuñación de moneda, etc.). Este conjunto monumental se completa con diversos elementos ornamentales (aras para sacrificios, estatuas honoríficas, arcos de triunfo, etc.) de los que en el caso de Caesaraugusta conocemos algunos a través de su representación en las monedas de la ciudad.",
    "estilo": "romano",
    "address": "Plaza de la Seo, 2",
    "horario": "Cerrado hasta el domingo 15 de marzo.\r\n\r\nMartes a sábado de 10 a 14h y 17 a 21h\r\nDomingos 10 a 14.30h \r\nLunes cerrado\r\n\r\nMedia hora antes del cierre se interrumpe la entrada.",
    ...
}
<monumento>
    <id>2</id>
    <title>Museo del Foro de Caesaraugusta</title>
    <description>
        El Foro es el centro neurálgico de la vida en una ciudad romana: es el principal lugar de reunión donde se desarrolla la vida político-administrativa, económica y religiosa. El recinto forense se organiza a partir de un gran espacio abierto, rodeado de uno o varios pórticos circundantes, en torno al cual se distribuyen los edificios más significativos: la Curia, dedicada a usos políticos y administrativos; la Basílica, donde se resuelven asuntos jurídicos; y el Templo principal de la ciudad. Junto a ellos están las tabernas, locales dedicados a usos comerciales, y seguramente habría otros edificios relacionados con la administración (archivos, acuñación de moneda, etc.). Este conjunto monumental se completa con diversos elementos ornamentales (aras para sacrificios, estatuas honoríficas, arcos de triunfo, etc.) de los que en el caso de Caesaraugusta conocemos algunos a través de su representación en las monedas de la ciudad.
    </description>
    <estilo>romano</estilo>
    <address>Plaza de la Seo, 2</address>
    <horario>
        Cerrado hasta nuevo aviso. Martes a sábado de 10 a 14h y 17 a 21h Domingos 10 a 14.30h Lunes cerrado Media hora antes del cierre se interrumpe la entrada.
    </horario>
</monumento>

Documentación adicional

Para algunos conjuntos de datos se establece un documento de ayuda individual con el objetivo de detallar las operaciones y métodos que se encuentran disponibles:

Enlaces de interés