Geospatial Search End Points

A geospatial search End Point is responsible for searching and optionally importing geospatial data according to a standard search schema. The open standard GeoJSON has been selected as the return format for all geospatial search End Points.

Namespace

By convention, all geospatial search End Points must be named search and must be created under the root namespace; goss.geospatial.layers. As it is not possible to create multiple End Points with the name search in the same folder, and to assist with categorisation, further subfolders should be used to categorise and name the search End Points. The full namespace of a geospatial search End Point should be goss.geospatial.layers.category.name.search, where category and name should be replaced as required.

For example, the following shows an example of a Flood Alerts search End Point that has been categorised under Environment.

Input Schema

All geospatial search End Points must accept a standard request parameter schema which looks like the following.

The schema is made of up the following key fields.

spatialFilter

The spatialFilter parameter allows the caller to define the spatial search area, currently searches may be performed with a bounding box or a point and radius circle.

distanceTo

The optional distanceTo parameter allows the caller to specify an arbitrary point (latitude and longitude) for which each search result will return it's distance to.

maxRows

The maxRows parameter allows the caller to request only a certain amount of search results are returned.

End Point Script

The purpose of a geospatial search End Point is to take the input parameters described above and return a list of results for the layer as a GeoJSON object, at it's most basic level this is all it needs to do. However one may wish to consider that it is also possible to import the results into the iCM database as part of the search for the benefit of future requests. Depending on the original source of the data this may provide substantial performance improvements.

The search End Points that are provided as out of the box examples all follow the following steps in code:

1. Check if an import exists for the requested search area

If yes...

2. Retrieve the data from the iCM database using a geospatial database query and return it immediately as GeoJSON

If no...

2. Retrieve the data from the original source (this could be a 3rd party API, CSV file, iCM article data... anywhere!)
3. Convert the original source data to GeoJSON
4. Import the data into the iCM database against the layer and search region
5. Dependent on the original source, post process the data to calculate distances, apply sorting and max row filtering.
6. Returns post processed GeoJSON result

Take a look at the Geospatial Layer Search Helper, which provides useful functions for developing geospatial import End Points.