EDIT

# Map REST Service

----

_This is not a specification of a publicly available service but a proposal and guidance for the implementation of next version of the EDIT Map Service_

_The next version of the EDIT Map Service is being discussed on [[MapRestServiceApi_20_Discussion|MapRestServiceApi 2.0 Discussion]]_

----

{{>toc}}

## Servers

The map services are currently available from the following servers:

* Primary server: http://edit.africamuseum.be/edit_wp5.

* Secondary server: http://edit.br.fgov.be/edit_wp5

The EDIT map service offers 3 different service endpoints. :

 **Recommended endpoint:** 

* **rest_gen.php** (version 1 developped from May 2011): Merging [areas.php" and "points.php]() color theme both for areas (polygons) and distribution points. Output in JSON format is also available. 

 **End points only for testing and special purposes:** 

* **areas.php**  (version 1 dev. from 2007): displaying maps with areas (polygons) having a color theme dynamically defined by HTTP GET or POST parameters. Output in json format is also available.

* **points.php** (version 1 dev. from 2007): displaying maps with points for occurrence data. Position, legend and symbology of the points can be dynamically defined by HTTP parameters. Output in JSON format is also available.

Versions:

* version 1  - used by most of users (May 2011):

  * http://edit.africamuseum.be/edit_wp5/v1/points.php

  * http://edit.africamuseum.be/edit_wp5/v1/areas.php

  * http://edit.africamuseum.be/edit_wp5/v1/rest_gen.php

* version 1.1 - (20th of May 2011)

  * http://edit.africamuseum.be/edit_wp5/v1.1/points.php

  * http://edit.africamuseum.be/edit_wp5/v1.1/areas.php

  * http://edit.africamuseum.be/edit_wp5/v1.1/rest_gen.php

* version 1.2 - **recommended** 

  * http://edit.africamuseum.be/edit_wp5/v1.2/points.php

  * http://edit.africamuseum.be/edit_wp5/v1.2/areas.php

  * **http://edit.africamuseum.be/edit_wp5/v1.2/rest_gen.php** 

## Introduction

The EDIT Map Service returns map images in response to a URL. Distribution and occurrence maps can be generated.

Each map is specified by attributes (URL query parameters) or in future by configuration files whose location is given by attributes to the service, which in turn will load the files to process them.

These configuration files are not Geoserver/WMS config files. These files are an alternative way to submit settings for a map to the wms wrapper. For example you can specify areas as described below or you tell the service  from where it can download a file which contains all the area definitions. Practical exampls of URI requests to a EDIT Map Service are found on [[MapRestServiceExamples|Map REST Service Examples]].

Some parts and features of this REST API is still in a creative process these considerations and thoughts are collected and discussed in [[MapRestServiceIdeas]].

## Conventions and general considerations

The EDIT Map Service is a service wrapping around a WMS geoserver. wms query parameters can be used in addition to the API attributes defined here. The wrapper internally construct the WMS GetMap request from the REST API attributes.

The request URIs must conform to [RFC 3986](http://tools.ietf.org/html/rfc3986.)

The EDIT Map Service ignores wms attributes if a substitute is defined in this specification, e.g.:

* **request=!GetMap**  -              not needed

* **Format          ** -             optional (need to define default : png?)

* **bbox              ** -           required!

* **width, height**         -        replaced by **ms** 

* **layers               ** -       replaced by **l**  optional

* **SRS                  ** -      (Spatial Reference System (SRS) identifier ) optional ( Defines projections in WMS GetMap request. Using EPSG:4326 (WGS84 lat/long) is the default but can be changed on-the-fly to different UTM and much more zone specific.)

In attribute names the following letters are used as abbreviations for:

* d: data

* s: style / size

* a: area

* r: resolution

* g: grid

* o: occurrence

* c: cell  

* l: layer

* m: map image

Since there is a size limitation for URLs the API syntax is soze optimizes where possible. This is mainly achieved by avoiding redundancies and could be further improved by reducing the need for separators. 

### Reserved Characters

The colon ':' is used as delimiter between a leading identifier and the data, style ...

The semi-colon ";" is always used as delimiter between entries of the same data type.

The comma "," character delimits the sub-entries of which a singel entry can be composed (e.g: <longitude>,<latitude>).

Data entities of different types which together specifiy a character out of a matrix (or tree) of possible characters are delimited by the dash "/" (e.g: <shape>/<size>/<color>).

There is no delimiter to concatenate multiple lists of entries into a single attribute. In this case the same attribute is used multiple time in the request URI, every time assigned to another set of entries ( e.g.: @od=1:38.326,-0.822;38.328,-0.542&od=3:40.78,-4.009;43.461,-5.412@).

### Syntax Definition

The grammar definition which is adapted from the [Backus-Naur Form (BNF)](http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form) is using the following characters:

Brackets "[]" are used to enclose optional attributes.

Angles "<>" are used to enclose data component names.

The expressions "[[]"|and "[;..]]" indicate that the preceding element can be repeated multiples times using the particular delimiter.

The pipe character "|" is being used to separate optional entries. 

## Map Services

There are two different services which are used for creating maps. One service for creating maps and another one being responsible for creating the legends. The map created by the map service can directly include legends in which case the map service is using the legend service internally. The services are registered to the following URI sub paths:

* map service: @ ./map/ @

* legend service: @ ./legend/ @

### Response Content Types

The map service can respond with two different content types which are: 

* **Map images** - this is the default response content type

* **JSONP** - this is useful in order to use the maps in a dynamic map viewer like openlayers.

To enable the JSONP response type you need to add the img query parameter to the request URL:

~~~

img=false

~~~

## Layers

For wms areas are specified in shape files (polygons in *.shp + area index in *.shx).

The map service offers a set of default raster data and shape files e.g. for all 4 TDWG regions, ISO regions etc.

These predefined layers can be selected by the layer name, e.g. tdwg1 for TDWG regions level 1.  

 **Attribute:** 

~~~

(layer) l=<layer name>[:[<layer style id>][<shp file url>|<raster data url>]];...

~~~

The (layer) "l" attribute is an facultative one it is not needed if only predefined layers are used for a map.

Multiple layer definitions are separated by dash characters.

Where

* `<layer name>` is the name of either a default shape file offered by the server or a new name.

* `<layer style id>` is the identifier of a layerstyle 

The order of <layer name> parameters in the attribute specifies the order of the layer stack for the map image from bottom to top. Raster data must be the first on the list, otherwise you cannot see vector layers.

In the latter case the optional attribute `<shp file url>` must be given to specify a *.shp file to processed by the server. The name of the also required *.shx (index-) file is inferred from @<shp file url>@. 

 **Available Layers (<layer name>)** 

* tdwg1 ([overview](http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:tdwg_level_1&styles=&bbox=-180.0,-90.0,180.0,83.624&width=684&height=330&srs=EPSG:4326&format=application/openlayers))

* tdwg2 ([overview](http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:tdwg_level_2&styles=&bbox=-180.0,-90.0,180.0,83.624&width=684&height=330&srs=EPSG:4326&format=application/openlayers))

* tdwg3 ([overview](http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:tdwg_level_3&styles=&bbox=-180.0,-90.0,180.0,83.624&width=684&height=330&srs=EPSG:4326&format=application/openlayers))

* tdwg4 ([overview](http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:tdwg_level_4&styles=&bbox=-180.0,-90.0,180.0,83.624&width=684&height=330&srs=EPSG:4326&format=application/openlayers))

* earth

* e_provinces

* several vmap0 layers (http://en.wikipedia.org/wiki/Vector_Map http://gis-lab.info/qa/vmap0-eng.html)

~~~

currently (8/8/2011) there are 76 vmap0 layers in the EDIT Geoserver WMS. 

     They are (roughly) divided in 4 zones:

         * Europe (layers beginning with 'vmap0_eu' in the EDIT WMS)

         * Asia and Oceania (layers beginning with 'vmap0_as' in the EDIT WMS 

         * Africa and South America (layers beginning with 'vmap0_afsa' in the EDIT WMS)

         * North America (layers beginning with 'vmap0_na' in the EDIT WMS)

~~~

* The complete European dataset has been imported, with political (borders of countries and national subdivisions (like Belgian and Dutch Provinces, French Regions, German Landers, Italian regions Swiss Canton etc...) layers,

 ecological layers (soil, rivers, vegetation}, layers on infrastructure and habitat (urban areas, roads, railways) etc...

* Only parts of the information have been imported for the 3 other zones , but they all features at least the political boundaries:

* Europe: http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:vmap0_eur_bnd_political_boundary_a&styles=&bbox=-31.266,30.0,180.0,81.857&width=1344&height=330&srs=EPSG:4326&format=application/openlayers

* Asia and Oceania: http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:vmap0_na_bnd_political_boundary_a&styles=&bbox=-180.0,-30.531,-7.921,83.627&width=512&height=339&srs=EPSG:4326&format=application/openlayers

* Africa and South America: http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:vmap0_afsa_bnd_political_boundary_a&styles=&bbox=-180.0,-30.531,-7.921,83.627&width=512&height=339&srs=EPSG:4326&format=application/openlayers

* North America: http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=topp:vmap0_na_bnd_political_boundary_a&styles=&bbox=-180.0,-30.531,-7.921,83.627&width=512&height=339&srs=EPSG:4326&format=application/openlayers

The provinces are named and retrievable through "GetFeature" WMS queries.

* -It is possible to ask for more layers as the complete Vmap0 has been loaded into the PostGIS database feeding the EDIT WMS.

* -It is also possible to aggregate together several layers in oen alias with one specific style, but this operation is tedious as it requires the manual configuration of several SLD files:

*  e.g: http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=vmap0_world_basic&styles=&bbox=-180.0,-90.0,180.0,90.0&width=660&height=330&srs=EPSG:4326&format=application/openlayers

* -An aggregate layer of all the national subdivisions of the world is available. 

* Its name is "*vmap0_world_national_boundaries*"

http://edit.br.fgov.be:8080/geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=vmap0_world_national_boundaries&styles=&bbox=-180.0,-90.0,180.0,83.627&width=684&height=330&srs=EPSG:4326&format=application/openlayers

----

For a complete list of currently available layers see [geoserver layer preview](http://edit.br.fgov.be:8080/geoserver/web/?wicket:bookmarkablePage=:org.geoserver.web.demo.MapPreviewPage)

 **Layer styles** 

Layer styles are defined by the layer_style attribute

~~~

(layer style) ls=<layer_style_id>:[<line_color>][/<line_width>][/<stroke_style_id>];..

~~~

Where 

* `layer_style_id` is the layers identifier

* `line_color` is the color of border lines used in the layer

* `line_width` is the width of the border lines

* `stroke_style_id` is an id for the stroke (still to be defined)

> [Pere]

> Shapefiles is the ESRI (propietary) format for storing vector data. The most performant way of storing areas are in postGIS database. 

> We could insert the .shp in postGIS and try to “inform” Geoserver of this new layer... something like this has been done before but it can be complicated. 

>

> Another issue is to insert information (CSV files or whatever, even shapefile)  in an already existing postGIS database (as the table already exists and is defined in Geoserver, we just need an userid filter to get the data we just have inserted now; this is the technique used in mapViewer to filter the CSV data you insert). 

>

>> [[Andreas|K]] So the solution could be like the following:

>> - We allow for example 20 extra layers as postGIS tables

>> - Shapefiles (or GML?) are inserted by shp2pgsql into one of the postGIS tables

>> - An md5 hash of the according URL parameter token ( <layer name>[[<shp|file url>]][[<raster|data url>]] ) is used as key to identify, i.e. to filter the shapes for this layer definition for the geoserver. Otherwise 1) you would have to add a URL queryparameter user=<username>

## Areas

*A.Attribute (for all layers)*: 

~~~

  (area data) ad=<layer name>:<field name>:<area set>[;..]

      <area set> ::= <area style ids>:<area id list>

      <area id list> ::= <area id>[,..]

~~~

Where 

* `<field name>` is the name of the field in the WMS layer that contains the <area style ids>

* `<area style ids>` is a string of one letter `[a-z,A-Z]` area style ids

* `<area id>` either is the shape index as defined in the *.shx file or a area name. Area names are internally translated by the service ito shape index.

e.g:

http://edit.africamuseum.be/edit_wp5/v1/areas.php?l=cyprusdivs&ad=cyprusdivs:bdcode:a:4|b:2|c:8&as=a:000000~0.1|b:~0.1|c:000000~0.1&title=a%3ACasual%3F|b%3Anaturalised|c%3AIndigenous&l=tdwg4&ad=cyprusdivs:bdcode:a:4|b:2|c:8&as=a:000000~0.1|b:~0.1|c:000000~0.1&title=a:Casual%3F|b:naturalised|c:Indigenous&img=false&ms=500&bbox=32,34,35,36&labels=1&img=true&ms=500&img=true&legend=1&mlp=3&mc_s=Georgia,15,blue&mc=&recalculate=false

*B.Attribute (optional for precoded TDWG layers)*: 

~~~

  (area data) ad=<layer name>:<area set>[;..]

      <area set> ::= <area style ids>:<area id list>

      <area id list> ::= <area id>[,..]

~~~

Where 

* `<area style ids>` is a string of one letter `[a-z,A-Z]` area style ids

* `<area id>` either is the shape index as defined in the *.shx file or a area name. Area names are internally translated by the service ito shape index.

* `<field name>` (2nd parameter of previous case) can be dropped in this case.  

## Area Style

*Attribute*: 

~~~

  (area style) as=<area style id>:<area style definition>[;..]              

   <area style definition> ::= <pattern id>/<color>[/<style_label>] -  defines a pattern and foreground color to fill a shape with

   <area style definition> ::= <color>[/<style_label>] -  defines a background (fill) color for a shape

~~~

Where 

* `<pattern id>` is a number from 0 to 99 identifying a predefined fill pattern

* `<color>` is a RGB hex code always 6 letters long

* `<style_label>` is the label of the style in the legend

*Further improvement*: 

  Removing the unnecessary colons used as separator, they are just for readability. 

  Area styles can easily parsed without.

### Point Style

*attribute*:

~~~

os=indexer:shape/RGB_fillcolor/size_of_shape/label

(1 indexer; 4 parameters separated by “/”):

~~~

e.g:

os=1:c/0000FF/17/others

indexer	        =	1 (can also be text)

shape		= 	“c” (circle). other possible values: "c"=>circle; "s" =>star; "sq"=> square

fill color	=	0000FF (Blue)

size		=	17

label		= 	"others"

## Grids

*Attributes*: 

~~~

(grid resolution) gr=<layer name>[:<layer style id>]:<long>[,<lat>] - specifies a grid layer

(grid data)       gd=<layer name>:<cell set>[;..]

                  <cell set> ::= <cell style id>:<cell id>

~~~

Where 

      `<layer name>` is the name of a predefined grid layer or a new name identifying the grid specified by the additional attributes.

      `<long>` is horizontal resolution in degrees eg. 1, 10, 0.6, 0.1 ...

      `<lat>` This optional attribute is the vertical resolution in degrees eg. 1, 10, 0.6, 0.1. if felt out the `<long>` attribute will taken instead

      <cell id> is the identifier of a cell concatenated of the horizontal and vertical cell number (figure) or the cell identifier of a predefined grid layer like UTM 25000. 

~~~

                  0   1 

                +---+---+

              0 | 00| 01|

                +---+---+

              1 | 10| 11|

                +---+---+

~~~

> If grid follows an already defined projection and resolution (for example UTM 25000 resolution that can be seen in mapViewer) we already have in our database the corresponding code for each cell. This code can be labeled (shown on the map). 

>

>> So we can ad  the following to the proposal (see above..)

~~~

      <cell style id>  is the id of a cell style .... [TODO]

~~~

 **Open questions:** 

* how to define style labels for the longitude and latitude axis?

## Occurrences

*Attributes*: 

~~~

  (occurrence data)  od=<occurrence set id>:<occurrence entry list>

  <occurrence entry list> ::= <occurrence entry>[;..]

  <occurrence entry> ::= <long>,<lat>[,<precision>]

  (occurrence style) os=<occurence style definition>[;..]

  <occurence style definition> ::= <occurrence set id>:<style>/<color>

~~~

Where

* `<occurrence set id>` is an number [0-9] on 1..n digits

* `<long>` is longitude in degrees of the occurrence point

* `<lat>`  is latitude in degrees of the occurrence point

* `<precision>` precision 

* `<color>` is a RGB hex code always 6 letters long

* `<style>` either one letter [[a-z|A-Z]] except 'u' and 'z' which are used for

  * u: u<unicode hex code(4 letters)> unicode character as occurrence point icon  

  * z: z<number> custom style reserved for future use  

  * c: circle

  * s: square

  * ....

## Legends

Legends can be either be horizontal or vertical legends (see below) you can place the legend on top or bottom or at the left or right side  or at the edges of the map. 

~~~

 (map legend type) mlt=<legend type id>

  <legend type id> ::= h|v // see below for explanation

 (map legend position) mlp=

  <legend position id> ::= 1|2|3|4|5|6|7|8  // see below for explanation

~~~

 **horizontal legend** (@mlt=h@):

~~~

item 1

item 2

item 3

~~~

 **vertical legend** (@mlt=v@):

~~~

item 1 item2 item 3

item 4 item 5 item 6

~~~

*legend positioning*:

~~~

+-----+

|1 2 3|

|4   5|

|6 7 8|

+-----+

~~~

## Map Image

Attributes:

~~~

  (map size)        ms=[<units>:][<width>][,<height>]

  (map resolution)  mr=<pdi>

~~~

Where 

* `<units>` is optional an is one of px, mm, cm, .... defaults is px

* `<pdi>` is the resolution of the image in dpi, default is 72dpi

*Open questions*:

* color space / profile definition could be important for print quality maps required? how to ?

* how to style and configure legends?

## Labels

How to define for each layer if we are interested (or not) to view it's label?

Andreas K. suggested these two main options:

1) extend the labels parameter:

labels =<layer name>:[0|1],...

2) extend the layers parameter with something like:

(layer) l=<layer name>[[[<layer|style id>]],[[<labels_on>]|[/<shp file url>]][[<raster|data url>]]];...

## Background WMS layer

The REST services also provide possibility to display background layer coming from external WMS:

There are 3 parameters to take into consideration

1)   "externalwms"       : The base URL of the WMS to query ("root" of the GetCapabilities" request.

2)   [externalwmsversion]() The version of the WMS standard used by the server (OPTIONAL: default value is "1.1.1")

3)   "externalwmslayer"  : A list of layers coming from the same WMS (comma-separated) 

The complete syntax is the following:

~~~

externalwms=[base URI of the WMS]&externalwmsversion=[externalwmsversion]&externalwmslayer=[name_layer_1][,name_layer_2][,...name_layer_n]

~~~

e.g.:

~~~

http://edit.africamuseum.be/edit_wp5/v1/rest_gen.php?od=1:52.17,14.26|52.18,14.26|52.16,14.27|52.16,14.28|52.16,14.29|52.29,14.26|52.28,14.39|52.28,14.41|52.2,14.43|52.19,14.52|52.12,14.46|52.13,14.46|52.11,14.47|52.12,14.47|52.13,14.47|52.18,14.49|52.19,14.49|52.06,14.5|52.07,14.5|52.09,14.5|52.06,14.51|52.07,14.51|52.21,14.51|52.06,14.52||2:52.08,14.53|52.09,14.53|52.06,14.55&os=1:s/8B0000/7/all||2:c/0000FF/7/others&l=earth:d&ad=vmap0_eur_pop_built_up_a:nam:d:%||vmap0_eur_pop_built_up_a:nam:a:EICHWALDE||vmap0_eur_pop_built_up_a:nam:b:COTTBUS||vmap0_eur_pop_built_up_a:nam:c:ZERNSDORF,BINDOWBRUCK,SENZIG&as=a:984ea3|b:ff7f00,1,0.1|c:ffff33,,0.1|d:FFCEFD,FFCEFD,0.1&title=a:EICHALDE|b:COTTBUS|c:ZERNSDORF,BINDOWBRUCK,SENZIG|d:others%20municipalities&img=true&recalculate=true&legend=1&mlp=1&ms=400,350&bbox=13.50,51.4,15,52.7&recalculate=false&callback=true&externalwms=http://isk.geobasis-bb.de/ows/dnm.php&externalwmsversion=1.1.1&externalwmslayer=bg%2Cvegetation%2Cgewaesser%2Csiedlung%2Cbln%2Cbrb%2Ctransport%2Cverkehrsobjekte%2Cstrassennamen%2Cortsnamen%2Cgewaessernamen

~~~

## Available layers

### 1) topp:em_tiny_jan2003 _Added 2013/07/25_

(layer originating from the Helsinki Natural history museum for Euro+Med areas : http://dev.e-taxonomy.eu/trac/ticket/2707). 

## Available Projections

### 1) EPSG:7777777 _Added 2013/07/25_

Projection for topp:em_tiny_jan2003

WKT (geoserver "epsg.properties):

~~~

7777777=PROJCS[

	"Lambert_Conformal_Conic",

	GEOGCS[

		"GCS_Unknown",

		DATUM[

			"D_European_1950",

			SPHEROID[

				"International_1924",

				6378388,297

			]

		],

		PRIMEM[

			"Greenwich",

			0

		],

		UNIT[

			"Degree",

			0.017453292519943295

		]

	],

	PROJECTION[

		"Lambert_Conformal_Conic"

	],

	PARAMETER[

		"standard_parallel_1",

		42

	],

	PARAMETER[

		"standard_parallel_2",

		56

	],

	PARAMETER[

		"latitude_of_origin",

		35

	],

	PARAMETER[

		"central_meridian",

		24

	],

	PARAMETER[

		"false_easting",

		3000000

	],

	PARAMETER[

		"false_northing",

		100000

	],

	UNIT[

		"Meter",

		1

	]

]

~~~

Proj4 (PostGIS):

~~~

+proj= lcc + 42 + 56 + 35 + 24 + 3000000 + 100000 (id in the spatial_ref_sys_table is 7777777)

~~~

## latest developments

Preliminary documentation on experimental features are found in the following tickets (only accessible for registered developers after login):

*  #4150 (compile edit map service documentation of new features in version v1.4_dev and v1.5_dev)