Project

General

Profile

MapRestServiceApi » History » Version 63

Andreas Kohlbecker, 02/12/2016 10:17 AM

1 1 Andreas Kohlbecker
2 2 Andreas Kohlbecker
3 1 Andreas Kohlbecker
4 8 Andreas Kohlbecker
5 61 Andreas Kohlbecker
# EDIT Map Service API
6 1 Andreas Kohlbecker
7
8 63 Andreas Kohlbecker
* [[MapRestServiceExamples|Map REST Service Examples]]
9
10
11 1 Andreas Kohlbecker
12 12 Andreas Kohlbecker
----
13
14
_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_
15
16 1 Andreas Kohlbecker
17 35 Andreas Kohlbecker
_The next version of the EDIT Map Service is being discussed on [[MapRestServiceApi_20_Discussion|MapRestServiceApi 2.0 Discussion]]_
18 34 Andreas Kohlbecker
19
20 1 Andreas Kohlbecker
----
21 21 Niels Hoffmann
22
23
{{>toc}}
24
25 12 Andreas Kohlbecker
26
27
28 20 Andreas Kohlbecker
## Servers
29
30
31
The map services are currently available from the following servers:
32
33
34 54 Andreas Kohlbecker
* Primary server: http://edit.africamuseum.be/edit_wp5.
35 1 Andreas Kohlbecker
36 54 Andreas Kohlbecker
* Secondary server: http://edit.br.fgov.be/edit_wp5
37 1 Andreas Kohlbecker
38 53 Andreas Kohlbecker
39 58 Andreas Kohlbecker
The EDIT map service offers 3 different service endpoints. :
40 1 Andreas Kohlbecker
41 29 Franck Theeten
42 58 Andreas Kohlbecker
 **Recommended endpoint:** 
43 55 Andreas Kohlbecker
44 29 Franck Theeten
45 1 Andreas Kohlbecker
* **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. 
46
47
48 58 Andreas Kohlbecker
 **End points only for testing and special purposes:** 
49
50
* **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.
51
52
* **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.
53
54
 
55 53 Andreas Kohlbecker
Versions:
56 1 Andreas Kohlbecker
57
58 60 Andreas Kohlbecker
* version 1  - (May 2011):
59 1 Andreas Kohlbecker
60 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1/points.php
61 1 Andreas Kohlbecker
62 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1/areas.php
63 29 Franck Theeten
64 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1/rest_gen.php
65 29 Franck Theeten
66 53 Andreas Kohlbecker
* version 1.1 - (20th of May 2011)
67 1 Andreas Kohlbecker
68 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1.1/points.php
69 1 Andreas Kohlbecker
70 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1.1/areas.php
71 1 Andreas Kohlbecker
72 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1.1/rest_gen.php
73 29 Franck Theeten
74 53 Andreas Kohlbecker
* version 1.2 - **recommended** 
75 29 Franck Theeten
76 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1.2/points.php
77 29 Franck Theeten
78 53 Andreas Kohlbecker
  * http://edit.africamuseum.be/edit_wp5/v1.2/areas.php
79 29 Franck Theeten
80 53 Andreas Kohlbecker
  * **http://edit.africamuseum.be/edit_wp5/v1.2/rest_gen.php** 
81 29 Franck Theeten
82 20 Andreas Kohlbecker
83
84 12 Andreas Kohlbecker
85 1 Andreas Kohlbecker
## Introduction
86
87
88 3 Andreas Kohlbecker
The EDIT Map Service returns map images in response to a URL. Distribution and occurrence maps can be generated.
89 1 Andreas Kohlbecker
90 15 Andreas Kohlbecker
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.
91 1 Andreas Kohlbecker
92 5 Andreas Kohlbecker
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]].
93 12 Andreas Kohlbecker
94
95
Some parts and features of this REST API is still in a creative process these considerations and thoughts are collected and discussed in [[MapRestServiceIdeas]].
96 1 Andreas Kohlbecker
97
98
99
## Conventions and general considerations
100
101
102 3 Andreas Kohlbecker
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.
103 1 Andreas Kohlbecker
104
105
The request URIs must conform to [RFC 3986](http://tools.ietf.org/html/rfc3986.)
106
107
108 3 Andreas Kohlbecker
The EDIT Map Service ignores wms attributes if a substitute is defined in this specification, e.g.:
109 1 Andreas Kohlbecker
110
111 19 Andreas Müller
* **request=!GetMap**  -              not needed
112 1 Andreas Kohlbecker
113
* **Format          ** -             optional (need to define default : png?)
114
115
* **bbox              ** -           required!
116
117
* **width, height**         -        replaced by **ms** 
118
119
* **layers               ** -       replaced by **l**  optional
120
121
* **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.)
122
123
124
In attribute names the following letters are used as abbreviations for:
125
126
127
* d: data
128
129
* s: style / size
130
131
* a: area
132
133
* r: resolution
134
135
* g: grid
136
137
* o: occurrence
138
139
* c: cell  
140
141
* l: layer
142
143
* m: map image
144
145
146
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. 
147
148
149
150
### Reserved Characters
151
152
153
The colon ':' is used as delimiter between a leading identifier and the data, style ...
154
155
156
The semi-colon ";" is always used as delimiter between entries of the same data type.
157
158
159
The comma "," character delimits the sub-entries of which a singel entry can be composed (e.g: <longitude>,<latitude>).
160
161
162
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>).
163
164
165
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@).
166
167
168
169
### Syntax Definition
170
171
172 22 Andreas Kohlbecker
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:
173 1 Andreas Kohlbecker
174
175
Brackets "[]" are used to enclose optional attributes.
176
177
178
Angles "<>" are used to enclose data component names.
179
180
181 22 Andreas Kohlbecker
The expressions "[[]"|and "[;..]]" indicate that the preceding element can be repeated multiples times using the particular delimiter.
182 1 Andreas Kohlbecker
183
184 22 Andreas Kohlbecker
The pipe character "|" is being used to separate optional entries. 
185 1 Andreas Kohlbecker
186 22 Andreas Kohlbecker
187
188 9 Andreas Kohlbecker
## Map Services
189 1 Andreas Kohlbecker
190
191 9 Andreas Kohlbecker
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:
192 1 Andreas Kohlbecker
193
194 10 Andreas Kohlbecker
* map service: @ ./map/ @
195 1 Andreas Kohlbecker
196 10 Andreas Kohlbecker
* legend service: @ ./legend/ @
197 1 Andreas Kohlbecker
198
199
200
201 59 Andreas Kohlbecker
### Response Content Types
202
203
204
The map service can respond with two different content types which are: 
205
206
207
* **Map images** - this is the default response content type
208
209
* **JSONP** - this is useful in order to use the maps in a dynamic map viewer like openlayers.
210
211
212
To enable the JSONP response type you need to add the img query parameter to the request URL:
213
214
215
~~~
216
img=false
217
~~~
218
 
219
220 10 Andreas Kohlbecker
221
## Layers
222
223
224 9 Andreas Kohlbecker
For wms areas are specified in shape files (polygons in *.shp + area index in *.shx).
225 1 Andreas Kohlbecker
226 10 Andreas Kohlbecker
227 1 Andreas Kohlbecker
The map service offers a set of default raster data and shape files e.g. for all 4 TDWG regions, ISO regions etc.
228 9 Andreas Kohlbecker
229 10 Andreas Kohlbecker
230 1 Andreas Kohlbecker
These predefined layers can be selected by the layer name, e.g. tdwg1 for TDWG regions level 1.  
231
232
233 9 Andreas Kohlbecker
 **Attribute:** 
234 10 Andreas Kohlbecker
235 1 Andreas Kohlbecker
236 10 Andreas Kohlbecker
237
~~~
238 22 Andreas Kohlbecker
(layer) l=<layer name>[:[<layer style id>][<shp file url>|<raster data url>]];...
239 1 Andreas Kohlbecker
~~~
240
241 13 Andreas Kohlbecker
The (layer) "l" attribute is an facultative one it is not needed if only predefined layers are used for a map.
242
243
244 1 Andreas Kohlbecker
Multiple layer definitions are separated by dash characters.
245
246
247
Where
248
249
* `<layer name>` is the name of either a default shape file offered by the server or a new name.
250
251
* `<layer style id>` is the identifier of a layerstyle 
252
253
254
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.
255
256
257
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>@. 
258
259
260 11 Andreas Kohlbecker
 **Available Layers (<layer name>)** 
261
262
263 24 Andreas Müller
* 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))
264 11 Andreas Kohlbecker
265 24 Andreas Müller
* 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))
266 11 Andreas Kohlbecker
267 24 Andreas Müller
* 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))
268 11 Andreas Kohlbecker
269 24 Andreas Müller
* 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))
270 11 Andreas Kohlbecker
271 23 Franck Theeten
* earth
272 11 Andreas Kohlbecker
273 36 Franck Theeten
* e_provinces
274
275 37 Franck Theeten
* several vmap0 layers (http://en.wikipedia.org/wiki/Vector_Map http://gis-lab.info/qa/vmap0-eng.html)
276 1 Andreas Kohlbecker
277 37 Franck Theeten
 
278 38 Franck Theeten
~~~
279
currently (8/8/2011) there are 76 vmap0 layers in the EDIT Geoserver WMS. 
280
     They are (roughly) divided in 4 zones:
281
         * Europe (layers beginning with 'vmap0_eu' in the EDIT WMS)
282
         * Asia and Oceania (layers beginning with 'vmap0_as' in the EDIT WMS 
283
         * Africa and South America (layers beginning with 'vmap0_afsa' in the EDIT WMS)
284
         * North America (layers beginning with 'vmap0_na' in the EDIT WMS)
285
~~~
286
* 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,
287
288
 ecological layers (soil, rivers, vegetation}, layers on infrastructure and habitat (urban areas, roads, railways) etc...
289
290
* Only parts of the information have been imported for the 3 other zones , but they all features at least the political boundaries:
291
292
* 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
293
294
* 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
295
296
* 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
297
298
* 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
299
300
301
The provinces are named and retrievable through "GetFeature" WMS queries.
302
303
304
* -It is possible to ask for more layers as the complete Vmap0 has been loaded into the PostGIS database feeding the EDIT WMS.
305
306
307
* -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:
308
309
310
311
*  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
312
313
314
* -An aggregate layer of all the national subdivisions of the world is available. 
315
316
317
* Its name is "*vmap0_world_national_boundaries*"
318
319
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
320
321
322
  
323
324
  
325
326
327
----
328
329 11 Andreas Kohlbecker
 
330 1 Andreas Kohlbecker
331 38 Franck Theeten
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)
332 25 Andreas Müller
333
334 27 Andreas Müller
 **Layer styles** 
335
336
337 1 Andreas Kohlbecker
Layer styles are defined by the layer_style attribute
338
339
340
~~~
341
(layer style) ls=<layer_style_id>:[<line_color>][/<line_width>][/<stroke_style_id>];..
342
~~~
343
344
Where 
345
346
* `layer_style_id` is the layers identifier
347
348
* `line_color` is the color of border lines used in the layer
349
350
* `line_width` is the width of the border lines
351
352
* `stroke_style_id` is an id for the stroke (still to be defined)
353 11 Andreas Kohlbecker
354 1 Andreas Kohlbecker
355
356
357
> [Pere]
358
359
> Shapefiles is the ESRI (propietary) format for storing vector data. The most performant way of storing areas are in postGIS database. 
360
361
> 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. 
362
363
>
364
365
366
> 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). 
367
368
>
369
370
>> [[Andreas|K]] So the solution could be like the following:
371
372
>> - We allow for example 20 extra layers as postGIS tables
373
374
>> - Shapefiles (or GML?) are inserted by shp2pgsql into one of the postGIS tables
375
376
>> - 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>
377
378
379
380
## Areas
381
382
383 23 Franck Theeten
*A.Attribute (for all layers)*: 
384 1 Andreas Kohlbecker
385
~~~
386 23 Franck Theeten
  (area data) ad=<layer name>:<field name>:<area set>[;..]
387
      <area set> ::= <area style ids>:<area id list>
388
      <area id list> ::= <area id>[,..]
389
~~~
390
391
Where 
392
393
394
* `<field name>` is the name of the field in the WMS layer that contains the <area style ids>
395
396
* `<area style ids>` is a string of one letter `[a-z,A-Z]` area style ids
397
398
* `<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.
399
400
401
e.g:
402
403 57 Andreas Kohlbecker
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
404 23 Franck Theeten
405
406
407
*B.Attribute (optional for precoded TDWG layers)*: 
408
409
~~~
410 1 Andreas Kohlbecker
  (area data) ad=<layer name>:<area set>[;..]
411
      <area set> ::= <area style ids>:<area id list>
412
      <area id list> ::= <area id>[,..]
413
~~~
414
415
Where 
416
417
418 23 Franck Theeten
* `<area style ids>` is a string of one letter `[a-z,A-Z]` area style ids
419 1 Andreas Kohlbecker
420 23 Franck Theeten
* `<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.
421 1 Andreas Kohlbecker
422 23 Franck Theeten
* `<field name>` (2nd parameter of previous case) can be dropped in this case.  
423 1 Andreas Kohlbecker
424
425
426
## Area Style
427
428
429
*Attribute*: 
430
431
~~~
432
  (area style) as=<area style id>:<area style definition>[;..]              
433
  
434
   <area style definition> ::= <pattern id>/<color>[/<style_label>] -  defines a pattern and foreground color to fill a shape with
435
   <area style definition> ::= <color>[/<style_label>] -  defines a background (fill) color for a shape
436
~~~
437
Where 
438
439
* `<pattern id>` is a number from 0 to 99 identifying a predefined fill pattern
440
441
* `<color>` is a RGB hex code always 6 letters long
442
443
* `<style_label>` is the label of the style in the legend
444
445
446
*Further improvement*: 
447
448
449
  Removing the unnecessary colons used as separator, they are just for readability. 
450
451
452
  Area styles can easily parsed without.
453 39 Franck Theeten
454
455
### Point Style
456
457
458
*attribute*:
459
460
461
~~~
462
os=indexer:shape/RGB_fillcolor/size_of_shape/label
463
(1 indexer; 4 parameters separated by “/”):
464
~~~
465
466
e.g:
467
468
os=1:c/0000FF/17/others
469
470
471
indexer	        =	1 (can also be text)
472
473
474
shape		= 	“c” (circle). other possible values: "c"=>circle; "s" =>star; "sq"=> square
475
476
477
fill color	=	0000FF (Blue)
478
479
480
size		=	17
481
482
483
label		= 	"others"
484
485
486
                         
487
488 1 Andreas Kohlbecker
489
490
491
## Grids
492
493
494
495
*Attributes*: 
496
497
498
~~~
499
(grid resolution) gr=<layer name>[:<layer style id>]:<long>[,<lat>] - specifies a grid layer
500
501
(grid data)       gd=<layer name>:<cell set>[;..]
502
                  <cell set> ::= <cell style id>:<cell id>
503
~~~
504
        
505
506
       
507
Where 
508
509
      `<layer name>` is the name of a predefined grid layer or a new name identifying the grid specified by the additional attributes.
510
511
      `<long>` is horizontal resolution in degrees eg. 1, 10, 0.6, 0.1 ...
512
513
514
      `<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
515
516
517
      <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. 
518
519
520
~~~
521
                  0   1 
522
                +---+---+
523
              0 | 00| 01|
524
                +---+---+
525
              1 | 10| 11|
526
                +---+---+
527
~~~
528
529
> 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). 
530
531
>
532
533
>> So we can ad  the following to the proposal (see above..)
534
535
                
536
~~~
537
      <cell style id>  is the id of a cell style .... [TODO]
538
~~~
539
540
 **Open questions:** 
541
542
543
* how to define style labels for the longitude and latitude axis?
544
545
546
547
## Occurrences
548
549
550
*Attributes*: 
551
552
553
~~~
554
  (occurrence data)  od=<occurrence set id>:<occurrence entry list>
555
  <occurrence entry list> ::= <occurrence entry>[;..]
556
  <occurrence entry> ::= <long>,<lat>[,<precision>]
557
  
558
  (occurrence style) os=<occurence style definition>[;..]
559
  <occurence style definition> ::= <occurrence set id>:<style>/<color>
560
~~~
561
562
Where
563
564
565
* `<occurrence set id>` is an number [0-9] on 1..n digits
566
567
* `<long>` is longitude in degrees of the occurrence point
568
569
* `<lat>`  is latitude in degrees of the occurrence point
570
571
* `<precision>` precision 
572
573
* `<color>` is a RGB hex code always 6 letters long
574
575
* `<style>` either one letter [[a-z|A-Z]] except 'u' and 'z' which are used for
576
577
  * u: u<unicode hex code(4 letters)> unicode character as occurrence point icon  
578
579
  * z: z<number> custom style reserved for future use  
580
581
  * c: circle
582
583
  * s: square
584
585
  * ....
586
587
588 9 Andreas Kohlbecker
589
## Legends
590
591
592
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. 
593
594
595
~~~
596
 (map legend type) mlt=<legend type id>
597
  <legend type id> ::= h|v // see below for explanation
598
599
 (map legend position) mlp=
600
  <legend position id> ::= 1|2|3|4|5|6|7|8  // see below for explanation
601
~~~
602
603
604
 **horizontal legend** (@mlt=h@):
605
606
~~~
607
item 1
608
item 2
609
item 3
610
~~~
611
612
 **vertical legend** (@mlt=v@):
613
614
~~~
615
item 1 item2 item 3
616
item 4 item 5 item 6
617
~~~
618
619
*legend positioning*:
620
621
~~~
622
+-----+
623
|1 2 3|
624
|4   5|
625
|6 7 8|
626
+-----+
627
~~~
628 1 Andreas Kohlbecker
629
630 62 Andreas Kohlbecker
### How to get legends separately from a map
631
632
633
634
The map service offers the `legends.php` endpoint which allows to get pure legends without a map. This exists for the versions v1.2 and v1.4_dev.
635
636
Two usage examples:
637
638
~~~
639
http://edit.africamuseum.be/edit_wp5/v1.2/legends.php?title=a:foreign|b:native|c:rare|d:unknown&as=a:329d2a,483eef,2,2_2|b:ab8dc9F,da1029,2,5_7|c:d2e347|d:f7555d&ms=60,50
640
http://edit.africamuseum.be/edit_wp5/v1.4_dev/legends.php?title=a:foreign|b:native|c:rare|d:unknown&as=a:329d2a,483eef,2,2_2|b:ab8dc9F,da1029,2,5_7|c:d2e347|d:f7555d&ms=60,50
641
~~~
642
643
 **Using the `legends.php` endpoints is however no longer recommended.** Please note that there is also a way to directly access the URL of the SLD generated for the legend in the JSON output of the main script `img=false` :
644
645
http://edit.africamuseum.be/edit_wp5/v1.4_dev/rest_gen.php?&img=false&recalculate=false&ms=512,512&bbox=-28.125,32.132821,54.84375,73.617196&l=background_gis:Y,earth:Z,&title=b:introduced%2C+naturalized|c:present|d:native%2C++doubtfully+native|a:native|f:extinct&ad=euromed_2013%3Aparent:a:It|euromed_2013%3Aemarea:f:Po|d:No&as=Z:ffffff,606060~|Y:1874CD~|a:ffaf00~0.1,|b:f781bf~0.1,|c:4daf4a~0.1,|d:377eb8~0.1,|f:4daf4a~0.1,&legend=1
646
647
648
then you can link it back to the WMS:
649
650
651
http://edit.africamuseum.be/geoserver/wms?REQUEST=GetLegendGraphic&VERSION=1.1.1&format=image/png&TRANSPARENT=TRUE&WIDTH=60&HEIGHT=50&layer=tdwg_level_3&SLD=http://edit.africamuseum.be/synthesys/www/v1/sld/sld_displayed_legend_euromed_2013_8e4a4b0aa1a16208028f552875575131.sld
652
653
654
655
656 1 Andreas Kohlbecker
## Map Image
657
658
659
Attributes:
660
661
~~~
662
  (map size)        ms=[<units>:][<width>][,<height>]
663
664
  (map resolution)  mr=<pdi>
665
~~~
666
  
667
668
Where 
669
670
* `<units>` is optional an is one of px, mm, cm, .... defaults is px
671
672
* `<pdi>` is the resolution of the image in dpi, default is 72dpi
673
674
675
*Open questions*:
676
677
678
* color space / profile definition could be important for print quality maps required? how to ?
679
680
* how to style and configure legends?
681 16 Pere Roca Ristol
682
683
684
## Labels
685
686
687
How to define for each layer if we are interested (or not) to view it's label?
688
689
Andreas K. suggested these two main options:
690
691
692
1) extend the labels parameter:
693
694
695
labels =<layer name>:[0|1],...
696
697
698
2) extend the layers parameter with something like:
699
700
701
(layer) l=<layer name>[[[<layer|style id>]],[[<labels_on>]|[/<shp file url>]][[<raster|data url>]]];...
702 28 Franck Theeten
703
704
705
706
## Background WMS layer
707
708
709
The REST services also provide possibility to display background layer coming from external WMS:
710
711
712
There are 3 parameters to take into consideration
713
714
715
  
716
717
1)   "externalwms"       : The base URL of the WMS to query ("root" of the GetCapabilities" request.
718
719
  
720
721
2)   [externalwmsversion]() The version of the WMS standard used by the server (OPTIONAL: default value is "1.1.1")
722
723
  
724
725
3)   "externalwmslayer"  : A list of layers coming from the same WMS (comma-separated) 
726
727
728
The complete syntax is the following:
729
730
731
~~~
732
externalwms=[base URI of the WMS]&externalwmsversion=[externalwmsversion]&externalwmslayer=[name_layer_1][,name_layer_2][,...name_layer_n]
733
~~~
734
735
736
737
e.g.:
738
739
740
741
~~~
742 57 Andreas Kohlbecker
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
743 28 Franck Theeten
~~~
744 40 Franck Theeten
745
746 43 Franck Theeten
747 44 Franck Theeten
## Available layers
748
749
750
751 49 Franck Theeten
### 1) topp:em_tiny_jan2003 _Added 2013/07/25_
752 48 Franck Theeten
  
753
(layer originating from the Helsinki Natural history museum for Euro+Med areas : http://dev.e-taxonomy.eu/trac/ticket/2707). 
754 1 Andreas Kohlbecker
755
756 43 Franck Theeten
757 48 Franck Theeten
758
759 1 Andreas Kohlbecker
## Available Projections
760
761 48 Franck Theeten
762
763 50 Franck Theeten
### 1) EPSG:7777777 _Added 2013/07/25_
764 48 Franck Theeten
765 1 Andreas Kohlbecker
Projection for topp:em_tiny_jan2003
766 48 Franck Theeten
767
WKT (geoserver "epsg.properties):
768
769 51 Andreas Kohlbecker
~~~
770 52 Andreas Kohlbecker
7777777=PROJCS[
771
	"Lambert_Conformal_Conic",
772
	GEOGCS[
773
		"GCS_Unknown",
774
		DATUM[
775
			"D_European_1950",
776
			SPHEROID[
777
				"International_1924",
778
				6378388,297
779
			]
780
		],
781
		PRIMEM[
782
			"Greenwich",
783
			0
784
		],
785
		UNIT[
786
			"Degree",
787
			0.017453292519943295
788
		]
789
	],
790
	PROJECTION[
791
		"Lambert_Conformal_Conic"
792
	],
793
	PARAMETER[
794
		"standard_parallel_1",
795
		42
796
	],
797
	PARAMETER[
798
		"standard_parallel_2",
799
		56
800
	],
801
	PARAMETER[
802
		"latitude_of_origin",
803
		35
804
	],
805
	PARAMETER[
806
		"central_meridian",
807
		24
808
	],
809
	PARAMETER[
810
		"false_easting",
811
		3000000
812
	],
813
	PARAMETER[
814
		"false_northing",
815
		100000
816
	],
817
	UNIT[
818
		"Meter",
819
		1
820
	]
821
]
822 1 Andreas Kohlbecker
~~~
823
Proj4 (PostGIS):
824
825 51 Andreas Kohlbecker
~~~
826 52 Andreas Kohlbecker
+proj= lcc + 42 + 56 + 35 + 24 + 3000000 + 100000 (id in the spatial_ref_sys_table is 7777777)
827 51 Andreas Kohlbecker
~~~
828 56 Andreas Kohlbecker
829
830
831
## latest developments
832
833
834
Preliminary documentation on experimental features are found in the following tickets (only accessible for registered developers after login):
835
836
837
*  #4150 (compile edit map service documentation of new features in version v1.4_dev and v1.5_dev)