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.
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.
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