Using request parameters to limit query results • EMODnetWFS

Requesting a full layer with emodnet_get_layers() will return the geometries for all features in that layer, potentially a large amount of data.

Some basic ability to limit the output of any query is possible by providing additional parameters to the feature request query. This can be achieved by passing additional arguments to emodnet_get_layers(...).

For details on all available parameters consult the GetFeature Geoserver documentation. Also note that there are differences in available parameters between different version of WFS specifications. We recommend and mainly document using the default and latest version ("2.0.0") which is supported by all EMODnet WFS services.

Initialise a WFS client

Let’s start by loading EMODnetWFS and initialising a WFS client to the human_activities WFS service.

library(EMODnetWFS)

wfs <- emodnet_init_wfs_client("human_activities")
#> Loading ISO 19139 XML schemas...
#> Loading ISO 19115 codelists...
#> Google's s2 geometry is not OGC compliant!
#> Spherical geometry (s2) switched off
#> ✔ WFS client created successfully
#> ℹ Service: "https://ows.emodnet-humanactivities.eu/wfs"
#> ℹ Version: "2.0.0"

Return single feature using feature ID

We can restrict the query to a single feature using featureID and providing the ID of a specific feature.

emodnet_get_layers(
  wfs = wfs,
  layers = "maritimebnds",
  featureID = "maritimebnds.861",
  reduce_layers = TRUE
)
#> Simple feature collection with 1 feature and 12 fields
#> Geometry type: MULTICURVE
#> Dimension:     XY
#> Bounding box:  xmin: -80.03719 ymin: 18.05616 xmax: -78.72694 ymax: 19.35781
#> Geodetic CRS:  WGS 84
#>             gml_id objectid mblszotpid localid                         sitename
#> 1 maritimebnds.861      861          3    3494 Delimitation line between states
#>   legalfound legalfou_1                 country nationalle nutscode
#> 1 1932-01-30       <NA> United Kingdom, Jamaica       <NA>   UK, JM
#>                                   mblsds_mbl shape_leng
#> 1 In www.marineregions.org. VLIZ Median Line   1.847992
#>                         the_geom
#> 1 MULTICURVE (LINESTRING (-78...

Return specific number of features

If the ID of the feature is unknown but we still want to limit the number of features returned, we use the count parameter for WFS 2.0.0 or the maxFeatures parameter for earlier WFS versions to restrict the number of features returned. In this example we restrict the query to the first feature.

emodnet_get_layers(
  wfs = wfs,
  layers = "maritimebnds",
  count = 1L,
  reduce_layers = TRUE
)
#> Simple feature collection with 1 feature and 12 fields
#> Geometry type: MULTICURVE
#> Dimension:     XY
#> Bounding box:  xmin: 6.6236 ymin: 52.87112 xmax: 14.04677 ymax: 55.0804
#> Geodetic CRS:  WGS 84
#>           gml_id objectid mblszotpid localid        sitename legalfound
#> 1 maritimebnds.1        1          7   49469 Internal waters       <NA>
#>   legalfou_1 country nationalle nutscode               mblsds_mbl shape_leng
#> 1       <NA> Germany       <NA>       DE In www.marineregions.org    54.8404
#>                         the_geom
#> 1 MULTICURVE (LINESTRING (11....

Order features

Exactly which features will be returned depends in the internal structure of the data. However, we can sort the returned selection based on an attribute value using the sortBy parameter.

Say we wanted to return 5 of the earliest maritime boundaries. In the following example, we sort by the "legalfound" attribute (which contains the date the boundary was legally founded) and combine it with the count parameter to restrict the number of features returned. This returns the first 5 features after the data has been ordered by "legalfound".

emodnet_get_layers(
  wfs = wfs,
  layers = "maritimebnds",
  sortBy = "legalfound",
  count = 5L,
  reduce_layers = TRUE
)
#> Simple feature collection with 5 features and 12 fields
#> Geometry type: MULTICURVE
#> Dimension:     XY
#> Bounding box:  xmin: -80.03719 ymin: 18.05616 xmax: 21.53884 ymax: 56.21403
#> Geodetic CRS:  WGS 84
#>             gml_id objectid mblszotpid localid                         sitename
#> 1 maritimebnds.859      859          3    3488 Delimitation line between states
#> 2 maritimebnds.860      860          3    3489 Delimitation line between states
#> 3 maritimebnds.738      738          4    2026                Continental Shelf
#> 4 maritimebnds.858      858          4    2027                Continental Shelf
#> 5 maritimebnds.861      861          3    3494 Delimitation line between states
#>   legalfound legalfou_1                 country nationalle nutscode
#> 1 1932-01-30       <NA>       Lithuania, Russia       <NA>   LT, RU
#> 2 1932-01-30       <NA>         Portugal, Spain       <NA>   PT, ES
#> 3 1932-01-30  61562.pdf         Sweden, Denmark  Bilateral   SE, DK
#> 4 1932-01-30  61562.pdf         Sweden, Denmark  Bilateral   SE, DK
#> 5 1932-01-30       <NA> United Kingdom, Jamaica       <NA>   UK, JM
#>                                                   mblsds_mbl shape_leng
#> 1                 In www.marineregions.org. VLIZ Median Line  0.6811054
#> 2                 In www.marineregions.org. VLIZ Median Line  1.8957056
#> 3 Territorial sea boundary agreement with Swedenin the Sound  0.4718419
#> 4 Territorial sea boundary agreement with Swedenin the Sound  0.8901870
#> 5                 In www.marineregions.org. VLIZ Median Line  1.8479924
#>                         the_geom
#> 1 MULTICURVE (LINESTRING (21....
#> 2 MULTICURVE (LINESTRING (-7....
#> 3 MULTICURVE (LINESTRING (12....
#> 4 MULTICURVE (LINESTRING (12....
#> 5 MULTICURVE (LINESTRING (-78...

The default sort operation is to sort in ascending order. Some WFS servers require the sort order to be specified. In this case, append a +A to the attribute character string passed to sortBy. Conversely, add a +D to sort in descending order.

Return blocks of features from specific starting point

Finally in WFS version 2.0.0 (and also available in earlier versions on GeoServer) a startIndex parameter was introduced, allowing users to specify the starting index of features to be returned.

#> [1] 1047

For example, the full "maritimebnds" layer contains 1047 features.

n_features <- layer_attributes_tbl(wfs = wfs, layer = "maritimebnds") %>% nrow()

n_features

Setting the startIndex to n_features - 4 (1043) returns the last 4 features.

startIndex <- n_features - 4L
startIndex
#> [1] 1043

emodnet_get_layers(
  wfs = wfs,
  layers = "maritimebnds",
  startIndex = startIndex,
  reduce_layers = TRUE
)
#> Simple feature collection with 4 features and 12 fields
#> Geometry type: MULTICURVE
#> Dimension:     XY
#> Bounding box:  xmin: -13.85305 ymin: 35.66859 xmax: 10.21833 ymax: 51.55778
#> Geodetic CRS:  WGS 84
#>              gml_id objectid mblszotpid localid
#> 1 maritimebnds.1044     1044          2       0
#> 2 maritimebnds.1045     1045          2       0
#> 3 maritimebnds.1046     1046          1   49033
#> 4 maritimebnds.1047     1047          1   49018
#>                               sitename legalfound          legalfou_1 country
#> 1 Exclusive Economic Zone (200 nm) EEZ 1997-07-31 ESP_1997_Decree.pdf   Spain
#> 2 Exclusive Economic Zone (200 nm) EEZ 1976-07-15    FRA_1976_Law.pdf  France
#> 3                Territory sea (12 nm)       <NA>                <NA>   Spain
#> 4                Territory sea (12 nm)       <NA>                <NA>  France
#>   nationalle nutscode
#> 1 Unilateral       ES
#> 2 Unilateral       FR
#> 3       <NA>       ES
#> 4       <NA>       FR
#>                                                                                                    mblsds_mbl
#> 1 Royal Decree 1315/1997, of 1 August 1997, establishing a Fisheries Protection Zone in the Mediterranean Sea
#> 2                                                                                               FRA EEZ 200nm
#> 3                                                                                    In www.marineregions.org
#> 4                                                                                    In www.marineregions.org
#>   shape_leng                       the_geom
#> 1  110.91163 MULTICURVE (LINESTRING (4.5...
#> 2  130.14609 MULTICURVE (LINESTRING (4.6...
#> 3   74.06973 MULTICURVE (LINESTRING (-2....
#> 4   65.51497 MULTICURVE (LINESTRING (9.6...

We can also combine startIndex and count to return specific blocks of features. For example, in the following query we request features 5-9 by supplying a startIndex of 4 and count of 5.

Note that startIndex uses 0 as a starting index (0 indicates the first feature), hence we set it to 4 in order to start at the 5th feature.

emodnet_get_layers(
  wfs = wfs,
  layers = "maritimebnds",
  startIndex = 4L,
  count = 6L,
  reduce_layers = TRUE
)
#> Simple feature collection with 6 features and 12 fields
#> Geometry type: MULTICURVE
#> Dimension:     XY
#> Bounding box:  xmin: -10.68333 ymin: 36.6425 xmax: 28.20899 ymax: 66.77516
#> Geodetic CRS:  WGS 84
#>            gml_id objectid mblszotpid localid        sitename legalfound
#> 1  maritimebnds.5        5          7   49474 Internal waters       <NA>
#> 2  maritimebnds.6        6          7   49475 Internal waters       <NA>
#> 3  maritimebnds.7        7          7   49476 Internal waters       <NA>
#> 4  maritimebnds.8        8          7   49478 Internal waters       <NA>
#> 5  maritimebnds.9        9          7   49479 Internal waters       <NA>
#> 6 maritimebnds.10       10          7   49480 Internal waters       <NA>
#>   legalfou_1 country nationalle nutscode               mblsds_mbl shape_leng
#> 1       <NA> Estonia       <NA>       EE In www.marineregions.org   44.50010
#> 2       <NA> Finland       <NA>       FI In www.marineregions.org  398.75400
#> 3       <NA>  France       <NA>       FR In www.marineregions.org   86.63315
#> 4       <NA> Ireland       <NA>       IE In www.marineregions.org   86.83152
#> 5       <NA>   Italy       <NA>       IT In www.marineregions.org  107.88191
#> 6       <NA>  Latvia       <NA>       LV In www.marineregions.org   15.63377
#>                         the_geom
#> 1 MULTICURVE (LINESTRING (22....
#> 2 MULTICURVE (LINESTRING (27....
#> 3 MULTICURVE (LINESTRING (9.4...
#> 4 MULTICURVE (LINESTRING (-7....
#> 5 MULTICURVE (LINESTRING (14....
#> 6 MULTICURVE (LINESTRING (24....

This in combination with, for example, a for loop, can be used to download and process large layer which might not be able to be handled in R in smaller, more manageable blocks of features.

Return data for specific attributes

Finally, we can specify specific attributes for which we want data returned using parameter propertyName.

To limit data returned to the single attribute "country" from just 3 features, we use parameters propertyName = "country" and count = 3.

Note that when limiting data to specific attributes, all other columns are returned as NA (including any spatial, in this case the_geom, column).


emodnet_get_layers(
  wfs = wfs,
  layers = "maritimebnds",
  propertyName = "country",
  count = 3L,
  reduce_layers = TRUE
)
#> Simple feature collection with 3 features and 12 fields (with 3 geometries empty)
#> Geometry type: GEOMETRYCOLLECTION
#> Dimension:     XY
#> Bounding box:  xmin: NA ymin: NA xmax: NA ymax: NA
#> Geodetic CRS:  WGS 84
#>           gml_id objectid mblszotpid localid sitename legalfound legalfou_1
#> 1 maritimebnds.1       NA         NA      NA     <NA>       <NA>       <NA>
#> 2 maritimebnds.2       NA         NA      NA     <NA>       <NA>       <NA>
#> 3 maritimebnds.3       NA         NA      NA     <NA>       <NA>       <NA>
#>    country nationalle nutscode mblsds_mbl shape_leng                 the_geom
#> 1  Germany       <NA>     <NA>       <NA>         NA GEOMETRYCOLLECTION EMPTY
#> 2 Bulgaria       <NA>     <NA>       <NA>         NA GEOMETRYCOLLECTION EMPTY
#> 3  Croatia       <NA>     <NA>       <NA>         NA GEOMETRYCOLLECTION EMPTY

To limit to multiple attributes, separate each attribute name in the character string supplied to propertyName by a comma.


emodnet_get_layers(
  wfs = wfs,
  layers = "maritimebnds",
  propertyName = "country,the_geom",
  count = 3L,
  reduce_layers = TRUE
)
#> Simple feature collection with 3 features and 12 fields
#> Geometry type: MULTICURVE
#> Dimension:     XY
#> Bounding box:  xmin: 6.6236 ymin: 42.16325 xmax: 28.4656 ymax: 55.0804
#> Geodetic CRS:  WGS 84
#>           gml_id objectid mblszotpid localid sitename legalfound legalfou_1
#> 1 maritimebnds.1       NA         NA      NA     <NA>       <NA>       <NA>
#> 2 maritimebnds.2       NA         NA      NA     <NA>       <NA>       <NA>
#> 3 maritimebnds.3       NA         NA      NA     <NA>       <NA>       <NA>
#>    country nationalle nutscode mblsds_mbl shape_leng
#> 1  Germany       <NA>     <NA>       <NA>         NA
#> 2 Bulgaria       <NA>     <NA>       <NA>         NA
#> 3  Croatia       <NA>     <NA>       <NA>         NA
#>                         the_geom
#> 1 MULTICURVE (LINESTRING (11....
#> 2 MULTICURVE (LINESTRING (28....
#> 3 MULTICURVE (LINESTRING (14....

Limit spatial extent using a boundary box

The bbox parameter allows us to search for features that are contained (or partially contained) inside a box of user-defined coordinates. The format of the bbox parameter in most EMODnet WFS cases (assuming you are using version 2.0.0) is bbox=a1,b1,a2,b2,[crs] where a1, b1, a2, and b2 represent the coordinate values. The optional crs parameter is used to name the CRS for the bbox coordinates (if they are different to the featureTypes native CRS.) The order of coordinates passed to the bbox parameter depends on the coordinate system used (this is why the coordinate syntax isn’t represented with x or y).

In the following example, we specify the bounding box by proving coordinates in the order xmin,ymin,xmax,ymax and specifying that coordinates are given in the EPSG:4326 coordinate reference system.

bbox_response <- emodnet_get_layers(
  service = "biology",
  layers = "mediseh_posidonia_nodata",
  bbox = "22.9,34.4,26.8,35.8,EPSG:4326",
  reduce_layers = TRUE
)
#> ✔ WFS client created successfully
#> ℹ Service: "https://geo.vliz.be/geoserver/Emodnetbio/wfs"
#> ℹ Version: "2.0.0"

bbox_response %>%
  sf::st_cast(to = "MULTILINESTRING") %>%
  mapview::mapview(burst = TRUE, legend = FALSE)

Non-standard Vendor Parameters

WFS vendor parameters are additonal, non-standard request parameters defined by an implementation to provide enhanced capabilities.

The majority of EMODnet services are GeoServer WFS implementations which support a variety of vendor-specific WFS parameters.

One of these are cql_filters. These are handled explicitly through the EMODnetWFS package through the cql_filter argument in emodnet_get_layers() and are documented in detail in article("ecql_filtering").

For additional vendor parameters available through GeoServer implementations please refer to the WFS vendor parameters documentatio

Exceptions are the Chemistry (Eutrophication by sea region, Eutrophication) services which uses Python and Chemistry (Litter) which uses MapServer so vendor parameters for these services might differ.