API REST Zaragoza (v2)
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
apikeyen 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:
|
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.
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:
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
JSON
{
"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]
}
},
...
]
}
XML
<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]
JSON
{
"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.",
...
}
XML
<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: