El Portal de Datos Abiertos del Ayuntamiento, a través de OGoov, ofrece una interfaz REST para acceder a la información del catálogo de datos, así como para acceder directamente a los datos.
API Rest Catálogo
El Catálogo de datos del Portal de Datos Abiertos del Ayuntamiento de Santander es gestionado por una instancia del sistema CKAN. Toda la documentación del API Rest de CKAN está disponible en el siguiente dirección: http://docs.ckan.org/en/latest/api/index.html. En la siguiente lista incluimos algunos ejemplos de utilización del API:
- Catálogo de datos simple: http://apicatalogo.santander.es/api/3/action/package_list
- Catálogo de datos ampliado: http://apicatalogo.santander.es/api/3/action/package_search
- Listado de grupos (sectores): http://apicatalogo.santander.es/api/3/action/group_list
- Listado de etiquetas: http://apicatalogo.santander.es/api/3/action/tag_list
- Toda la información de un conjunto de datos: http://apicatalogo.santander.es/api/3/action/package_show?id=[id_distribucion]
- Catalogo en formato DCAT/RDF: http://datos.santander.es/dcat
Todos estos ejemplos usan la última versión de la API, la número 3, por razones de compatibilidad hacia atrás las anteriores APIs también están disponibles y se aceptan llamadas de este tipo (devueltas por el API 1):
- Catálogo de datos simple: http://apicatalogo.santander.es/api/rest/dataset
- Listado de grupos (sectores): http://apicatalogo.santander.es/api/rest/group
- Listado de etiquetas: http://apicatalogo.santander.es/api/rest/tag
API Rest Datos (RTOD)
API Rest ofrecida por el middleware Real Time Open Data (RTOD). Sus servicios están divididos en dos grupos: operaciones sobre colecciones y recursos y operaciones del sistema.
El sistema también posee un control de extensiones sobre las peticiones HTTP, de tal manera que devolverá las representaciones y formatos deseados a través de las extensiones asociadas a los mimetypes reflejada en la petición. Por ejemplo: .atom, .json, .n3…
El punto de acceso al API Rest de datos está disponible en: http://datos.santander.es/api
A continuación se detallan las URLs de acceso a las operaciones así como la funcionalidad y parámetros de cada operación.
Operaciones sobre colecciones (Datasets)
/rest/collections
GET: Listado con la información de las colecciones del servidor de datos. La respuesta devolverá el identificador, nombre y autor de cada colección. El listado de colecciones aceptará paginación page= y número de elementos a devolver items= en el resultado. Un ejemplo de petición sería rest/collections?page=2&items=5. Las representaciones soportadas para esta operación serán XML y JSON.
/rest/collections/:collection
GET: Información de la colección identificada por :collection. La respuesta contendrá aquella información relativa a la configuración y los metadatos de la colección. Las representaciones soportadas para esta operación serán XML y JSON.
/rest/datasets/:collection
GET: La petición HTTP devuelve el listado con la representación de los recursos de una colección identificada por :collection. La respuesta mostrará el dataset asociado a la colección que se le pasa como parámetro.
- La petición HTTP acepta los siguientes parámetros:
-
- Para filtrar por parámetros mediante sintaxis Lucene query=
- Para paginar la respuesta page=
- Para especificar cuantos registros queremos que devuelva la API en cada página usaremos el parámetro items=. Nota Importante: Cualquier consulta realizada contra la API, si no se le especifica el parámetro items= solo va a devolver los 1000 primeros registros. Esto normalmente se indicara en los metadatos de paginación que aparecen en cabecera del fichero obtenido, pero hay algunos formatos como es el CSV, donde no se indica, y que puede dar lugar a obtención de ficheros parciales. Un ejemplo. La siguiente consulta devuelve la ejecución presupuestaria de gastos contables del ejercicio 2014. Es una consulta de mas de 1000 registros, pero si lo obtenemos directamente en CSV, por ningun lado nos damos cuenta que el fichero esta incompleto: http://datos.santander.es/api/rest/datasets/corriente_gastos.csv?query=ayto\:Ejercicio:2014. Si realizamos esta misma consulta en formato json, rápidamente nos damos cuenta en la información de cabecera que el fichero esta incompleta: http://datos.santander.es/api/rest/datasets/corriente_gastos.json?query=ayto\:Ejercicio:2014.
- Los resultados devueltos por la API siempre se ordenan por el campo dc:modified. Con el parámetro sort= podemos cambiar el modo de ordenación entre ascendente y descendente. Los valores que admite sort= son asc y desc. Nota: La API no permite establecer otro campo de ordenación. Si se necesita ordenar los resultados por otro campo, se tendrá que realizar el ordenamiento en el lado del cliente.
- Para indicar los campos o atributos de la colección que se quiere obtener usar data=campo1,campo2... Este parámetro es opcional, sino se especifica la API devolverá todos los campos/atributos de cada elemento de la colección. Se ha de tener en cuenta que los campos id y dc:modified son campos que se devuelven siempre, independientemente del uso de este parámetro.
- Peticiones con una única premisa pueden realizarse de manera query=dc\:identifier:12345 o -query=dc\:identifier:12345
- Peticiones con varias premisas deberán ir entre paréntesis query=(dc\:identifier:12345 OR dc\:identifier:54321)o -(query=dc\:identifier:12345 OR query=dc\:identifier:12345).
-
- Listado completo de recursos servidos en formato json: http://datos.santander.es/api/rest/collections.json
- Descripción de metadatos de un recurso: http://datos.santander.es/api/rest/collections/agenda_cultural.xml
- Obtener todos los datos de un recurso (en formato n3): http://datos.santander.es/api/rest/datasets/noticias_cultura.n3
- Listado de recursos en los que un metadato contiene un valor concreto: http://datos.santander.es/api/rest/datasets/oferta_empleo.json?query=ayto\:TipoOferta:Prensa
- Utilización de varias condiciones AND: http://datos.santander.es/api/rest/datasets/mercados_puestos.json?query=ayto\:idMercado:2%20AND%20ayto\:puesto:13
- Búsqueda de paradas de autobús por longitud y latitud: http://datos.santander.es/api/rest/datasets/paradas_bus.json?items=10&query=wgs84_pos\:lat:{429029 TO 429031} AND wgs84_pos\:long:{4810143 TO 4810147}
- Búsqueda de mediciones de Trafico entre fechas: http://datos.santander.es/api/rest/datasets/mediciones.json?query=(dc\:modified:{2015-08-01T12\:00\:00Z TO 2015-08-01T12\:15\:00Z})&sort=desc
- Paginación del resultado: http://datos.santander.es/api/rest/datasets/oferta_empleo.json?items=50&page=1
- Listado de items que NO cumplan una determinada condición: http://datos.santander.es/api/rest/datasets/oferta_empleo.json?query=-(ayto\:idNivelAcad:15%20OR%20ayto\:idNivelAcad:16)
- Usar el parámetro data para obtener solo determinados campos de una colección: http://datos.santander.es/api/rest/datasets/control_flotas_posiciones.json?data=ayto:servicio,geom2d:y,geom2d:x
Las representaciones soportadas para esta operación serán XML, Atom, JSON, RDF/XML, RDF/Turtle, RDF/N3, CSV y HTML.
Operaciones sobre recursos
/rest/datasets/:collection/:resource
GET: Representación del recurso con identificador :resource de la colección :collection. Las representaciones soportadas para esta operación serán XML, Atom, JSON, RDF/XML, RDF/Turtle, RDF/N3, CSV y HTML.
Ejemplo de petición válida:
- Obtener un recurso: http://datos.santander.es/api/datos/agenda_cultural/15903.n3
Representación de las respuesta de la interfaz Rest
Las peticiones realizadas a la interfaz Rest son respondidas en la representación que admite cada una de las operaciones y que deben ser definidas en la cabecera. Una petición a la operación /rest/info, será respondida en formato JSON, si en la cabecera se ha establecido el Content-Type del Accept como application/json.
Las representaciones soportadas por la interfaz Rest son las siguientes:
- XML: application/xml
- Atom: application/atom+xml
- JSON: application/json
- RDF/XML: application/rdf+xml
- RDF/TURTLE: text/turtle
- RDF/N3: text/n3
- CSV: text/csv
- HTML: text/html
NOTA: La pagina de códigos usada para generar los contenidos de la interfaz rest es UTF-8
CORS
Para todos aquellos Infomediarios que quieran consumir datos desde sus aplicaciones mediante peticiones Ajax, se encontrarán con la dificultad de que CORS no esta habilitado por defecto en la plataforma de Open Data de Santander. No obstante, la activación de CORS es posible, y con el fin de facilitar el trabajo de los desarrolladores, el Ayuntamiento proporciona un mecanismo para solicitar la activación de CORS a determinados dominios. Si es su caso, por favor rellene el siguiente formulario detallando la petición e indicando el dominio desde el que se quieren realizar las peticiones Ajax.
Para mas información sobre CORS, puede visitar el siguiente enlace en la Wikipedia: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing