Protocol

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