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 in to LDS to create your API key).
Spatial operators
There are many operators you can use to spatially filter data, such as bbox (bounding box). These let you search for data based on the relationship between geometry values:
- disjoint
- equals
- intersects
- within
- overlaps
Read CQL filter reference documentation
Read OGC filter reference documentation
Spatial parameters
When performing spatial operations you need to specify the geometry column and the geometry type, as well as the coordinates.
For all LDS property and ownership, street address and geodetic data the geometry column is ‘shape’. For most other layers, including hydrographic and topographic data, the column name is 'geometry'. You can find the name of the column containing the spatial definition by running a DescribeFeatureType query on the dataset. As a rule, the spatial column is listed last when viewing the response of a describe feature type request.
The following code snippets show the format to specify the spatial parameters using the CQL and OGC methods.
CQL filter
cql_filter=Intersects(shape,POINT(-45.891523 170.467375))
- Intersects – the spatial operator
- shape – the name of the column containing the spatial definition of the dataset
- POINT – the geometry type of the values you are specifying
OGC filter
Intersects> PropertyName>shapePropertyName> Literal> Point srsName="http://www.opengis.net/gml/srs/epsg.xml#4167"> gml:coordinates>-45.891523 170.467375gml:coordinates> Point> Literal> Intersects>See the 'intersects' example below to see this spatial operator in action.
Coordinate format and order
To effectively use spatial filters, you need to ensure:
- the coordinate value of your filter aligns with the unit of the source dataset
- the coordinates are specified in the same order in which they are defined in the EPSG parameter database.
Go to the EPSG parameter database
If you are querying an LDS dataset where the source data is in NZTM2000 (EPSG:2193) the coordinate values must be in the same projection (unit based on meters) and the order is y/x:
5939800 1722599, 5916017 1760652
For the geographic coordinate system NZGD2000 (EPSG:4167) values need to be provided in lat/long (degrees based) and with a y/x order:
-36.764156 174.975230,-36.817467 175.023120
If you want to transform your dataset from the source coordinate system to another within the same WFS request as a spatial filter, you need to ensure your filter coordinate value is in the same unit and order as the source dataset according to the EPSG definition:
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50787&SRSName=EPSG:2193&cql_filter=bbox(shape,-36.764156,174.975230,-36.817467,175.023120)
Coordinate specification is also impacted by the WFS version you are using. The default version for LDS WFS queries is 2.0. In this WFS version, the coordinate order is sourced from the EPSG parameter database.
Read about setting the axis order in WFS 1.0
If you run the example above in WFS version 1.0, you will need to change the order of the coordinate values.
Translate coordinate values with our online coordinate conversion tool
Bbox spatial filter
The bbox (bounding box) parameter lets you search for features that are located (or partially located) inside a box of coordinates. Coordinates are provided in pairs of minimum and maximum values, each separated by a comma:
bbox=(shape,a1,b1,a2,b2)
This example will return from the NZ Geodetic Marks layer marks located at the western end of Waiheke Island. The coordinate values are provided in terms of the source CRS for the dataset (NZGD2000) and are ordered y/x as specified in the definition for EPSG:4167.
View the NZ Geodetic Marks layer
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50787&cql_filter=bbox(shape,-36.764156,174.975230,-36.817467,175.023120)
The OGC filter version of this request is:
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?VERSION=2.0.0&REQUEST=GetFeature&typeNames=layer-50787& 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:4167'> <gml:coordinates>-36.764156,174.975230 -36.817467,175.023120</gml:coordinates> </gml:Box> </BBOX> </And> </Filter>
Outputted in json format then loaded into CartoDB for visualisation purposes, this filter request provides the following records:
Advanced spatial filters
The ECQL spatial predicate operators allow you to perform more complex searches based on the relationship between geometry values. For these operations, coordinates must be provided in WKT format, where values are separated by a space and pairs are separated by a comma:
(a1 b1,a2 b2)
Intersects filter
This spatial filter will return records that intersect with a specified geometry. This can be useful for finding data, particularly polygon data, associated with a specific location.
This example will return from the NZ Property Titles Including Owners layer any records where the geometry intersects with a specific location in Auckland City – The Domain. (Note that access to this dataset requires acceptance of the LINZ Licence for Personal Data.)
View NZ Property Titles including Owners layer
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50805&SRSName=EPSG:2193&cql_filter=Intersects(shape,POINT(-36.8596 174.7757))
This next intersects example will return from the NZ Primary Parcels layer any records where the geometry intersects the specified line located in Greymouth.
View the NZ Primary Parcels layer
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetFeature&typeNames=layer-50772&cql_filter=Intersects(shape,LINESTRING(-42.45063 171.21188,-42.45859 171.20709))
Within filter
A 'within' spatial filter will return records within the described polygon. In this case the polygon is the Octagon in Dunedin City and the filter will select parcels from the NZ Primary Parcels layer that are within it.
View the NZ Primary Parcels layer
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetFeature&typeNames=layer-50772&cql_filter=Within(shape,POLYGON((-45.874136 170.501371,-45.872947 170.502041,-45.872544 170.503536,-45.872999 170.505233,-45.874136 170.505870,-45.875255 170.505187,-45.875723 170.503601,-45.875261 170.501969,-45.874136 170.501371)))&outputformat=csv
This request has been outputted in csv format then opened in QGIS to visualise the filtered results:
This spatial filter can be useful for finding all records within or partially within a defined area that is more complex than a simple box.
DWithin filter
The 'DWithin' (distance within) filter will return records that are located within a specific distance (radius) of a defined point, much like a buffer. As well as the point geometry, you must specify the value of distance from this point and unit of measure.
Note that in Geoserver, DWithin requests only work if the source data is in meters (such as LINZ topographic data). The units for the DWithin are:
- feet
- meters
- statute miles
- nautical miles
- kilometres.
This example will return features from the NZ Height Points (Topo50) layer that are within 10,000 meters of a defined point. Note that the coordinate values must be provided in the same y/x order as the EPSG definition for NZTM2000.
View the NZ Height Points (Topo50) layer
https://data.linz.govt.nz/services;key=YOUR_API_KEY/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=layer-50284&cql_filter=DWithin(GEOMETRY,POINT(5895346 1792630),10000,meters)
