WFS

Nexus WFS API service returns details and (if available) vector geometries for any feature in a users' world.

GET /wfs/?world={world_alias}&request={request}&typenames={feature_type_alias}&token={web_api_token}

Parameters¶

Parameter	Mandatory	Meaning	Default value
`world`	Yes	Alias of world	-
`request`	Yes	Type of request: `getfeature`, `describefeaturetype` or `getcapabilities`	`getfeature`
`typenames`	Yes	Alias of requested feature type (for example `building` or `monitoring_station`; see Vector feature types)	-
`view`	No	Type of view: `feature`, `feature_event`, `feature_status`	`feature`
`count`	No	Number of features to return	`100000`
`startindex`	No	Starting point for counting features (normally combined with `count`)	`0`
`outputformat`	No	Output format in which results are returned (can be `json`, `csv` or `gml3`)	`gml3`
`sortby`	No	Sorting order of query results	-
`cql_filter`	For 'feature_event' view	Apply filtering on the features to return	-
`cql_filter_thresholds`	For 'feature_status' view	Select threshold to feature events for determining status	-
`featureid`	No	ID of feature to retrieve (only returns that one feature)	-
`propertyname`	No	Only include specified properties in response. Each property should be separated by a comma	-
`bbox`	No	Only return features within bounding box. Specify as `x_ll,y_ll,x_ur,y_ur,bbox_srid`	-
`srsname`	No	Transform features to a specific projection. Specify for example as `EPSG:4326`
`geometryname`	No	Geometry property to return, in case feature has multiple geometry properties. By default (`auto`), most detailed available geometry is returned (in order of availability: `polygon_3d`, `polygon`, `centerline`, `centroid`).	`auto`
`chartid`	No	Return additional `chart` property with URL pointing to interactive chart for each feature	-
`chart_range`	No	When `chartid` is provided, choose a specific interval. Options: `auto`, `P1D`, `P1W`, `P1M`, `P1Y`, `P5Y`, `P10Y`, or a custom range, such as `-P3D/+P10D`	`auto`
`event_valid_during`	No	Set the value of any events outside a validity time range to `null`. Useful for showing locations with their most recent events, while 'greying out' locations whose measurements are too old	-
`event_sortby`	No	Sort property and order for events. Options: `timestamp d`, `timestamp a`, `value d`, `value a`	`timestamp d`
`event_limit`	No	Number of events per feature to return (for `feature_event` view)	`1`
`distinct_on`	No	Properties to use for a 'distinct on' filtering on selected features	-
`simplify`	No	Simplify geometries for faster rendering by reducing their accuracy to approximately 0.5m	`false`
`flatten`	No	Flatten properties that are within a nested JSON object	`false`

Example

Request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=weather_station&outputformat=csv&count=3&token={web_api_token}"

Response:

id,dc_id,id_src,label,details,centroid
22,18,209,IJmond,,POINT(95931.09343 497826.9672)
23,18,210,Valkenburg Zh,,POINT(89519.11346 465192.84233)
24,18,215,Voorschoten,,POINT(89954.24818 461848.93659)

Note

Some features in the database use curved geometry types - such as CurvePolygon or CircularString, which are not natively supported by GeoJSON. During API requests, Nexus automatically converts these geometries into equivalent linear polygon representations.

Data chunking¶

Be aware that data volumes in Nexus can be huge. If you request all features of a certain type all at once, it may result in a multi-GB output size. A core concept when you are working with the WFS API is therefore to iterate over the content to gather everything that you are interested in.

This means that when you access data, you will retrieve it in parts. With the count parameter, you tell the API how much data you want to see at once. Together with the offset you can tell the API from where it should start counting in order to get the next chunk of data.

Example

Request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=weather_station&outputformat=csv&count=2&offset=1&token={web_api_token}"

Response:

id,dc_id,id_src,label,details,centroid
22,18,209,IJmond,,POINT(95931.09343 497826.9672)
23,18,210,Valkenburg Zh,,POINT(89519.11346 465192.84233)

Filtering¶

With the cql_filter (Common Query Language) parameter, you can filter the results of your request to only include features that satisfy certain criteria. The filter is much like an SQL where-clause and can contain all common expressions such as and, or, >, = etcetera.

Note

Specifically with this parameter, encoding the value is very important. Check the API Basics to learn more about this.

Comparisons¶

The CQL-filter supports standard comparisons, such as: >, =, <>, >=, < and <=. Such comparisons can be done for numeric, date, datetime, boolean and text properties.

Comparison	Meaning
`>`	Greater than
`=`	Equal to
`<>`	Not equal to
`>=`	Greater than or equal to
`<`	Less than
`<=`	Less than or equal to

Example

CQL filter to get buildings constructed in or after 2020:

construction_year >= 2020

Encoded request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=building&cql_filter=construction_year+%3E%3D+2020&count=10&token={web_api_token}"

Specifically for text data, also the like operator can be used. To select data whose values are within a set of allowed values, use the in operator.

Example

CQL filter to get all buildings that are currently under construction or that just finished construction:

status in ('under_construction','construction_finished')

Encoded request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=building&cql_filter=status+in+%28%27under_construction%27%2C%27construction_finished%27%29&count=10&token={web_api_token}"

Example

CQL filter to get all buildings that have 'construction' in their status:

status like '%construction%'

Encoded request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=building&cql_filter=status+like+%27%25construction%25%27&count=10&token={web_api_token}"

Combining comparisons¶

Like SQL, it is possible to combine filters, by using and or or.

Example

CQL filter to get buildings higher than 15 meters and constructed in 2022:

height > 15 and construction_year = 2022

Encoded request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=building&cql_filter=height+%3E+15+and+construction_year+%3D+2022&count=100&token={web_api_token}"

Temporal filtering¶

The 'feature_event' and 'feature_status' views require a temporal filter, as to select only timeseries events in a limited window. This temporal filter is specified as a during <start>/<end> predicate. This predicate specifies a range with a start and end, which in itself may be defined as a static set of dates, timestamps, or relative offsets. Time range must be specified according to ISO 8601 standard. Note that the start and end should not be quoted. An ISO 8601 period string prefixed with a '+' or '-' indicates an offset relative from now, whereas an ISO 8601 period string without prefix indicates a relative offset from either the start or end of the range.

Example

Examples of valid durations (unencoded):

- event_timestamp during -P3D/+P1D (from 3 days ago until 1 day ahead)
- event_timestamp during -P5M/P2M (from 5 months ago until 3 months ago)
- event_timestamp during 2020-01-03T13:00/P3D (from January 3rd, 2020 until January 6th, 2020)
- timestamp during 2020-01-03/2020-02-05 (static dates)

Spatial filtering¶

Bounding box filtering¶

Using the bbox parameter, one can limit the features to only those inside a bounding box.

Example

Get all soil bodies at a certain location

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=soil_body&bbox=100000,400000,135000,455000,28992&token={web_api_token}"

Distance filtering¶

The dwithin function in the cql_filter parameter allows you to find features within a specified distance from a given geometry. This is useful for proximity searches such as finding all buildings within 500 meters of a point.

The syntax for the dwithin function is:

dwithin(geometryproperty, wkt_geometry, distance, units)

Argument	Description
`geometryproperty`	The geometry property to search. Valid options: `centerline`, `centroid`, `centroid_3d`, `footprint`, `outline`, `polygon`, `polygon_3d`
`wkt_geometry`	A WKT (Well-Known Text) geometry. Format: `TYPE(coordinates)`. Valid types: `POINT`, `LINESTRING`, `POLYGON`, `MULTIPOINT`, `MULTILINESTRING`, `MULTIPOLYGON`
`distance`	A numeric value representing the search radius (must be greater than zero)
`units`	Distance units. Valid options: `meters` or `kilometers`

Note

When using kilometers, the distance is automatically converted to meters internally
Argument wkt_geometry is expected to be in the spatial reference system of the world, unless srsname is specified (in which it is assumed to be in that spatial reference system).
dwithin can be combined with other CQL filters expressions using and or or operators

Example

Find all buildings within 500 meters of a specific point:

dwithin(centroid, POINT(100000 450000), 500, meters)

Encoded request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=building&cql_filter=dwithin(centroid%2C+POINT(100000+450000)%2C+500%2C+meters)&token={web_api_token}"

Example

Using dwithin with coordinate transformation via srsname parameter.

If your world uses EPSG:28992 (Dutch RD) as its native CRS, but you want to search 1.5 meter around location SRID=4326;POINT(3.313766 47.974914) and have the resulting geometries also in EPSG:4326, then:

dwithin(centroid, POINT(3.313766 47.974914), 1.5, meters)

Encoded request with srsname=EPSG:4326:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=building&srsname=EPSG%3A4326&cql_filter=dwithin(centroid%2C+POINT(3.313766+47.974914)%2C+1.5%2C+meters)&token={web_api_token}"

Example

Similarly, if your world uses EPSG:4326 as its native CRS, but you want to search 1.5 meter around location SRID=28992;POINT(100000 450000) and have the resulting geometries also in EPSG:28992, then:

dwithin(centroid, POINT(100000 450000), 1.5, meters)

Encoded request with srsname=EPSG:28992:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=building&srsname=EPSG%3A28992&cql_filter=dwithin(centroid%2C+POINT(100000+450000)%2C+1.5%2C+meters)&token={web_api_token}"

Relationships¶

Data in Nexus is often interrelated. For example, large multi-storey buildings often contain several apartments and shops. In technical speak: the feature type building is related to the type building_unit (building unit covers both apartments and shops). Another example: a monitoring station can consist of multiple individual groundwater monitoring tubes. In turn a groundwater monitoring tube is likely to be resulting in a timeseries of groundwater head observations. Nexus WFS API represents such relationships using primary keys. This allows one to follow such relationships through subsequent API requests. For more background on this, check the Nexus data model

Example

Get all weather stations, then retrieve the timeseries for a particular weather station and finally get the actual events of one particular timeseries.

First, request a list of weather stations:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=weather_station&outputformat=csv&count=5&token={web_api_token}"

Response:

id,dc_id,id_src,label,details,centroid
22,18,209,IJmond,,POINT(95931.09343 497826.9672)
23,18,210,Valkenburg Zh,,POINT(89519.11346 465192.84233)
24,18,215,Voorschoten,,POINT(89954.24818 461848.93659)
25,18,225,IJmuiden,,POINT(98442.88141 497574.90525)
26,18,240,Schiphol,,POINT(114280.34596 481284.20714)

Next, request all timeseries for weather station De Bilt:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=timeseries&cql_filter=feature_id=3+and+feature_type='weather_station'&outputformat=csv&token={web_api_token}"

Response:

id,dc_id,id_src,feature_id,parameter,feature_type
21,6,,3,etref_mm_d,weather_station
22,6,,3,prec_mm_d,weather_station
23,6,,3,rad_in_s_j_cm2_d,weather_station
26,6,,3,hum_rel_pct,weather_station
37,6,,3,wind_speed_max_hour_mean_m_s,weather_station
38,6,,3,wind_speed_max_m_s,weather_station
39,6,,3,wind_speed_mean_m_s,weather_station
40,6,,3,wind_direction_deg,weather_station
20,6,,3,airtemp_mean_deg_c,weather_station
19,6,,3,airtemp_max_deg_c,weather_station

Finally, request the actual daily average temperature measurements for January 2021 (timeseries_id 20) using the Events API.

Sorting¶

Normally, results are returned in random order. This yields the fastest response, but may sometimes be undesirable. Results can therefore be sorted explicitly in ascending or descending order using the sortby parameter. Add an a to the property name to order in ascending order and a d to apply descending ordering.

Note

Specifically with this parameter, encoding the value is very important. Check the API Basics to learn more about this.

Example

Get a list of facilities sorted by their name (label) in descending (d) order:

sortby=label d

Encoded request

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&typenames=facility&outputformat=csv&sortby=label+d&count=5&token={web_api_token}"

Response:

dc_id,id_src,id,label,start_date,category,maingroup,daily_customer_capacity,website,details,building_unit_id,building_id,centroid
261,100825908,2240,,,fire_station,,,,,,,POINT(134024.4825 464652.0945)
261,100805509,2455,,,fire_station,,,,,,,POINT(113177.781 462554.80001)
261,100792503,2039,,,fire_station,,,,,,,POINT(115072.26565 450902.94987)
261,100796050,2040,,,fire_station,,,,,,,POINT(117678.8825 458173.929)
261,100830643,2241,,,fire_station,,,,,,,POINT(139784.20112 463282.75178)

Consolidating data in a single view¶

By default, data from a single feature type is returned in a WFS request (feature view). However, by using the feature_event view it is possible to add to each feature an event or set of events. For example, for showing the current temperature on a map, one could request all weather stations (feature) and have added to each station the most recent temperature measurement (event). If a particular feature has in addition to measurements also a set of thresholds, one may also use the feature_status view by returning for that feature not only an event, but also the status of that event.

Feature events¶

The feature_event view returns features, each one combined with an event or set of events. When using this view, it is mandatory to specify a CQL filter (parameter cql_filter) that includes at least:

an equality-comparison for selecting a specific timeseries parameter (timeseries_parameter = ...), and
a temporal filter for selecting the range (event_timestamp during .../...)

In addition to the regular feature properties, the CQL filter may for this view also include additional timeseries properties, such as timeseries_id, timeseries_dc_id, timeseries_maingroup and timeseries_subgroup.

Optionally, for this view, the event_limit and event_order parameters may be specified to select the number of events per feature and the sorting order of the events per feature. Finally, also event_valid_during can be used as parameter for this view to set the value of events outside a validity window to null. This allows all features with a certain type of timeseries events to be shown on a map while hiding the measured value of outdated measurements.

Example

CQL filter to get for each weather station the most recent temperature, no older than 3 days:

timeseries_parameter = 'airtemp_mean_deg_c' and event_timestamp during -P3D/+P0D

Encoded request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&view=feature_event&typenames=weather_station&cql_filter=timeseries_parameter+%3D+%27airtemp_mean_deg_c%27+and+event_timestamp+during+-P3D%2F%2BP0D&count=100&token={web_api_token}"

Example

Encoded request for showing each weather station having a temperature measurement no older than one year. Hide the value of measurements that are older than 3 days:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&view=feature_event&typenames=weather_station&cql_filter=timeseries_parameter+%3D+%27airtemp_mean_deg_c%27+and+event_timestamp+during+-P1Y%2F%2BP0D&event_valid_during=-P3D%2F%2BP0D&count=100&token={web_api_token}"

Feature status¶

The feature_status view returns a list of features, each feature combined with an event (same as feature_event) and the status of that event. A status is determined by comparing the selected event of a feature with a set of thresholds, each threshold being a timeseries with events on its own (since thresholds may be subject to change over time). Both timeseries events and thresholds should have the same timeseries parameter. Nexus considers a threshold to mark the right side of each status/class bin, meaning that an event will adopt the status of the smallest of all selected thresholds that it does not exceed.

Note

For each feature event the most recent threshold is selected from before or at the events' timestamp. Status determination does not depend on how recent the threshold is, neither on the event search window as specified in the cql_filter. If no threshold can be found for a certain feature event, the status is returned as null.

A feature_status view has the same CQL filter requirements as for feature events, but requires in addition cql_filter_thresholds to be specified. Typically cql_filter_thresholds is only used to select dataconnections, maingroups or subgroups to be used as thresholds for status determination (properties threshold_dc_id, threshold_maingroup, threshold_subgroup). Filtering thresholds on timeseries_parameter is not permitted, as the thresholds have the same parameter as the events to which they are applied (and the parameter is already defined in the cql_filter).

Example

Let's determine the current status for a weather station having a timeseries with observation of parameter airtemp_mean_deg_c by applying a set of thresholds, differentiated by their maingroup: High, Medium and Low.

CQL filter:

timeseries_parameter = 'airtemp_mean_deg_c' and event_timestamp during -P3D/+P0D

CQL filter thresholds:

maingroup in ('High','Medium','Low')

Encoded request:

curl "https://nexus.stellaspark.com/api/v1/wfs/?world=sandbox&request=getfeature&view=feature_status&typenames=weather_station&cql_filter=timeseries_parameter+%3D+%27airtemp_mean_deg_c%27+and+event_timestamp+during+-P3D%2F%2BP0D&cql_filter_thresholds=maingroup+in+%28%27High%27%2C%27Medium%27%2C%27Low%27%29&count=100&token={web_api_token}"