Navigation :

Executing Functions

Functions can be executed to provide sets of features or data.

Execute a function

The path /functions/{funid}/items is the basic query to execute a function and return the set of features or data it produces.

The response from a spatial function is a GeoJSON feature collection containing the result. The response from a non-spatial function is a JSON dataset containing the result.

These are similar to using SQL statement clauses to control the results of a query. In fact, the service implements these parameters by generating the equivalent SQL. However, these filters are applied to the results of an executed function, so it doesn’t necessarily allow optimizing the execution of the function. (For example, specifying a bounding box only filters the results generated by the function; it is not available to the function to reduce the number of records generated.)

Function arguments

Functions provide query parameters of the form param=arg-value to provide an argument value for each function parameter. Omitted parameters use the default specified in the function definition (if any). If a function parameter does not provide a default then a value must be supplied.

Example

http://localhost:9000/functions/countries_name/items?name_prefix=T

Filter by bounding box

The query parameter bbox=MINX,MINY,MAXX,MAXY is used to limit the features returned to those that intersect a specified bounding box. The bounding box is specified in geographic coordinates (longitude/latitude, SRID = 4326). If the source data has a non-geographic coordinate system the bounding box is transformed to the source coordinate system to perform the query.

A bounding box in a different coordinate system may be specified by adding the bbox-crs=SRID query parameter.

This parameter is only useful for spatial functions.

Example

http://localhost:9000/functions/countries_name/items?bbox=10.4,43.3,26.4,47.7

Filter by CQL expression

The response feature set can be filtered to include only features which satisfy a logical expression written in the Common Query Languae (CQL). See the CQL section for more details.

Example

http://localhost:9000/functions/countries_name/items?name_prefix=C&filter=continent='Europe' AND pop_est<2000000

Filter geometry coordinate system

By default the coordinate system of geometry literals in the filter expressionis is assumed to be 4326 (geodetic). A different coordinate system can be specified by using the query parameter filter-crs=SRID.

Example

http://localhost:9000/functions/countries_name/items.json?filter=DWITHIN(geom,POINT(1209000+477000),1000)&filter-crs=3005

Response properties

The query parameter properties=PROP1,PROP2,PROP3... specifies the properties returned in the response. This reduces the response size of functions that produce a large number of records. If the parameter is specified with an empty list, no feature properties are returned.

Example

http://localhost:9000/functions/countries_name/items?properties=name

Response coordinate system

The query parameter crs=SRID specifies the coordinate system to be used for the feature geometry in the response. The SRID must be a coordinate system which is defined in the PostGIS instance. By default data is returned in WGS84 (SRID=4326) geodetic coordinate system.

GeoJSON technically does not support coordinate systems other than 4326, but the OGC API standard allows non-geodetic data to be encoded in GeoJSON. However, this data may not be compatible with other systems.

This parameter is only useful for spatial functions.

Example

http://localhost:9000/functions/bc_rivers_by_name/items?name=Fraser&crs=3005

Limiting and paging

The query parameter limit=N can controls the maximum number of data items returned in a response.

The query parameter offset=N specifies the offset in the actual query result at which the response data set starts.

When used together, these two parameters allow paging through large result sets.

Example

http://localhost:9000/functions/countries_name/items?limit=50&offset=200

The default page size and the maximum page size are set by the configuration parameters LimitDefault and LimitMax.

Sorting

The result set can be sorted by any property it contains. This allows performing “greatest N” or “smallest N” queries.

  • sortby=PROP orders results by PROP in ascending order

The sort order can be specified by prefixing + (ascending) or - (descending) to the ordering property name. The default is ascending order.

  • sortby=+PROP orders results by PROP in ascending order
  • sortby=-PROP orders results by PROP in descending order

NOTE: if used, + needs to be URL-encoded as %2B.

Example

http://localhost:9000/functions/countries_name/items?sortby=name