This documentation describes some of the attribute and spatial filters you can add to your changeset request. This lets you maintain a subset of a dataset.
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. The more complex OGC filter method is comparable to those used for changeset scripted process, so some of the examples are also provided in OGC format.
See our documentation on advanced WFS filtering for more examples (links below).
Filtering and change actions
Because changesets are generated on request, the changeset actions returned are specific to any additional filter parameters applied in the request.
Applying a filter to your changeset request can impact the definition of the changeset action. If you apply a filter to your changeset request, some feature changes that apply to the whole dataset could be given a different action type in the context of the filtered subset. This is particularly important for feature updates.
For example, you might apply an attribute filter to a changeset request to the NZ Road Centrelines (Topo50) dataset so that it returns change records only where the surface is metalled. This means:
- a road feature that was unmetalled and has become metalled will appear as INSERT for the filtered changeset, instead of UPDATE for the whole dataset
- a road feature that was metalled and has become sealed will appear as DELETE for the filtered changeset, instead of UPDATE for the whole dataset
Changeset attribute filters
You can add WFS advanced operations to your changeset request to filter your query by attribute or value. This is useful if you want to maintain your own copy of a subset of LDS data or are only interested in changes within a subset of data.
See our documentation on WFS filtering by attribute or feature for information on using attribute filters, and for more examples of filters you can use.
This example makes a request to the NZ Street Address layer that will return any street address records that changed between 5 August 2018 and 9 September 2018 within Queenstown.
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs? service=WFS&version=2.0.0& request=GetFeature& typeNames=layer-53353-changeset& viewparams=from:2018-08-05;to:2018-09-09& cql_filter=town_city='Queenstown'
The OGC filter version of this request is:
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs? service=WFS&version=2.0.0& request=GetFeature& typeNames=layer-53353-changeset& viewparams=from:2018-08-05;to:2018-09-09& 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"> <PropertyIsEqualTo> <PropertyName>town_city</PropertyName> <Literal>Queenstown</Literal> </PropertyIsEqualTo> </Filter>
Note that 'town_city’ is sourced from the NZ Localities dataset (owned by Fire and Emergency New Zealand).
You can also use filtered changeset requests to keep track of changes to particular records. For example, the following query will show ownership changes related to a particular group of property titles over a particular time period.
This example will return from the NZ Property Title Owners layer a dataset of the changes to any of the specified title numbers (where the owner is Wellington City Council) between 1 September 2018 and 9 September 2018. (Note that access to this dataset requires acceptance of the LINZ Licence for Personal Data).
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs? service=WFS&version=2.0.0& request=GetFeature&typeNames=layer-50806-changeset& viewparams=from:2018-09-01T07:35:14.088816Z;to:2018-09-08T10:40:14.618490Z& propertyName=(id,title_no,owner,__change__)& cql_filter=title_no IN ('WN44D/514', 'WN452/129', '605839', 'WN50D/409', 'WN25D/1000')
Note that this example adds milliseconds to the time parameter of the request. This is necessary because the LDS update process does not finish exactly at midnight. If 2018-09-08 is specified, LDS will interpret it as 2018-09-08 0:00.00000 (midnight) which may be earlier than the actual update time. To avoid missing data, we advise adding a day’s buffer to your request.
You can use a compound attribute filter to further refine your changeset request.
The example below uses a compound attribute filter to return all new (that is, inserted) unit titles from the NZ Property Titles List table issued in August 2018.
Unit titles are linked to a single supplementary record sheet (SRS) title, which are recorded in the 'title_no_srs' column. This query identifies unit titles by the existence of a value in the SRS title number column. A further condition is then placed on the request so that records are returned only where the change action is an 'insert' (that is,. it skips updates and deletes):
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs? service=WFS&version=2.0.0& request=GetFeature& typeNames=table-51567-changeset& viewparams=from:2018-08-01;to:2018-09-01& cql_filter=title_no_srs IS NOT NULL and __change__='INSERT'
You can also add WFS advanced operations to your changeset request to filter your query based on geometry. This is useful when you are only interested in data related to a specific location.
See our documentation on WFS spatial filtering for tips and tricks, and for more examples of spatial filters you can use.
This example uses a simple bbox (bounding box) spatial filter to return changeset data within a specified area. This request will return records from the NZ Survey Boundary Marks layer that have changed between 7 July and 25 August 2018 in an area north of Wellington.
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs? service=WFS&version=2.0.0& request=GetFeature& typeNames=layer-50774-changeset& viewparams=from:2018-07-07;to:2018-08-25& cql_filter=bbox(shape,-41.19292,174.79827,-41.22143,174.83680)& SRSName=EPSG:2193
The OGC filter version of this request is:
http://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs? VERSION=2.0.0&request=GetFeature& typeNames=layer-50774-changeset& viewparams=from:2018-07-07;to:2018-08-25& 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> <BBOX> <PropertyName>shape</PropertyName> <gml:Box srsName='EPSG:2193'> <gml:coordinates>-41.19292,174.79827 -41.22143,174.83680</gml:coordinates> </gml:Box> </BBOX> </And> </Filter>
Survey mark records in our chosen locality that have changed between July and August 2018 are in green below. These are also displayed against all survey marks in the wider area.
See our spatial filtering documentation for further examples of spatial filters you can apply to your changeset requests.