MapFish Protocol

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

Representation

The representation format is GeoJSON.

Interface

Read one feature

• Request: GET http://www.example.fr/features/1.json
• Response: GeoJSON FeatureCollection with one feature
  • success status code: 200 OK

Read features

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

• Request parameters for filtering: lon, lat, tolerance, box, maxfeatures, and epsg
  • maxfeatures: limit the number of features in the response
  • lon: the x coordinate of the center of the search region, the projection system of this coordinate can be specified with the epsg parameter
  • lat: the y coordinate of the center of the search region, the projection system of this coordinate can be specified with the epsg parameter
  • tolerance: the tolerance around the center of the search region, it is expressed in the units associated with the projection system of the lon/lat coordinates
  • box: a list of coordinates representing a bounding box ([xmin, ymin, xmax, ymax]), the projection system of the coordinates can be specified with the epsg parameter
  • epsg: the EPSG code of the lon, lat or box values

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/?box=5,50,7,60
• Response: the features within the bounding box (5,50,7,60)

• Request: GET http://www.example.fr/features/?maxfeatures=3
• Response: a maximum of 3 features

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 feaures action

Example:

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

Note:

• If using pylons, routing has to be modified to enable access to the /count action:

  map.connect(':controller/count', action='count')