Web Feature Services (WFS) advanced operations allow you filter your query based on geometry. This is particularly useful when you are only interested in data related to a specific location.
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).
There are many operators you can use to spatially filter data including Bbox (bounding box) and a range operators allow you to search for data based on the relationship between geometry values:
When performing spatial operations you need to specify the geometry column and the geometry type, in addition to 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'. As described in our documentation for filtering by attribute or feature, 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.
These code snippets show the format to use to specify the spatial parameters using the CQL and OGC methods:
- 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
See the Intersects example below to see this spatial operator in action.
Coordinate format and order
To effectively use spatial filters, you also need to ensure the coordinate value of your filter aligns with the unit of the source dataset and that the coordinates are specified in the same order in which they are defined in the EPSG parameter database.
If you are querying a 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:
For the geographic coordinate system NZGD2000 (EPSG:4167) values need to be provided in lat/long (degrees based) and with a y/x order:
Similarly, if you want to transform your dataset from the source coordinate system to another within the same WFS request as a spatial filter, you will need to ensure your filter coordinate value is in the same unit and order as the source dataset as per the EPSG definition:
However, 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.
If you run the example above in WFS version 1.0, you will need to change the order of the coordinate values for the request to run successfully.
Bbox spatial filter
The Bbox (or bounding box) parameter allows you to 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:
As a commonly used spatial filter, we have provided examples of this Bbox filter example in both CQL and OGC format.
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.
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">
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 separates by a comma:
This spatial filter will return records that intersect with a specified geometry. This can be very useful for finding data, particularly polygon data, associated with a specific location.
This Intersects 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: Access to this dataset requires your acceptance of the LINZ Licence for Personal Data).
This next Intersects example will return from the NZ Primary Parcels layer any records where the geometry intersects the specified line located in Greymouth.
cql_filter=Intersects(shape,LINESTRING(-42.45063 171.21188,-42.45859 171.20709))
A Within spatial filter will return records that are located 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.
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)))&
This request has been outputted in csv format then opened in QGIS to visualise the filtered results:
This spatial filter can be really useful for finding all records within or partially within a defined area that is more complex than a simple box.
The DWithin or Distance Within filter will return records that are located within a specific distance (radius) from 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: Geoserver has a limitation where DWithin requests only work where the source data is in meters, e.g. LINZ Topographic data. The units for DWithin is one of 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: the coordinate values must be provided in the same y/x order as per the EPSG definition for NZTM2000.