NOTA: selecciona la orientación oportuna del papel en las opciones de impresión de tu navegador. Puedes imprimir la página o volver al visor.

Documentación de la API REST

Los objetivos de diseño principales de la API son:

  • Utilización del estilo arquitectural REST.

  • Diseño de una API limpia y agnóstica de su implementación. Actualmente al API está implementada en RubyOnRails pero podrá ser re-implementada o ampliada en el futuro en otras plataformas, como PHP o Zope.

  • Uso de la librería OpenLayers para mostrar y trabajar con los mapas, lo que además permite que seamos directamente compatibles con Mapstraction.

  • Utilizar el semi-estándar TMS para servir los mapas a OpenLayers

  • Intentar adherirse a APIs estándares por todas la ventajas de interoperatividad que ofrecen.
  • En un futuro posiblemente implementar los servicios de la Open Geospatial Consortium (OGC), que incluyen:

En general, la API está dividida es dos partes:

  • API para hacer consultas y obtener información.
  • API para embeber y trabajar con mapas. Por embeber nos referimos a incrustar una ventana en la aplicación que un tercero está desarrollando.

Consideraciones generales

Esta API es accesible vía HTTP y sigue el estilo REST. El diseño de la API es agnóstico con respecto a una implementación particular, aunque tiene detalles de diseño de la implementación REST de RubyOnRails. Esta influencia de RubyOnRails está documentada en cada caso particular.

Tipo de coordenadas

A no ser que se indique lo contrario de forma explícita, todas las coordenadas (longitud/latitud) usadas en esta API están en la proyección Spherical Mercator con un SRS de "EPSG:900913".

URL base de la API

Todas las URLs que aparecen en este documento se aplican sobre la URL base del servidor donde se aloja la API. De momento esta URL base es:

b5m.gipuzkoa.net/api/

Cabe destacar que una implementación en RubyOnRails es agnóstica del dominio utilizado ya que por defecto la aplicación web se auto-ajusta al dominio de la URL de petición.

Versionado

La API está versionada, de forma que pueda evolucionar sin interferir con los clientes que actualmente la utilicen. Los números de versión tienen la forma:

mayor.menor

Este documento describe la versión 1.0 de la API, por lo que la URL base será:

b5m.gipuzkoa.net/api/1.0/

Una versión determinada de la API debe ser estable durante un tiempo prudencialmente largo para no interferir a los clientes actuales que la estén utilizando.

Localización

El resultado de muchas consultas contiene texto que debe aparecer localizado a petición del cliente.

La selección de la localización se hace de una forma RESTful, introduciendo un código de idioma en el path de la URL. Esto se hace en detrimento del uso de query strings (por ejemplo "?lang=es") tal como recomienda la RestBible (pags. 121-123).

Los códigos de idioma están especificados según el estándar ISO 639-1. Los códigos principales para nuestra aplicación son:

 - Euskera:    eu
 - Castellano: es
 - Inglés:     en
 - Francés:    fr

La especificación del código de lenguaje aparece después del número de versión de la API, como por ejemplo:

/api/1.0/es/

La parte "estructural" REST del path (cadena de directorios) de las URLs está en ingles y es independiente de la localización seleccionada. Esto es por consistencia, no tiene sentido que las URLs cambien según la localización seleccionada. Debido al estilo REST, hay partes del path que corresponden a parámetros de la consulta, y por tanto podrán estar localizados.

Los casos en los que los parámetros de consulta están localizados son para la "codificación" de entidades (municipios, calles...)

Por ejemplo, para obtener el MBR de un objeto (mas información en los detalles de la API)

/api/1.0/es/locate/mbr/M_069

La selección del locale se hace por medio la URL como se ha descrito, y de momento se ignora la cabecera HTTP Accept-Language. Esto es en concordancia con el estilo REST (RestBible 93,391).

En cualquier caso, todo el contenido textual devuelto por la API está codificado en UTF-8. De momento, la cabecera HTTP Accept-Charset será ignorada (RestBible 390).

Formato de salida

La API expone los recursos (datos) en diferentes representaciones. Típicamente estas representaciones incluyen los formatos:

  • JSON
  • XML
  • TEXT (TXT,CSV)

La selección de la representación se realiza seleccionando de la siguiente lista el primer caso que se cumpla (estilo Rails):

  1. Añadiendo una "extensión de formato" a la URL de la petición. Como por ejemplo:
    /api/1.0/es/locate/mbr/M_069.xml
    /api/1.0/es/locate/mbr/M_069.json
    
  2. Utilizando la cabecera HTTP Content con el MIME type adecuado.

  3. Si no se cumple ninguno de los casos anteriores, se devolverá en la representación por defecto que es XML.

No todos los recursos están disponible en todos los formatos. Los recursos exponen la lista de formatos en los que pueden ser obtenidos. La lista de formatos está accesible añadiendo la extensión ".formats" a la URL que prefija la "clase de recursos". Por ejemplo:

  • /api/1.0/es/locate/mbr.formats
    /api/1.0/es/locate/info.formats
    

El resultado es una CSV textual con los formatos de representación soportados por esa clase de recursos.

EPSG

El API permite recibir los resultados en los sistemas de referencia: EPSG:900913 (Spherical Mercator -- por defecto), EPSG:4326 (WGS84) y EPSG:25830 (ETRS89). La selección del sistema de referencia se realiza mediante el parámetro srs.

  • /api/1.0/es/locate/mbr/M_069.xml;srs=epsg:25830
    /api/1.0/es/locate/mbr/M_069.xml;srs=epsg:4326
    /api/1.0/es/locate/mbr/M_069.xml;srs=epsg:900913
    

Formato JSONP

La API puede devolver los datos en formato JSONP. Este es un caso particular ya que hay que especificar cual es la función de callback.

Comúnmente se suele especificar este callback utilizando un query string en la URL. En nuestro caso podría ser algo como:

/api/1.0/es/locate/mbr/M_069.jsonp?callback=mi_funcion

Esta forma de especificar el callback no sigue el estilo arquitectural REST y no es caché friendly. Por ello se ha elegido una forma más REST de especificar el callback.

El callback se especifica utilizando un parameter (que no query string) en la URL:

/api/1.0/es/locate/mbr/M_069.jsonp;callback=mi_funcion

El parámetro callback puede estar URL-codificado. En el caso de utilizar un "." en el callback también hay que URL-codificarlo aunque no sea habitual. De hecho se recomienda URL-codificar todos los caracteres a excepción de letras y dígitos:

/api/1.0/es/locate/mbr/M_069.jsonp;callback=form%5B0%5D%2Efuncion   # equivale al callback "form[0].funcion"

Algunos ejemplos de peticiones:

Petición:

/api/1.0/es/locate/info/D_4545.json

Resultado:

{
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
}

Petición:

/api/1.0/es/locate/info/D_4545.jsonp;callback=funcion

Resultado:

funcion({
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
})

Petición:

/api/1.0/es/locate/info/D_4545.jsonp;callback=form%5B0%5D%2Efuncion

Resultado:

form[0].funcion({
    "info": {
        "type": "postal_id",
        "postal_code": {
            "id_municipality": "017",
            "name": "SALESIANOS, CONVENTO",
            "bis": " ",
            "postal_code": "20720",
            "district_code": "02",
            "municipality": "AZKOITIA",
            "num": "012",
            "street": "AIZKIBEL KALEA",
            "section_code": "002",
            "id_street": "1240"
        }
    }
})

Organización jerárquica de la API (''namespaces'' o espacios de nombres)

Las URLs de la API están estructuradas de forma jerárquica. En un primer nivel, se distingue el tipo de recurso a acceder por medio de un identificador:

Namespace Uso
configuration/ Información sobre las capas disponibles
locate/ Para acceder a los recursos (datos) geográficos
library/ Para cargar las librerías Javascript
osgeo/ Para acceder a API's definidas por la Open Source Geospatial Foundation. Mayormente para TMS.

Posteriormente, la URL sigue identificando los recursos de una forma jerárquica, desde el recurso que "engloba" a los demás hacia el recurso "más pequeño".

Operaciones REST de modificación

La versión actual de la API sólo soporta el método GET de HTTP, esto es, sólo permite obtener datos. Los métodos PUT, POST y DELETE no están soportados actualmente.

Seguridad y control de uso

La versión actual de la API no soporta ningún sistema de autentificación (API key). Todos los accesos son anónimos y no limitados.

Resumen de la estructura de las URLs

Dominio base Versión Locale Namespace Ruta al recurso [Representación (formato)]
 b5m.gipuzkoa.net/api/   M.m/   xy/   vwxyz/   .../...   .xyz 
Ejemplo
 b5m.gipuzkoa.net/api/   1.0/   es/   locate/   mbr/M_069   .json 

Definición de la API

Las URLs de estas definiciones son relativas al prefijo de su URL correspondiente.

Namespace "configuration/"

Estas URLs devuelven datos de configuración.

URL Resumen Descripción
 configuration/layers/foreground  Capas de primer plano Las capas que están activas y pueden acceder vía TMS
 configuration/layers/background  Capas de segundo plano Las capas que están activas y pueden acceder vía APIs de Google, Yahoo, Microsoft...

Se pueden ver ejemplos de su uso en: "ejemplos del namespace configuration".

Namespace "locate/"

Todas estas URLs devuelven datos y hacen referencia a objetos.

URL Resumen Descripción
 mbr/{code}  Minimum Bounding Rectangle del objeto especificado Coordenadas del rectángulo mínimo que engloba al objeto
 geometry/{code}  Geometría que define el objeto La geometría es una serie de coordenadas que definen un polígono que representa al objeto. Representaciones soportadas: GML
 center/{code}  Centro del Objeto Coordenadas del centro del objeto
 info/{code}  Descripción textual del objeto La descripción textual incluye su nombre normalizado, tipo...
 search/{cadena_de_busqueda}  Término que se quiere buscar Nombre del topónimo que se desea buscar

Los Objetos permitidos son los siguientes:

Objeto Código Valor de ejemplo
Comarcas S_codcomarca S_3
Municipios M_codmuni M_045
Calles como conjunto de edificios K_codmuni_codcalle K_003_1110
Calles como vial V_codmuni_codcalle V_003_1110
Distritos y secciones SC_codmuni_coddistri_codseccion SC_045_01_003
Direcciones postales D_idpostal D_4545
Direcciones postales2 F_codmuni_codcalle_portal F_045_1110_003 F_034_1104_004B
Edificios E_idarea E_33360
Carreteras y tren T_codcarre T_9044
Punto Kilométrico PK_nombrecarretera_kilómetro PK_GI-2132_5
Barrios (código de área) B_idarea B_14278
Barrios (código de nombre) Z_idbarrio Z_15400
Cuencas C_codcuenca C_11
Núcleos N_codnucleo N_30145
Rios I_idrio I_17609
Orografía (código de área) O_idarea O_21669
Orografía (código de nombre) G_idorogra G_24071
Cuevas CV_codigo CV_CE0708
Carte megalitica GK_codigo GK_GARK153
Estaciones Megaliticas EM_codigo EM_AR13019

El formato de la respuesta de la búsqueda para search/:

Campo Descripción
type El tipo de nombre del que se trata, por ejemplo, EDIFICIO, MUNICIPIO, BARRIO, ARROYO, CALLE, DIRECCION POSTAL
name El nombre de elemento encontrado que contiene la palabra clave consulada por el usuario.
code Es el código del elemento en la base de datos. Éste es necesario para hacer cualquier tipo de consulta al API REST
urls Array de las urls a los distintos tipos de mapas y aplicaciones
ortho URL a la ortofoto de B5Map
map URL al mapa de B5Map
pictometry URL a la vista de pájaro de B5Map
map2d URL al mapa de !B5M
info URL del callejero
map3d URL a la aplicación Gipuzkoa3D
google URL a GoogleMaps?

Se pueden ver ejemplos de su uso en: "ejemplos del namespace locate".

Namespace "query/"

Estas URLs permiten obtener información sobre los objetos que están alrededor de una coordenada.

URL Resumen Descripción
 whatisthis/lat/{lat}/lon/{lon}/tolerance/:tolerance/codes/{codes}  Devuelve una lista de objetos geográficos que se encuentran en un punto (*)

(*) Dada una coordenada y una lista de tipos de objetos geográficos a consultar devuelve una lista de objetos geográficos en cuya superficie está contenida la coordenada ("objetos que hay en ese punto"). Sólo se comprueban los tipos de objetos geográficos especificados, así que nunca se devolverá un objeto geográfico de un tipo no especificado. Parámetros:

lat: latitud
lon: longitud
tolerance: radio en KMs que define un area alrededor del punto en la cual se buscan los objetos (0 para buscar exactamente en el punto dado)
codes: lista de tipos de objetos geográficos separados por coma ("T,D,E") o asterisco ("*") para comprobar todos los códigos disponibles 

Namespace "layer/"

Estas URLs devuelven información asociada a una capa (ya sea ortofoto o mapa).

URL Descripción
 layer/scenetype/layer/{layer}/mbr/xmin/{xmin}/ymin/{ymin}/xmax/{xmax}/ymax/{ymax}  Comprueba si el MBR pasado está dentro, parcialmente fuera o totalmente fuera de Gipuzkoa. Devuelve de forma textual:
* 1: totalmente dentro
* 2: parcialmente fuera
* 3: totalmente fuera

Se pueden ver ejemplos de su uso en: "ejemplos del namespace layer".

Namespace "pictometry/"

Estas URLs devuelven información sobre las imágenes de pictometry,

 pictometry/coordinate-search/lat/{lat}/lon/{lon}.{format}  Obtiene las imágenes de pictometry disponibles en las coordenadas dadas. Devuelve una lista de vistas, y por cada vista:
* URL TMS base de la imagen
* una coordenada dentro de esa imagen que representa el "centro" más aproximado correspondiente a las coordenadas planares originales
* orientación de la imagen (N/S/E/O/NW...)
 pictometry/checkfast/lat/{lat}/lon/{lon}.{format}  Comprueba de forma rápida si hay imágenes de pictometry en las coordenadas dadas. Devuelve TRUE o FALSE.

Se pueden ver ejemplos de su uso en: "ejemplos del namespace pictometry".

Namespace "library/"

Estas URLs permiten la carga de la librerías Javascript por parte del cliente. La librería base es "openlayers" pero en todos los ejemplos (y productos) vamos a utilizar las librerías "prototype" y "scriptaculous", así que (de momento) también las ponemos a disposición de los clientes.

Utilizamos un prefijo con el nombre de la librería para simplificar el rutado, ya que, por ejemplo, dentro de openlayers/ va a haber más directorios "ocultos" con resources que necesita OpenLayers (img/, css/ ...).

Los clientes pueden optar a cargar estas librerías desde otros sitios.

URL Resumen Descripción
 openlayers/OpenLayers.js  Librería OpenLayers, OJO! Utilizar el nombre exacto de fichero "OpenLayers.js" (y no "openlayers.js" por ejemplo) o la librería no se va a cargar correctamente (es un detalle de implementación de la librería OpenLayers) http://openlayers.org/
 openlayers/OpenLayers.js.version  Versión de la librería OpenLayers que proveemos
 prototype/prototype.js  Librería Prototype http://www.prototypejs.org/
 prototype/prototype.js.version  Versión de la librería Prototype que proveemos
 scriptaculous/scriptaculous.js  Librería script.aculo.us http://script.aculo.us/
 scriptaculous/scriptaculous.js.version  Versión de la librearía script.aculo.us que proveemos

Se pueden ver ejemplos de su uso en: "ejemplos del namespace library".

Namespace "osgeo/"

Estas URLs son para acceder a "estándares" definidos por la OSGEO, de momento sólo para TMS.

URL Resumen Descripción Ejemplo
 osgeo/tms/tileset/1.0.0/ort/..  Tile Resources para OpenLayers Ortofotos (Actual) http://b5m.gipuzkoa.net/api/1.0/es/osgeo/tms/tileset/1.0.0/ort/17/64822/83058.jpg
 osgeo/tms/tileset/1.0.0/map/..  Tile Resources para OpenLayers Map (Actual) http://b5m.gipuzkoa.net/api/1.0/es/osgeo/tms/tileset/1.0.0/map/17/64822/83058.png
 osgeo/tms/tileset/1.0.0/ort2006/..  Tile Resources para OpenLayers Ortofotos 2006 http://b5m.gipuzkoa.net/api/1.0/es/osgeo/tms/tileset/1.0.0/ort2006/17/64822/83058.jpg
 osgeo/tms/tileset/1.0.0/map2008/..  Tile Resources para OpenLayers Map 2008 http://b5m.gipuzkoa.net/api/1.0/es/osgeo/tms/tileset/1.0.0/map2008/17/64822/83058.png

Cartografías disponibles:

Cartografía Año ID
Mapa actual map
2010 map2010
2009 map2009
2008 map2008
2007 map2007
Ortofoto actual ort
2009 ort2009
2008 ort2008
2007 ort2007
2006 ort2006
2005 ort2005
2004 ort2004
2002 ort2002
2001 ort2001
Pictometry 2007 pictometry

Se pueden ver ejemplos de su uso en :"ejemplos del namespace osgeo".

Aplicación de ejemplo

Se puede ver una simple aplicación haciendo uso de esta API en: "aplicación de ejemplo".