WFS filter methods and parameters

An introduction to some of the parameters you can add to your Web Feature Services (WFS) request to filter data, filter methods, and the tools to run them.

On this page

URL parameters

A basic WFS 2.0 GetFeature URL for requesting data has the following syntax:

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?REQUEST=GetFeature&typeNames=LAYER_ID
  • YOUR_API_KEY – your LDS API key (sign into LDS to create your key)
  • LAYER_ID – the identifier of the LDS dataset

The additional parameters you can use to filter or transform your request include:

Parameter Description Example
count Limits the number of features returned (WFS 1.1, 2.0). The syntax for WFS 1.0 is maxfeatures count=4
maxfeatures=4
SRSName         Enables on-the-fly coordinate system transformation SRSName=EPSG:2193
(EPSG for NZTM2000)
PropertyName         Returns only specified attributes or columns PropertyName=id,name
BBOX         A spatial filter that returns features where a geometry is located within a bounding box BBOX=(shape,-36.764156,174.975230,-36.817467,175.023120)
outputformat Controls the file format of your request. Supports json, csv and kml outputformat=json

Use the LDS Changeset API to request only the data that has changed between dataset revisions

For a full list of filter parameters, see the reference links below for CQL and OGC filter methods.

Filter methods

ECQL filters

CQL (Common Query Language) is an extension provided by the Geoserver software we use in LDS. CQL is a basic query language which is simple and fast to read and write and looks very similar to SQL.

ECQL filter reference

A WFS GetFeature request using a CQL filter (note the HTTP 'cql_filter' parameter) is demonstrated below. The NZ Primary Parcels layer includes current primary parcels intended for a range of purposes including Crown ownership, lake or river, or road or railway.

In this example we filter the NZ Primary Parcels layer to only return parcels where they are intended for roading:

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?

  VERSION=2.0.0&

  REQUEST=GetFeature&typeNames=layer-50772&

  cql_filter=parcel_intent='Road'

For ease of authoring and demonstration, the majority of examples in this documentation are provided in CQL format.

View the NZ Primary Parcels layer

OGC filters

OGC filters are the official method for filtering WFS queries. This filtering method draws from the XML standard and allows more complex expressions.

OGC filter encoding

Geoserver OGC filter reference

The following example is the same request as above but using an OGC Filter (note the HTTP 'filter' parameter):

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?VERSION=2.0.0&REQUEST=GetFeature&typeNames=layer-50772&filter=<?xml version="1.0"?>
<Filter xmlns="http://www.opengis.net/ogc" xmlns:v="http://data.linz.govt.nz/ns/v" xmlns:gml="http://www.opengis.net/gml"> 
<And>
        <PropertyIsEqualTo>
<PropertyName>parcel_intent</PropertyName>
<Literal>Road</Literal>
</PropertyIsEqualTo>
</And>
</Filter>

Running a filter

If you’re using a GIS application, your app is likely to have a built-in query building tool to help you build and run these advanced WFS filters. If you don’t have a GIS app or want to run your query outside a specific application you can also run these filters in your browser of through a scripted process or utility.

Directly in your browser

You can build your query in Notepad, for example, then paste the URL into the address bar in your browser. You can use the outputformat parameter described in our Changeset API documentation to specify the file format for your request to be returned in. If you don’t specify an output format the results will be displayed in your browser.

The queries above can be pasted into your browser to return results. Just remember to replace the YOUR_API_KEY placeholder with your own key.

Read the changeset API documentation

Through a scripted process or utility

Any programming language that can make web requests can use WFS and apply filters to these requests. Because the WFS URL is just a string of text characters, the URL including the filter can be created on the fly by a script in response to user input or predetermined logic. This means that WFS enables the automation of processes that rely on LDS data.

One example of such a tool is GDAL/OGR. GDAL/OGR is a library of software tools for data translation and processing which reduces the need for manual coding. It can be run from the command line or accessed through an API for Python, C and C++.

Get the free GDAL binary download for Windows, MAC and LINUX

Run WFS filter queries in GDAL using OGR SQL statements