Web Feature Services (WFS) advanced operations allow you filter your query by attribute or value. This is particularly useful when you are only interested in a subset of the data within an LDS layer or table.

You can run these CQL filter queries by copying and pasting the example URLs into your browser’s address bar after replacing the YOUR_API_KEY placeholder with your API key (sign into LDS to create your API key)

Determining attribute and feature values

To run these WFS filters you will first need to know the values or names of the attribute or features you want to filter on. 

Remember that filters are case sensitive. This applies across the board - to attributes and values. Where a dataset has a column name ‘lane-count’, a filter on this attribute must honour the lower case convention. A filter using ‘Lane-Count’, for example, would return an error.

Attribute names

Attribute or column names are listed under the Technical Details in the About page of any LDS dataset:

Screenshot showing Attributes field in LDS

Alternatively, you can run a DescribeFeatureType query on the layer. This query will also give you the name of the geometry column which you will need to know if you want to filter the data spatially. Note, the TypeName parameter:

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=DescribeFeatureType&typeName=layer-50329

This query run in the browser returns:

Screenshot highlighting named attributes in XML file

Note: the column named “GEOMETRY” which contains the spatial definition for this table. As a rule the spatial column is listed last when viewing the response of a Describe-Feature-Type request.

Some LINZ datasets are described in detail in a Data Dictionary. These will provide you with the attribute names for the datasets, as well as, schema information and attribute descriptions. Where relevant, they will also describe the relationship between individual tables/layers. 

View our data Dictionaries on the LINZ Data Service.

Other data dictionaries:

Feature values

In most cases, unless columns have a small number of unique values, you know the feature you’re looking for or you are familiar with the data, filtering based on specific feature values is not practical. Some datasets available through LDS can have many thousands of unique values within a single column.

The Data Table tab for any LDS vector or tabular dataset will show you the attribute data. For a dataset, such as Topo50 NZ Road Centrelines, you can use the column sort function to help you see the range of values for the columns. In this example, the ‘macronated’, ‘lane_count’, ‘way_count’ and ‘surface’ columns each have a small set of unique values you could use for filtering purposes.

View the Topo50 NZ Road Centrelines dataset

Simple feature filter

This example will return from the NZ Road Centreline (Topo50) layer in json format only those records where the road surface is classified as metalled:

View the NZ Road Centreline (Topo50) layer

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50329&cql_filter=surface='metalled'&outputformat=json

This filter will return all records from NZ Title Memorial List table related to the title number OT19C/115, 772955 and 769598. (Note: Access to this dataset requires your acceptance of the LINZ Licence for Personal Data). This type of filter is useful when you know the title number or other unique values and want to only access records containing that value:

View the NZ Title Memorial List table

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=table-51695&cql_filter=title_no= IN ('OT19C/115', '772955', '769598')

Compound feature filter

This WFS cql filter example will return a csv file all title records from the NZ Title Memorials List table that have a current lease against them. To further restrict the number of features returned, the request is also filtered by the land district of North Auckland.

Note: this land district is a LINZ survey administration boundary. It does not reflect the official boundaries of that district (see the LINZ Land Districts layer to view the boundaries).

View the NZ Title Memorials List table

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=table-51695&cql_filter=instrument_type='Lease' AND land_district='North Auckland' AND current='TRUE'&outputFormat=csv

This example will return from the NZ Parcels layer historic parcels that were intended to be Māori freehold or Māori customary land.

View the NZ Parcels layer

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-51571&cql_filter=status='Historic' AND parcel_intent='Maori'

Say you’re working for Auckland Council and for planning purposes are interested in all Unit Titles across the district. The request below will return from the NZ Property Titles layer records with a title attribute of ‘Unit’ issued in 2015 in North Auckland.

View the NZ Property titles layer

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50804&cql_filter=type='Unit' AND land_district='North Auckland' AND issue_date >'2014-12-31'

The ‘North Auckland’ land district is a LINZ survey administration boundary. It does not reflect the official boundaries of that district (see the LINZ Land Districts layer to view the boundaries). So, once you had this data you would need to link it against parcels in a GIS application and partition it by official TA boundary.

This next example uses a LIKE statement and % wildcard character to return from the NZ Property Title Estates List table current titles in a CSV file where the text describing the purpose of the land includes any reference to recreation or reserve.

View the NZ Property Title Estates List table

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?SERVICE=WFS&VERSION=2.0.0&request=GetFeature&typeNames=table-51566&cql_filter=purpose LIKE '%25Reserve%25' OR purpose LIKE '%25Recreation%25'&outputFormat=csv

Note: for this example to run successfully in the browser, the % wildcard character needs to be ascii encoded to %25.

Attribute filter

The examples above will return all fields for the requested records.  In some cases, you may want to return only a subset of attributes. This can be useful for quick lookups – just remember, you will need all attributes to fully understand and analyse the data and relationship across related datasets.

Attribute filters can be applied using the <PropertyName> property. Use a comma-separated list of values to specify the attributes you want returned. This example will return only the id, mark_type and order fields for the first 10 records from the NZ Protected Survey Marks dataset.

View the NZ Protected Survey Marks dataset

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50839&PropertyName=(id,mark_type,order)&count=10

You can, of course, combine this operation with the feature filters above to restrict the data returned even further. This example will return only the id, mark_type and order fields from the NZ Protected Survey Marks dataset where the order is 2:

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50839&PropertyName=(id,mark_type,order)&cql_filter=order='2'

Similarly, this example combines the PropertyName property with an ILIKE clause (case insensitive) to return specified attributes for records from the NZ Parcels layer that are subject to a statutory action (Act or Regulation) that has been notified through an official Gazette notice.

View the NZ Parcels layer

https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?SERVICE=WFS&VERSION=2.0.0&request=GetFeature&typeNames=layer-51571&PropertyName=(id,status,statutory_actions,titles)&cql_filter=statutory_actions ILIKE '%25Gazette%25'
Reference Category: Web services
Reference Tags: WFS, Attribute filter, Field filter, Data subset, Web feature services
Last Updated: 
23 August 2018