• Table of contents
• Map REST Service
  • Introduction
  • Conventions and general considerations
    • Reserved Characters
    • Syntax Definition
  • Layers
  • Areas
  • Area Style
  • Grids
  • Occurrences
  • Map Image

Map REST Service¶

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 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 Map REST Service Examples.

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

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: ,).

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: //).

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) 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 preceeding element can be repeated multiples times using the particular delimiter.

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>]];...

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 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 @@.

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).

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 ( ]][[ ) 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=

Areas¶

Attribute:

  (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.

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.

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 except 'u' and 'z' which are used for

  • u: u unicode character as occurrence point icon
    
  • z: z custom style reserved for future use
    
  • c: circle
  • s: square
  • ....

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?