REST API Documentation
The main design goals of this API are as follows:
-
Use a RESTful architectural style REST.
-
To design a clean API that is implementation agnostic. Currently, this API is implemented in RubyOnRails but it could be re-implemented or extended in the future for other platforms such as PHP or Zope.
-
To use the OpenLayers library to display and manage maps, which allows direct compatibility with Mapstraction.
-
To use a semi-standard TMS to serve OpenLayers maps.
- To attempt to adhere to API standards because of the advantages this has to offer in terms of interoperability.
-
To allow for the future implementation of Open Geospatial Consortium (OGC) services, including:
In general, the API is divided into 3 parts:
- API for making requests and obtaining data.
- API for embedding and handling maps. By "embedding", we refer to inserting a window into a third-party application in development.
General Considerations
This API is accessible via HTTP and is a RESTful web service. The API has been designed to be implementaton-agnostic, although there are design details that site the RubyOnRails implementation of REST. This RubyOnRails influence has been documented in each particular case.
Coordinate Types
Unless otherwise explicitly specified, all coordinates (longitude/latitude) used in this API are assumed to be in the Spherical Mercator projection with an SRS value of "EPSG:90013".
The API's URL Base
All the URLs that appear in this document are built over a URL base that points to the server where the API is hosted. Currently, the URL base points here:
b5m.gipuzkoa.eus/api/
It's worth noting that an implementation in RubyOnRails is domain-agnostic since the web application automatically adjusts itself to the domain within the requested URL.
Versioning
The API is versioned in order to continue evolving without interfering with those clients that currently make use of it. The version numbers come in the "major.minor" form.
major.minor
This document describes version 1.0 of the API, whose base URL is:
b5m.gipuzkoa.eus/api/1.0/
A particular API version should remain stable during a prudently long period of time in order to avoid interfering with anyone currently using it.
Localization
Many result sets contain text whose language must be specified in the request.
The localization parameter is specified RESTfully by including the language code in the path of the request URL. This takes the place of using query strings (for example "?lang=es") as recommended in the RestBible (pages 121-123).
Language codes are specified following the ISO 639-1 standard. The main locale codes used in our application are:
- Euskera: eu - Spanish: es - English: en - French: fr
The language code is specified after the API version number, for example:
/api/1.0/en/
The structurally RESTful part of URL paths (chain of directories) always remains in English and is independent of the selected language. This is done for consistency. It makes no sense for URLs to change according to the selected language. Due to the RESTful style, there are parts of the path that correspond to request parameters that may be localized for that reason.
Request parameters may be localized to "codify" entities (municipalities, streets)
For example, to obtain an object's MBR (see API details)
/api/1.0/en/locate/mbr/M_069
The locale parameter is defined in the URL as described, and for now the Accept-Language HTTP header is ignored. This is done in accordance with the REST style (RestBible 93,391).
All textual content returned by the API is encoded in UTF-8. For now, the Accept-Charset HTTP header is ignored (RestBible 390).
EPSG
The following reference systems: EPSG:900913 (Spherical Mercator -- default), EPSG:4326 (WGS84) y EPSG:25830 (ETRS89) could be applied to the results. Please use the srs parameter to specify the system reference.
/api/1.0/en/locate/mbr/M_069.xml;srs=epsg:25830 /api/1.0/en/locate/mbr/M_069.xml;srs=epsg:4326 /api/1.0/en/locate/mbr/M_069.xml;srs=epsg:900913
Output format
The API exposes and represents resources (data) in a variety of different formats. Typically, these representations include the following formats:
- JSON
- XML
- TEXT (TXT,CSV)
Formats are selected when finding the first applicable case in the following list (Rails style):
- By adding a "format extension" to the URL request. For example:
/api/1.0/en/locate/mbr/M_069.xml /api/1.0/en/locate/mbr/M_069.json
-
By using the HTTP Content header with the appropriate MIME type.
- If none of these cases apply, the default XML representation will be returned.
Not all resources are available in all formats. Each resource exposes its own list of available formats. This list of formats can be accessed by adding the ".formats" extension to the URL and presetting the "resource class". For example:
-
/api/1.0/en/locate/mbr.formats /api/1.0/en/locate/info.formats
The result is a comma separated list of the representational formats supported by this resource class.
JSONP Format
The API can return data in JSONP format. This is a particular case in which a callback function must be specified.
This callback is commonly specified in the URL's query string. In our case, it could be something like this:
/api/1.0/en/locate/mbr/M_069.jsonp?callback=my_function
This method of specifying the callback does not follow REST architectural standards, nor is it cache friendly. For that reason, a more RESTful way to indicate the callback parameters.
The callback is specified by using a parameter (not the query string) in the URL:
/api/1.0/en/locate/mbr/M_069.jsonp;callback=my_function
The callback parameter may be url-encoded. Cases of callback names that contain a periods (".") require url-encoding in spite of common practice. In fact, we recommend url-encoding all non-alphanumeric characters:
/api/1.0/en/locate/mbr/M_069.jsonp;callback=form%5B0%5D%2Efunction # Is the callback "form[0].funcion"
Some request examples:
Request:
/api/1.0/en/locate/info/D_4545.json
Result:
{ "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" } } }
Request:
/api/1.0/en/locate/info/D_4545.jsonp;callback=my_function
Result:
my_function({ "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" } } })
Request:
/api/1.0/en/locate/info/D_4545.jsonp;callback=form%5B0%5D%2Emy_function
Result:
form[0].my_function({ "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" } } })
The API's Hierarchical structure (''namespaces'')
The API's URLs have a hierarchical structure. At the first level, the resource type is designated by ID:
Namespace | Usage |
configuration/ | Information on the available layers |
locate/ | For accessing geographical resources (data) |
library/ | For loading JavaScript libraries |
osgeo/ | For accessing APIs defined by the Open Source Geospatial Foundation, most commonly for TMS. |
Later, the URL continues to identify resources hierarchically, from the most "global" resource down to the most "specific".
RESTful update operations
The current API only supports the HTTP GET method, meaning it only permits data retrieval. The PUT, POST and DELETE methods are not supported at this time.
Security and access control
The API does not currently support any authentication system (API key). All requests are anonymous and unlimited.
Summary of URL structure
Base domain | Version | Locale | Namespace | Resource path | [Representation (format)] |
b5m.gipuzkoa.eus/api/ | M.m/ | xy/ | vwxyz/ | .../... | .xyz |
Example | |||||
b5m.gipuzkoa.eus/api/ | 1.0/ | es/ | locate/ | mbr/M_069 | .json |
API Definition
The URLs specified in these definitions are relative to their corresponding URL prefix.
Namespace "configuration/"
These URLs return configuration data.
URL | Summary | Description |
configuration/layers/foreground | Frontal layers | Layers that are active and can access TMS |
configuration/layers/background | Background Layers | Layers that are active and can access APIs from Google, Yahoo, Microsoft... |
Examples of their use can be found in: "examples of namespace configuration".
Namespace "locate/"
All these URLs return data and make reference to objects.
URL | Summary | Description |
mbr/{code} | Minimum Bounding Rectangle of the specified object | Coordinates of the minimum binding rectangle that contains the object |
geometry/{code} | Geometry that defines the object | Geometry refers to a series of coordinates that define a path or polygon that represents an object. Supported formats: GML |
center/{code} | The object's center | The object's center coordinates |
info/{code} | The object's textual description | The textual description includes its normalized name, type... |
search/{cadena_de_busqueda} | Term to be queried | Name of toponym to be queried |
The following objects are accepted:
Object | Code | Example value |
Comarcas (counties) | S_codcomarca | S_3 |
Municipalities | M_codmuni | M_045 |
Streets blocks | K_codmuni_codcalle | K_003_1110 |
Streets | V_codmuni_codcalle | V_003_1110 |
Districts and areas | SC_codmuni_coddistri_codseccion | SC_045_01_003 |
Postal addresses | D_idpostal | D_4545 |
Postal addresses2 | F_codmuni_codcalle_portal | F_045_1110_003 F_034_1104_004B |
Buildings | E_idarea | E_33360 |
Roads and rails | T_codcarre | T_9044 |
Kilometre Point | PK_roadname_kilometer | PK_GI-2132_5 |
Neighborhoods (area code) | B_idarea | B_14278 |
Neighborhoods (name code) | Z_idbarrio | Z_15400 |
Valleys (cuencas) | C_codcuenca | C_11 |
City Centers | N_codnucleo | N_30145 |
Rivers | I_idrio | I_17609 |
Orography (area code) | O_idarea | O_21669 |
Orography (name code) | G_idorogra | G_24071 |
Caves | CV_codigo | CV_CE0708 |
Carte megalitic | GK_codigo | GK_GARK153 |
Megalitic stations | EM_codigo | EM_AR13019 |
Format of the response from search/ query:
Field | Description |
type | An object name, such as BUILDING, MUNICIPALITY, NEIGHBORHOOD, RIVER, STREET, POSTAL ADDRESS |
name | The name of each returned element contains the requested keyword. |
code | This is the element's code in the database. It is required for all of API REST requests. |
urls | An array of URLs for the different types of maps and applications |
ortho | URL to B5Map Ortofoto |
map | URL to B5Map map |
pictometry | URL to B5Map birds-eye view |
map2d | URL to !B5M map |
info | URL to street map |
map3d | URL the !Gipuzkoa3D application |
URL to GoogleMaps? |
Examples of their use can be found in: "examples of namespace locate".
Namespace "query/"
These URLs allow data requests for objects surrounding a given set of coordinates (lon/lat).
URL | Summary | Description |
whatisthis/lat/{lat}/lon/{lon}/tolerance/:tolerance/codes/{codes} | Returns a list of geographic objects around a given point | (*) |
(*) Given a set of coordinates and a list of geographic object types, the query returns a list of geographic objects whose surface contains those coordinates ("objects found at this point"). The results are filtered by geographic object type, ensuring that unspecified types will be ignored. Parameters:
lat: latitude lon: longitude tolerance: radius in KMs that defines an area around the point at which objects are searched (0 to look exactly at the given point) codes: list of geographic types separated by commas ("T,D,E") or an asterisk ("*") to include all available geographic codes.
Namespace "layer/"
These URLs return information for a given layer (either ortofoto or map).
URL | Description |
layer/scenetype/layer/{layer}/mbr/xmin/{xmin}/ymin/{ymin}/xmax/{xmax}/ymax/{ymax} | A check is made to see if the given MBR falls inside, outside, or partially outside Gipuzkoa. A text result is returned: * 1: totally inside * 2: partially outside * 3: totally outside |
Examples of their use can be found in: "examples of namespace layer".
Namespace "pictometry/"
These URLs return information about pictometry images.
pictometry/coordinate-search/lat/{lat}/lon/{lon}.{format} | Obtains the available pictometry images for a given set of coordinates. Returns a list of views, and for each view: * Base TMS URL for the image * A set of coordinates within the image that represents the "center point" that most approximates the corresponding set of original planar coordinates * image orientation (N/S/E/W/NW...) |
pictometry/checkfast/lat/{lat}/lon/{lon}.{format} | The fastest way to check whether or not pictometry images exist for a given coordinate set. Returns TRUE or FALSE. |
Examples of their use can be found in: "examples of namespace pictometry".
Namespace "library/"
These URLs handle the task of loading client-side JavaScript libraries. The library is built on "OpenLayers", but in all our examples (and products) we will be using the "prototypejs" and "scriptaculous" libraries as well. So at least for now, these libraries are loaded as well and available to use as needed.
In order to avoid complicating URLs, we use the library's name as a prefix. There will be more "hidden" directories under openlayers/, for example, with resources needed by OpenLayers (img/, css/ ...) .
Clients may choose to load these libraries from other sources.
URL | Summary | Description |
openlayers/OpenLayers.js | OpenLayers, Library. Caution with OpenLayers! Use the exact name of the file "OpenLayers.js" without ignoring case ("openlayers.js") or else the library will not load correctly (it's something to know about the way OpenLayers has been implemented). | http://openlayers.org/ |
openlayers/OpenLayers.js.version | Version of the OpenLayers library we provide | |
prototype/prototype.js | Prototype library | http://www.prototypejs.org/ |
prototype/prototype.js.version | Version of the Prototype library we provide | |
scriptaculous/scriptaculous.js | script.aculo.us library | http://script.aculo.us/ |
scriptaculous/scriptaculous.js.version | Version of the script.aculo.us library we provide |
Examples of their use can be found in: "examples of namespace library".
Namespace "osgeo/"
These URLs are for accessing "standard" OSGEO definitions. This is currently only used for TMS.
URL | Summary | Description | Example |
osgeo/tms/tileset/1.0.0/ort/.. | Tile Resources for OpenLayers | Ortofotos (Actual) | http://b5m.gipuzkoa.eus/api/1.0/en/osgeo/tms/tileset/1.0.0/ort/17/64822/83058.jpg |
osgeo/tms/tileset/1.0.0/map/.. | Tile Resources for OpenLayers | Map (Actual) | http://b5m.gipuzkoa.eus/api/1.0/en/osgeo/tms/tileset/1.0.0/map/17/64822/83058.png |
osgeo/tms/tileset/1.0.0/ort2006/.. | Tile Resources for OpenLayers | Ortofotos 2006 | http://b5m.gipuzkoa.eus/api/1.0/en/osgeo/tms/tileset/1.0.0/ort2006/17/64822/83058.jpg |
osgeo/tms/tileset/1.0.0/map2008/.. | Tile Resources for OpenLayers | Map 2008 | http://b5m.gipuzkoa.eus/api/1.0/en/osgeo/tms/tileset/1.0.0/map2008/17/64822/83058.png |
Available cartographies:
Cartography | Year | ID |
Mapa | current | map |
2010 | map2010 | |
2009 | map2009 | |
2008 | map2008 | |
2007 | map2007 | |
Ortofoto | current | ort |
2009 | ort2009 | |
2008 | ort2008 | |
2007 | ort2007 | |
2006 | ort2006 | |
2005 | ort2005 | |
2004 | ort2004 | |
2002 | ort2002 | |
2001 | ort2001 | |
Pictometry | 2007 | pictometry |
Examples of their use can be found in:"examples of namespace osgeo".
Sample application
A simple example of an application making use of this API can be seen here: "sample application".