MapFish Protocol

This page describes the MapFish Protocol. The MapFish Protocol is a RESTful protocol for creating/reading/updating/deleting features.

Representation

The representation format is GeoJSON.

HTTP Interfaces

Read one feature

  • Request: GET http://www.example.fr/features/1.json
  • Response: GeoJSON FeatureCollection with one feature
    • success status code: 200 OK
  • Supported request parameters:
    • no_geom=true: so that the returned feature has no geometry ("geometry": null)
    • attrs={field1}[,{field2},...]: to restrict the list of properties returned in the feature

Read features

  • Request: GET http://www.example.fr/features
  • Response: GeoJSON Feature
    • success status code: 200 OK

  • Supported request parameters:
  • the no_geom and attrs parameters described in the previous section are also supported here
  • limit={num}: limit the number of features to num features (maxfeatures is an alias to limit)
  • offset={num}: skip num features
  • order_by={field}: order the features using field
  • dir=DESC|ASC: determine the ordering direction (applies only if order_by is specified)
  • lon={x}: the x coordinate of the center of the search region, this coord's projection system can be specified with the epsg parameter
  • lat={y}: the y coordinate of the center of the search region, this coord's projection system can be specified with the epsg parameter
  • tolerance={num}: the tolerance around the center of the search region, expressed in the units of the lon/lat coords' projection system
  • bbox={xmin,ymin,xmax,ymax}: a list of coordinates representing a bounding box, the coords' projection system can be specified with the epsg parameter
  • geometry={geojson}: a GeoJSON string representing a geometry, the coords' projection system can be specified with the epsg parameter
  • epsg={num}: the EPSG code of the lon, lat or box values
  • queryable={field1}[,{field2},...]}: the names of the feature fields that can be queried
  • {field}__{query_op}={value}: specify a filter expression, field must be in the list of fields specified by queryable, supported query_op's are:
    • eq: equal to
    • ne: not equal to
    • lt: lower than
    • lte: lower than or equal to
    • gt: greater than
    • gte: greater than or equal to
    • like
    • ilike

Examples:

  • Request: GET http://www.example.fr/features/?lon=5&lat=50&tolerance=200
  • Response: the features whose distance to point (5,50) is lower than or equal to 200 meters
  • Request: GET http://www.example.fr/features/?lon=5&lat=50
  • Response: the features that contain point (5,50)
  • Request: GET http://www.example.fr/features/?bbox=5,50,7,60
  • Response: the features within the bounding box (5,50,7,60)
  • Request: GET http://www.example.fr/features/?limit=3
  • Response: a maximum of 3 features
  • Request: GET http://www.example.fr/features/?limit=3&queryable=name,elevation&name__ilike=col&elevation__gte=1800&attrs=name,elevation&no_geom=true
  • Response: at most 3 features whose names include "col" and whose elevations are greater than or equal to 1800

Create/Update features

  • Request: POST http://www.example.fr/features or PUT http://www.example.fr/features
    • body: GeoJSON FeatureCollection
  • Response: GeoJSON FeatureCollection
    • success status code: 201 Created

Features with no ids ({id: null}) are created. Features with ids are updated.

Update a feature

  • Request: PUT http://www.example.fr/features/<id> where <id> is the feature id
    • body: GeoJSON Feature
  • Response: GeoJSON Feature
    • success status code: 201 Created

Delete a feature

Features are deleted one by one.

  • Request: DELETE http://www.example.fr/features/<id> where <id> is the feature id
  • Response
    • success status code: 204 No Content

Count features

  • Request: GET http://www.example.fr/features/count
  • Response: Plain text containing an integer representing the feature count
    • success status code: 200 OK
  • Request parameters for filtering: same as the Read features action

Example:

  • Request: GET http://www.example.fr/features/count?lon=5&lat=50&tolerance=2
  • Response: the number of features whose distance to point (5,50) is lower than or equal to 2 degrees