Geospatial Filtering

Sapi-nt supports querying and filtering resources which are defined by a specific geographic location.

• Using Geospatial Filters
• Configuring a Geospatial Endpoint

Using Geospatial Filters

As an API user, to specify a geospatial area in which to filter resources, you must provide request parameters in your request.

To filter list query results by a geospatial area (on endpoints which support it), use the lat and long query parameters to define the latitude and longitude of a point on Earth, and the dist query parameter to define a maximum distance from that point, in kilometres. All of these parameters support double-precision decimal values.

Alternatively, to filter query results by a geospatial area within Great Britain, you can use easting and northing query parameters instead of lat and long. Eastings and Northings are the planar grid coordinates used by Ordnance Survey maps.

Sapi-nt determines the shape of the geospatial filter area based on the endpoint configuration.

• Circle Filter - Defines the filter area as a circle, centred on the specified point, with a radius of the specified distance.
• Box Filter - Defines the filter area as a square, centred on the specified point, with sides of two times the specified distance.

Using Polygon Filters with PostGIS

As an API user, when querying resources from a data source whose geospatial data is indexed with PostGIS, you can define a filter area as the interior area of a polygon, defined by a collection of geospatial points.

To filter list query results by a polygonal area, provide the within query parameter with a JSON-serialized representation of a GeoJSON geometry. Note that the JSON representation must be correctly URL-encoded in your request parameter.

Example

An example of a GeoJSON geometry:

{
  "type": "Polygon",
  "coordinates": [[[
    -2.647854754962907,
    51.466503943064566
  ], [
    -2.647854754962907,
    51.41458631598468
  ], [
    -2.5402702250107723,
    51.41458631598468
  ], [
    -2.5402702250107723,
    51.466503943064566
  ], [
    -2.647854754962907,
    51.466503943064566
  ]]]
}

Configuring a Geospatial Endpoint

As an API author, you can enable geospatial filtering for each endpoint by adding the relevant configuration to the endpoint spec.

To configure an endpoint with geospatial filtering support, set the geoFilters property on the endpoint spec. The value of geoFilters must be a list of filter shapes that the endpoint supports, including one or more of CircleFilter or BoxFilter. When Sapi-nt constructs geospatial filters for requests on an endpoint with multiple filter shapes, it uses the CircleFilter filter shape by default.

Note: Sapi-nt does not currently support dynamically setting the filter shape on each query.

Additionally, to enable geospatial filtering on related resources, set the geoParameter property on the endpoint spec. The value of geoParam must be the name of a resource-valued property on the root resource of the query. When you set this property, all geospatial filters on this endpoint will filter on the related resources, not the root resources.

Example

name      : list-geo-box
type      : list
url       : "geo/box-filter"
query     : "?id a def-sample:Measurement ."
geoParameter: "samplingPoint"
geoFilters:
  - BoxFilter

Configuring a PostGIS Integrated Data Source

As an API author, you can configure PostGIS integration for each data source by adding the relevant configuration to the data source spec.

To configure a data source with PostGIS integration, set the postgisSupported property o the data source spec. The value of postgisSupported is a mapping of filter shapes to PostGIS query names. The filter shapes must include one or more of CircleFilter, BoxFilter and PolygonFilter.

Example

name     : defaultDataSource
type     : dataSource.sparql.remote
endpoint : http://localhost:3030/ds/query
postgisSupported:
  "CircleFilter"  : "findWithin"
  "PolygonFilter" : "findGeoJson"