Sunday, 16 February 2014

Cool things to do with the mapguide-rest API: Part 2

Now for part 2 of the cool things you can do with the mapguide-rest API.

Making a new MgMap

mapguide-rest provides a shim to the CREATERUNTIMEMAP operation that returns the same response as the operation we've introduced for the MapGuide 2.6 release. Except this one can work with older releases as well.

POST http://servername/mapguide/rest/services/createmap.xml
mapdefinition = Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition
requestedfeatures = 7

Or if you want a JSON version

POST http://servername/mapguide/rest/services/createmap.json
mapdefinition = Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition
requestedfeatures = 7

Creating a map with the above operation will also create a selection set as well with the same map name (which you can find out inside the response of the above operation)

MgMap interaction

Having created a Runtime Map, here's how you can describe and interact with it.

In case you created a Runtime Map without requesting a layer structure, you can request it like so:

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layers.xml

Or if you want a JSON version

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layers.json

You can list the groups in the same fashion

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layergroups.xml

Or if you want a JSON version

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/layergroups.json

But the most important thing you want to do with a runtime map is to render an image of it, here's how you do it

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/overlayimage.png?x=-87.73&y=43.74&scale=75000&width=800&height=600&behavior=2

Note that like GETDYNAMICMAPOVERLAYIMAGE, setting X/Y/Scale/DPI/width/height modifies the state of the MgMap. Knowing some math, you have the means of building a basic map viewer by tweaking the x, y and scale parameters based on mouse clicks and movements.

If you want to request a non-overlay image (ie. GETMAPIMAGE instead of GETDYNAMICMAPOVERLAYIMAGE), just replace overlayimage.png with image.png

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/image.png?x=-87.73&y=43.74&scale=75000&width=800&height=600

You can also request a DWF plot of this map in its current view as well

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/plot.dwf

Or if you have a PrintLayout, you can request a DWF plot using the specified layout.

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/plot.dwf?printlayout=Library://Samples/Sheboygan/Layouts/SheboyganMap.PrintLayout

Map Selection interaction

Like the Runtime Map, there are many ways to interact with a map selection. Like the Runtime Map, interaction with a map selection requires a session id and the map name.

Here's how you get the raw XML of the selection

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/xml

Here's how you can describe what layers are in the selection set

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/layers.xml

Or if you want a JSON version

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/layers.json

If you want to get the actual selected features

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/features.xml/Parcels

Or if you want a more usable format like GeoJSON

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/features.geojson/Parcels

And with any request that returns feature data, we support transform-ability out of the box

GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/features.geojson/Parcels?transformto=WGS84.PseudoMercator

There are 2 ways to manipulate selections.

First is by using the shim to QUERYMAPFEATURES

PUT http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection
geometry = POLYGON((-87.72464513939002 43.756626600485,-87.72464513939002 43.757316392651,-87.723570655439 43.757316392651,-87.723570655439 43.756626600485,-87.72464513939002 43.756626600485))
selectionvariant = INTERSECTS
requestdata = 15
selectioncolor = 0xFF000000
selectionformat = PNG
maxfeatures = -1
persist = 1

format = json

The other way is to POST the selection XML 

POST http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/xml

OpenLayers support

If you want to see more concrete examples of map and selection interaction, you can check out the OpenLayers samples included with mapguide-rest, which have been ported over from the ones that will be included in MapGuide Open Source 2.6. These sample use a new OpenLayers.Layer.MapGuideREST class which uses the REST APIs offered by mapguide-rest.

Next post will focus on the other half of mapguide-rest, the data publishing replacement for GeoREST


ChrisGo said...

I like it a lot! I can't wait to see this fully implemented and supported. MapGuide 2.6 here we come.

Tom Buch said...

Hi Jackie,

I try to obtain a dwf using :
GET http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Map/plot.dwf

I installed rest on MGOS 2.5 but i don't find the repository

So the request rutuns 404 error.

There is an aditionnal plugin or something else to complete the rest plugin?

Thank you.

Jackie Ng said...

Did you install the ARR module for IIS and rename web.config.iis to web.config?

Otherwise the "clean" URLs I am using as examples do not work, and you have to use


instead of


Tom Buch said...

ok, it works better, thank you!

I have 2 other questions :
1. I display my map and I execute the url, the system open the result in dwf.
I pan or zoom in my map and try again.
The dwf is not refresh. I try to clear the cache browser but y have the same result.

Thanks again.
Do you knows where is the cache of this plot?

2. Do yo know if it's possible to configure the toolbox in French?

Jackie Ng said...

Have a look at the "kitchen sink" example I just added:

It has DWF plot URLs, and they produce DWF plots that reflect what you're currently seeing on the map.

Scott Hameister said...

I am not having luck with Creating Selection with REST and PUT

Not even with POST and X-HTTP-Method-Override: I get "Method not allowed" with Put and "UnhandledError" with "Unhandled Exception" with the Work around

I saw a reference to POST http://servername/mapguide/rest/session/my-mapguide-session-id/my-map-name.Selection/xml
but I cant get that to work either
'geometry' : 'POLYGON((288438 1140677,290356 1140677, 290356 1137948,288438 1137948))',
'selectionvariant' : 'INTERSECTS',
'requestdata' : 15,
'selectioncolor' : '0xFF000000',
'selectionformat' : 'PNG',
'maxfeatures' : -1,
'persist' : 1,

'format' : 'json'