API REST Zaragoza (v2)

Acceso a la API REST

Introducción


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

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

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