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

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

Here are examples of some of the additional parameters you can use to filter or transform your request:

ParameterDescriptionExample
countLimits the number of features returned (WFS 1.1, 2.0). The syntax for WFS 1.0 is maxfeaturescount=4
maxfeatures=4
SRSName        Enables on the fly coordinate system transformationSRSName=EPSG:2193
(EPSG for NZTM2000)
PropertyName        Returns only specified attributes/columnsPropertyName=id,name
BBOX        A spatial filter that returns features where a geometry is located within a bounding boxBBOX=(shape,-36.764156,174.975230,-36.817467,175.023120)
outputformatControls the file format of your request. Supports json, csv and kmloutputformat=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

Here’s a WFS GetFeature request using a CQL filter (note the HTTP "cql_filter" parameter). The NZ Primary Parcels layer includes current primary parcels that are intended for one of 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 use 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 you to build more complex expressions.

OGC filter encoding

Geoserver OGC filter reference

Here’s 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 your 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:

Directly in your browser

Build your query manually in notepad, for example, then paste the URL into the address bar in your browser. Make use of 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.

Both 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 is the real power of WFS as it 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 does some of the heavy lifting that would otherwise need to be coded manually. It can be run from the commandline 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

Reference Category: Web services
Reference Tags: WFS, Filter parameter, OGC filter, CQL filter, WFS browser query, Web feature services
Last Updated: 
21 August 2018