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). 

Spatial operators

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:

  • 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, 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:

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>shape</PropertyName>
<Literal>
<Point srsName="http://www.opengis.net/gml/srs/epsg.xml#4167">
<gml:coordinates>-45.891523 170.467375</gml: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 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. 

Go to 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:

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

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:

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)

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.

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 for the request to run successfully.

Translate coordinate values with our online coordinate conversion tool

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:

bbox=(shape,a1,b1,a2,b2)

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.

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:

CartoDB example

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:

(a1 b1,a2 b2)

View ECQL spatial predicates

Intersects filter

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).

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))
Intersects line example

Within filter

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.

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)))&
o
utputformat=csv

This request has been outputted in csv format then opened in QGIS to visualise the filtered results:

Within filter example

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. 

DWithin filter

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.

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)
DWithin example
Reference Category: Web services
Reference Tags: WFS, Spatial filter, Geometry filter, BBOX, Axis order, Web feature services
Last Updated: 
24 August 2018