Additions to the MapFish Protocol

We recently added new stuff to the MapFish Protocol.

As a refresher, let’s first take a look at what the MapFish Protocol had before the new additions.

(Note that you’d need the JSONovich FireFox extension to see the output of the examples given below in your web browser.)

Geographic query params

• box={x1},{y1},{x2},{y2}: the features within the specified bounding box
• geometry={geojson_string}: the features within the specified geometry
• lon={lon}&lat={lat}&tolerance={tol}: the features within the specified tolerance of the specified lon/lat

Examples:

• http://demo.mapfish.org/mapfishsample/trunk/summits?box=6.2,45.6,6.3,45.7
• http://demo.mapfish.org/mapfishsample/trunk/summits?geometry={“type”:”Polygon”,”coordinates”:[[[6.2,45.6],[6.3,45.6],[6.3,45.7],[6.2,45.7],[6.2,45.6]]]}
• http://demo.mapfish.org/mapfishsample/trunk/summits?lon=6.2&lat=45.6&tolerance=0.1

Limiting and Sorting

• limit={num}: the maximum number of features returned
• offset={num}: the number of features to skip
• order_by={field_name}: the name of the field to use to order the features
• dir=ASC|DESC: the ordering direction

Examples:

• http://demo.mapfish.org/mapfishsample/trunk/summits?limit=10
• http://demo.mapfish.org/mapfishsample/trunk/summits?limit=10&offset=2
• http://demo.mapfish.org/mapfishsample/trunk/summits?limit=10&offset=2&order_by=elevation
• http://demo.mapfish.org/mapfishsample/trunk/summits?limit=10&offset=2&order_by=elevation&dir=ASC
• http://demo.mapfish.org/mapfishsample/trunk/summits?limit=10&offset=2&order_by=elevation&dir=DESC

The new params

• no_geom=true|false: so that the returned feature has no geometry (“geometry”: null)
• attrs={field1}[,{field2},...]: to restrict the list of properties returned in the features
• queryable={field1}[,{field2},...]: the names of the feature fields that can be queried
• {field}__{query_op}={value}: filter expression, field must be in the list of fields specified by queryable, query_op is one of “eq”, “ne”, “lt, “le”, “gt”, “ge”, “like”, “ilike”

And now an example combining all the new parameters:

• http://demo.mapfish.org/mapfishsample/trunk/summits?queryable=name,elevation&name__ilike=col&elevation__gte=3500&attrs=name,elevation&no_geom=true

The above query returns a GeoJSON representation of the summits whose names include “col” and whose elevations are greater than or equal to 3500. The returned features have no geometry and their attributes include “name” and “elevation” only.

Not including the geometry in the features makes the parsing in the browser much faster, so for cases where the geometries aren’t needed this is a big win.

Credits for the “queryable={field}&{field}__{query_op}={value}” syntax goes to FeatureServer!