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.
A basic WFS 2.0 GetFeature URL for requesting data has the following syntax:
- 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:
|count||Limits the number of features returned (WFS 1.1, 2.0). The syntax for WFS 1.0 is maxfeatures||count=4|
|SRSName||Enables on the fly coordinate system transformation||SRSName=EPSG:2193|
(EPSG for NZTM2000)
|PropertyName||Returns only specified attributes/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|
For a full list of filter parameters, see the reference links below for CQL and OGC filter methods.
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.
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:
For ease of authoring and demonstration, the majority of examples in this documentation are provided in CQL format.
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.
Here’s the same request as above but using an OGC Filter (note the HTTP "filter" parameter):
<Filter xmlns="http://www.opengis.net/ogc" xmlns:v="http://data.linz.govt.nz/ns/v" xmlns:gml="http://www.opengis.net/gml">
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.
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++.