WFS reference¶

GetCapabilities¶

The GetCapabilities operation is a request to a WFS server for a list of the operations and services, or capabilities, supported by that server.

To issue a GET request using HTTP:

http://example.com/geoserver/wfs?
  service=wfs&
  version=1.1.0&
  request=GetCapabilities

The equivalent request using POST:

<GetCapabilities
 service="WFS"
 xmlns="http://www.opengis.net/wfs"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.opengis.net/wfs
 http://schemas.opengis.net/wfs/1.1.0/wfs.xsd"/>

GET requests are simplest to decode, but the POST requests are equivalent.

The parameters for GetCapabilities are:

Although all of the above parameters are technically required as per the specification, GeoServer will provide default values if any parameters are omitted from a request.

The GetCapabilities response is a lengthy XML document, the format of which is different for each of the supported versions. There are five main components in a GetCapabilities document:

DescribeFeatureType¶

DescribeFeatureType requests information about an individual feature type before requesting the actual data. Specifically, the operation will request a list of features and attributes for the given feature type, or list the feature types available.

The parameters for DescribeFeatureType are:

To return a list of feature types, the GET request would be as follows. This request will return the list of feature types, sorted by namespace:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=DescribeFeatureType

To list information about a specific feature type called namespace:featuretype, the GET request would be:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=DescribeFeatureType&
  typeNames=namespace:featuretype

GetFeature¶

The GetFeature operation returns a selection of features from the data source.

This request will execute a GetFeature request for a given layer namespace:featuretype:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype

Executing this command will return the geometries for all features in given a feature type, potentially a large amount of data. To limit the output you can restrict the GetFeature request to a single feature by including an additional parameter, featureID and providing the ID of a specific feature. In this case, the GET request would be:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype&
  featureID=feature

If the ID of the feature is unknown but you still want to limit the amount of features returned, use the count parameter for WFS 2.0.0 or the maxFeatures parameter for earlier WFS versions. In the examples below, N represents the number of features to return:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype&
  count=N

http://example.com/geoserver/wfs?
  service=wfs&
  version=1.1.0&
  request=GetFeature&
  typeName=namespace:featuretype&
  maxFeatures=N

Exactly which N features will be returned depends in the internal structure of the data. However, you can sort the returned selection based on an attribute value. In the following example, an attribute is included in the request using the sortBy=attribute parameter (replace attribute with the attribute you wish to sort by):

http://example.com/geoserver/wfs?
   service=wfs&
   version=2.0.0&
   request=GetFeature&
   typeNames=namespace:featuretype&
   count=N&
   sortBy=attribute

The default sort operation is to sort in ascending order. Some WFS servers require the sort order to be specified, even if an ascending order sort if required. In this case, append a +A to the request. Conversely, add a +D to the request to sort in descending order as follows:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype&
  count=N&
  sortBy=attribute+D

There is no obligation to use sortBy with count in a GetFeature request, but they can be used together to manage the returned selection of features more effectively.

To restrict a GetFeature request by attribute rather than feature, use the propertyName key in the form propertyName=attribute. You can specify a single attribute, or multiple attributes separated by commas. To search for a single attribute in all features, the following request would be required:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype&
  propertyName=attribute

For a single property from just one feature, use both featureID and propertyName:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype&
  featureID=feature&
  propertyName=attribute

For more than one property from a single feature, use a comma-seaprated list of values for propertyName:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype&
  featureID=feature&
  propertyName=attribute1,attribute2

While the above permutations for a GetFeature request focused on non-spatial parameters, it is also possible to query for features based on geometry. While there are limited options available in a GET request for spatial queries (more are available in POST requests using filters), filtering by bounding box (BBOX) is supported.

The BBOX parameter allows you to search for features that are contained (or partially contained) inside a box of user-defined coordinates. The format of the BBOX parameter is bbox=a1,b1,a2,b2``where ``a1, b1, a2, and b2 represent the coordinate values. The order of coordinates passed to the BBOX parameter depends on the coordinate system used. (This is why the coordinate syntax isn’t represented with x or y.) To specify the coordinate system, append srsName=CRS to the WFS request, where CRS is the Coordinate Reference System you wish to use.

As for which corners of the bounding box to specify, the only requirement is for a bottom corner (left or right) to be provided first. For example, bottom left and top right, or bottom right and top left.

An example request involving returning features based on bounding box would be in the following format:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetFeature&
  typeNames=namespace:featuretype&
  srsName=CRS
  bbox=a1,b1,a2,b2

LockFeature¶

A LockFeature operation provides a long-term feature locking mechanism to ensure consistency in edit transactions. If one client fetches a feature and makes some changes before submitting it back to the WFS, locks prevent other clients from making any changes to the same feature, ensuring a transaction that can be serialized. If a WFS server supports this operation, it will be reported in the server’s GetCapabilities response.

In practice, few clients support this operation.

Transaction¶

The Transaction operation can create, modify, and delete features published by a WFS. Each transaction will consist of zero or more Insert, Update, and Delete elements, with each transaction element performed in order. Every GeoServer transaction is atomic, meaning that if any of the elements fail, the transaction is abandoned and the data is unaltered. A WFS server that supports transactions is sometimes known as a WFS-T server. GeoServer fully supports transactions.

More information on the syntax of transactions can be found in the WFS specification and in the GeoServer sample requests.

GetGMLObject¶

A GetGMLObject operation accepts the identifier of a GML object (feature or geometry) and returns that object. This operation is relevant only in situations that require Complex Features by allowing clients to extract just a portion of the nested properties of a complex feature. As a result, this operation is not widely used by client applications.

GetPropertyValue¶

A GetPropertyValue operation retrieves the value of a feature property, or part of the value of a complex feature property, from a data source for a given set of features identified by a query.

This example retrieves the geographic content only of the features in the topp:states layer:

http://example.com/geoserver/wfs?
  service=wfs&
  version=2.0.0&
  request=GetPropertyValue&
  typeNames=topp:states&
  valueReference=the_geom

The same example in a POST request:

<wfs:GetPropertyValue service='WFS' version='2.0.0'
 xmlns:topp='http://www.openplans.org/topp'
 xmlns:fes='http://www.opengis.net/fes/2.0'
 xmlns:wfs='http://www.opengis.net/wfs/2.0'
 valueReference='the_geom'>
  <wfs:Query typeNames='topp:states'/>
</wfs:GetPropertyValue>

To retrieve value for a different attribute, alter the valueReference parameter.

GetFeatureWithLock¶

A GetFeatureWithLock operation is similar to a GetFeature operation, except that when the set of features are returned from the WFS server, the features are also locked in anticipation of a subsequent transaction operation.

This POST example retrieves the features of the topp:states layer, but in addition locks those features for five minutes.

<wfs:GetFeatureWithLock service='WFS' version='2.0.0'
 handle='GetFeatureWithLock-tc1' expiry='5' resultType='results'
 xmlns:topp='http://www.openplans.org/topp'
 xmlns:fes='http://www.opengis.net/fes/2.0'
 xmlns:wfs='http://www.opengis.net/wfs/2.0'
 valueReference='the_geom'>
  <wfs:Query typeNames='topp:states'/>
</wfs:GetFeatureWithLock>

To adjust the lock time, alter the expiry parameter.

CreateStoredQuery¶

A CreateStoredQuery operation creates a stored query on the WFS server. The definition of the stored query is encoded in the StoredQueryDefinition parameter and is given an ID for a reference.

This POST example creates a new stored query (called “myStoredQuery”) that filters the topp:states layer to those features that are within a given area of interest (${AreaOfInterest}):

<wfs:CreateStoredQuery service='WFS' version='2.0.0'
 xmlns:wfs='http://www.opengis.net/wfs/2.0'
 xmlns:fes='http://www.opengis.org/fes/2.0'
 xmlns:gml='http://www.opengis.net/gml/3.2'
 xmlns:myns='http://www.someserver.com/myns'
 xmlns:topp='http://www.openplans.org/topp'>
  <wfs:StoredQueryDefinition id='myStoredQuery'>
    <wfs:Parameter name='AreaOfInterest' type='gml:Polygon'/>
    <wfs:QueryExpressionText
     returnFeatureTypes='topp:states'
     language='urn:ogc:def:queryLanguage:OGC-WFS::WFS_QueryExpression'
     isPrivate='false'>
      <wfs:Query typeNames='topp:states'>
        <fes:Filter>
          <fes:Within>
            <fes:ValueReference>the_geom</fes:ValueReference>
             ${AreaOfInterest}
          </fes:Within>
        </fes:Filter>
      </wfs:Query>
    </wfs:QueryExpressionText>
  </wfs:StoredQueryDefinition>
</wfs:CreateStoredQuery>

DropStoredQuery¶

A DropStoredQuery operation drops a stored query previous created by a CreateStoredQuery operation. The request accepts the ID of the query to drop.

This example will drop a stored query with an ID of myStoredQuery:

http://example.com/geoserver/wfs?
  request=DropStoredQuery&
  storedQuery_Id=myStoredQuery

The same example in a POST request:

<wfs:DropStoredQuery
 xmlns:wfs='http://www.opengis.net/wfs/2.0'
 service='WFS' id='myStoredQuery'/>

ListStoredQueries¶

A ListStoredQueries operation returns a list of the stored queries currently maintained by the WFS server.

This example lists all stored queries on the server:

http://example.com/geoserver/wfs?
  request=ListStoredQueries&
  service=wfs&
  version=2.0.0

The same example in a POST request:

<wfs:ListStoredQueries service='WFS'
 version='2.0.0'
 xmlns:wfs='http://www.opengis.net/wfs/2.0'/>

DescribeStoredQueries¶

A DescribeStoredQuery operation returns detailed metadata about each stored query maintained by the WFS server. A description of an individual query may be requested by providing the ID of the specific query. If no ID is provided, all queries are described.

This example describes the exsting stored query with an ID of urn:ogc:def:query:OGC-WFS::GetFeatureById:

http://example.com/geoserver/wfs?
  request=DescribeStoredQueries&
  storedQuery_Id=urn:ogc:def:query:OGC-WFS::GetFeatureById

The same example in a POST request:

<wfs:DescribeStoredQueries
 xmlns:wfs='http://www.opengis.net/wfs/2.0'
 service='WFS'>
  <wfs:StoredQueryId>urn:ogc:def:query:OGC-WFS::GetFeatureById</wfs:StoredQueryId>
</wfs:DescribeStoredQueries>