How to add a spatial or attribute filter to your changeset request to further refine the changeset records returned.
This documentation describes and provides examples of some of the useful attribute and spatial filters you can append to your changeset request, allowing you to 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. As the more complex OGC filter method is comparable to those used for changeset scripted process, some of the examples below are also provided in OGC format.
See our documentation on advanced WFS filtering for more examples (links below).
Filtering and change actions
You need to be mindful that applying a filter to your changeset request can impact the definition of the changeset action. If you apply a filter to your changeset request, certain feature changes (in particular feature updates) that apply to the whole dataset could be given a different action type in the context of the filtered subset.
In short, as changesets are generated on request, the changeset actions returned are specific to any additional filter parameters applied in the request.
For example, say you have applied an attribute filter to your changeset request to the NZ Road Centrelines (Topo50) dataset so that it returns change records only where the surface=metalled:
- 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 been changed to ‘sealed’ will appear as a DELETE for filtered change-set, instead of UPDATE for the whole dataset
Changeset attribute filters
You can add WFS advanced operations to your changeset request to allow you filter your query by attribute or value. This is really 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 tips and tricks 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 have changed between 5 August and 9 September within Queenstown.
The OGC filter version of this request is:
<Filter xmlns=http://www.opengis.net/ogc xmlns:v="http://data.linz.govt.nz/ns/v" xmlns:gml="http://www.opengis.net/gml">
Note: town_city’ is sourced from the NZ Localities dataset (owned by NZ Fire Service).
You can also use filtered changeset requests to keep track of changes to particular records. For example, if you are interested in ownership changes related to a particular group of property titles over a particular time period, you could use a query like that below.
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: Access to this dataset requires your acceptance of the LINZ Licence for Personal Data).
cql_filter=title_no IN ('WN44D/514', 'WN452/129', '605839', 'WN50D/409', 'WN25D/1000')
Note: This example adds milliseconds to the time parameter of the request. This is 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 earlier than the actual update time. To avoid missing data, we advise you add a day’s buffer to your request.
Use a compound attribute filter to refine your changeset request even further.
This example below uses a compound attribute filter to return all new (i.e. 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. We then place a further condition on the request so that records are returned only where the change action is an INSERT (i.e. it skips Updates and Deletes):
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 particularly 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.
The OGC filter version of this request is:
<Filter xmlns="http://www.opengis.net/ogc" xmlns:v="http://data.linz.govt.nz/ns/v" xmlns:gml="http://www.opengis.net/gml">
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.