Filtering lists of resources - BAS API Documentation

Filtering by temporal extent

This pattern is based on the datetime parameter from the OGC API - Features - Part 1: Core specification.

Note: This pattern is deliberately limited in its support for ISO 8601 and represents minimum support APIs should implement. APIs MAY implement other parts of the ISO 8601 standard, such as durations (‘from [date] + 12 days’), or repeating intervals (‘every wednesday at 12:00 for 2 hours from [date]) but MUST NOT contravene this pattern.

When to use this pattern

list methods for resources with a single temporal extent, as either a datetime instant (such when something was captured or recorded) or a date period (such as a duration or validity)

Examples:

a job vacancy resource may have an ‘advertised for’ (validity) period
a cruise or cruise leg resource may have a duration period
a photograph resource may have a capture instant
an event or observation resource may have a ‘recorded at’ instant

When to not use this pattern

where resources have multiple temporal extents
where resources have temporal extents based on paleotime

Examples:

a grants or projects resource may have mutually exclusive fieldwork, reporting, funding and access durations

How to use this pattern

clients SHOULD URL encode values (e.g. /, : and + characters)
- for example, 2012-10-24T20:00:00+00:00 becomes 2012-10-24T20%3A00%3A00%2B00%3A00
- for example, 2012-10-24T20:00:00+00:00/2012-10-24T21:30:00+00:00 becomes 2012-10-24T20%3A00%3A00%2B00%3A00%2F2012-10-24T21%3A30%3A00%2B00%3A00

Where the datetime parameter value is an instant:

APIs MUST treat values as literal values (i.e. not implicitly convert them to an interval)

Where the datetime parameter value is an interval:

APIs MUST treat values as inclusive ranges, e.g. >= / <= as per ISO 8601:

A time interval comprises all instants between the two limiting instants and, unless otherwise stated, the limiting instants themselves.

APIs MUST treat .. as an open range

for example, 2012-10-24T20:00:00+00:00/.. MUST be interpreted as ‘from 2012-10-24T20:00:00+00:00 onwards’, and ../2012-10-24T20:00:00+00:00 MUST be interpreted as ‘until 2012-10-24T20:00:00+00:00’.

Examples

https://api.bas.ac.uk/example/v1/things?datetime=2012-10-24T20%3A00%3A00%2B00%3A00
- datetime instant: 2012-10-24T20:00:00+00:00
- would return all things with a value of exactly 2012-10-24T20:00:00+00:00
https://api.bas.ac.uk/example/v1/things?datetime=2012-10-24T20%3A00%3A00%2B00%3A00%2F2012-10-24T21%3A30%3A00%2B00%3A00
- datetime interval (closed on both sides)
- becomes 2012-10-24T20:00:00+00:00/2012-10-24T21:30:00+00:00 (from 2012-10-24T20:00:00+00:00 until 2012-10-24T21:30:00+00:00)
- would return all things between 2012-10-24T20:00:00+00:00 and 2012-10-24T21:30:00+00:00
https://api.bas.ac.uk/example/v1/things?datetime=2012-10-24T20%3A00%3A00%2B00%3A00%2F..
- datetime interval (open on right side)
- becomes 2012-10-24T20:00:00+00:00/..
- would return all things from 2012-10-24T20:00:00+00:00 onwards

Filtering by spatial extent

This pattern is based on the bbox parameter from the OGC API - Features - Part 1: Core specification.

This pattern can be used for both 2D (x,y) and 3D (x,y,z) spatial extents as needed.

It is assumed extents use the EPSG:4979 (Geographic 3D) (Spatial) Coordinate Reference System (SRS/CRS). Where this isn’t the case, an additional query parameter, bbox-crs, is required.

The bbox-crs parameter is taken from the OGC API - Features - Part 2: Coordinate Reference Systems by Reference standard, which is a draft and therefore subject to change. Use with caution.

The EPSG:4979 (Geographic 3D) CRS is effectively a superset of the EPSG:4326 (Geographic 2D) CRS, with the former also able to represent vertical extent.

When to use this pattern

list methods for resources with a single spatial extent, expressed as a bounding box in either 2 or 3 dimensions

Examples:

the area covered by a dataset (area, 2D)
the position of an aeroplane (point, 3D)

When to not use this pattern

where resources have multiple spatial extents

Examples:

the areas covered by multiple sample sites

How to use this pattern

clients SHOULD URL encode values (e.g. / and : characters)
- for example, 160.6,-55.95,-170,-25.89 becomes 160.6%2C-55.95%2C-170%2C-25.89
- for example, http://www.opengis.net/def/crs/EPSG/0/3031 becomes http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F3031

Examples

https://api.bas.ac.uk/example/v1/things?bbox=160.6%2C-55.95%2C-170%2C-25.89
- becomes 160.6,-55.95,-170,-25.89
- bounding box (2 Dimensional):
  - lower left corner, coordinate axis 1: 160.6
  - Lower left corner, coordinate axis 2: -55.95
  - upper right corner, coordinate axis 1: -170
  - upper right corner, coordinate axis 2: -25.89
- would return all things totally contained within the given bounding box
https://api.bas.ac.uk/example/v1/things?bbox=160.6%2C-55.95%2C0%2C-170%2C-25.89%2C100
- becomes 160.6,-55.95,0,-170,-25.89,100
- bounding box (3 Dimensional):
  - lower left corner, coordinate axis 1: 160.6
  - Lower left corner, coordinate axis 2: -55.95
  - Lower left corner, coordinate axis 3: 0
  - upper right corner, coordinate axis 1: -170
  - upper right corner, coordinate axis 2: -25.89
  - upper right corner, coordinate axis 3: 100
- would return all things totally contained within the given bounding box
https://api.bas.ac.uk/example/v1/things?bbox=160.6%2C-55.95%2C-170%2C-25.89&bbox-crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F3031
- becomes 160.6,-55.95,-170,-25.89 (in EPSG:3031 Antarctic Polar Stereographic))
- bounding box (2 Dimensional):
  - lower left corner, coordinate axis 1: 160.6
  - Lower left corner, coordinate axis 2: -55.95
  - upper right corner, coordinate axis 1: -170
  - upper right corner, coordinate axis 2: -25.89
- would return all things totally contained within the given bounding box in the given projection