Universal Search API Specification
Universal Search API Specification for SWITCH-ON.
The Universal Search Box allows to specifically search for resources by defining different pre-search filters (keywords, spatial coverage, temporal coverage, ...) of resources. Depending on the types of pre-search filters specified, a specific input format of the filter expressions entered is expected.
The general format for such a filter expression is: $filter : "$parameter", whereby $filter is an arbitrary filter keyword and $parameter is an arbitrary value in double quotes. A simple RegEx for validating filter expressions is /^(\w+:".+"\s?)+$/
The filter-specific formats of the filter parameters may differ from filter to filter. See below for a list of predefined filters and the respective parameter specifications.
For the user, there are two possibilities for specifying pre-search filters that are applied when performing a search for resources with help of the Universal Search Box:
- The user can directly input appropriate filter expressions in the Universal Search Box, e.g. keyword:"water quality”, or
- the user can use various UI Widgets, for example the Search Filter Ribbon, that are provided for different type of search filters (spatial, temporal, keywords, ...). For some examples of such Widgets, please refer to User Interface Mockups (Balsamiq Sources).
Some filters, like keywords, can occur multiple times. If not specified otherwise in the respective filter description, for each filter a separate filter expression is added to the Universal Search String.
Thus, the preferred syntax for such filters is for example not keywords:"water quality, catchments" but keyword:"water quality" keyword:"catchments"
The Universal Search API is simple API for server searches that (currently!) accepts a single parameter (query) that expects a complete Universal Search String and returns a collection of resources (cids JSON objects).
Endpoint for post requests:
http://host:8890/searches/SWITCH-ON.de.cismet.cids.custom.switchon.searches.universalSearch/results
Example JSON POST:
{"list":[{"key":"query","value":"fromdate:%222014-12-31%22+todate:%222015-01-15%22+keyword:%22water+quality%22"}]}
The API returns a collection of complete cids JSON (resource) objects.
This is a non-exhaustive list of predefined filters that are needed for SWITCH-ON. Both the Universal Search Box and the Universal Search API are not limited to the search filters described below. They may accept any filter expression that conforms to the general format for filter expressions.
The filter description mentions also to the Standard Information Model (SIM) of SWITCH-ON. For a general description of the SIM, please refer to the SWITCH-ON deliverable D2.2 “Standard Information Model for Meta-Data”. For a list of Meta-Data Repositories (Integration Base instances) that can be used for development and testing, please refer to the Developer Documentation of the cids-custom-switchon project.
Filter to restrict search results to specific (cids) classes. In SWITCH-ON there's only one class (Resource) that is relevant for the user and all subsequent filters are related to attributes of the Resource class.
- Filter Specification: class
- Parameter Specification: classname
- Occurrence: 1...n
- Filter Example: class:"resource"
- Relationship to SIM: All cids classes, especially 'resource'
Filter for simple keyword-based search.
- Filter Specification: keyword
- Parameter Specification: the keywords
- Occurrence: 0...n
- Filter Example: keyword:"water quality" keyword:"precipitation"
- Relationship to SIM: Keywords are all tags belonging to the tag groups “INSPIRE themes 1.0” and “keywords – open”. There is no dedicated attribute for Keywords in the Resource Class. Keywords Tags are stored in the tags [] attribute of the resource class together with other tags. Keyword search is already implemented in cids-custom-switchon-server.
Temporal coverage search for a start date of a resource data collection (fromdate) and end date of a resource data collection (todate).
- Filter Specification: fromdate and todate (Alternative for discussion: date_to and date_from?)
- Parameter Specification: ISO 8601 date
- Occurrence: 0...2
- Filter Example: fromdate:"2014-01-01" todate:"2014-12-31"
- Relationship to SIM: Attributes Resource/toDate and Resource/fromDate. If toDate is empty, this means that the collection of data is ongoing. However if fromDateand and toDateare both empty, it means that no information about temporal coverage is available. Temporal search is already implemented in cids-custom-switchon-server.
Geometry-based geospatial search based on coordinates. The coordinates of the search area (e.g. Bounding Box) can be selected with help of a separate UI Widget (e.g. map widget) and are also shown in the Universal Search Box in simplified format. The search supports the WKT geometry primitives Point and Polygon.
Besides the specification of the search extent (Point or Polygon), an additional filter can be provided that controls the behaviour of the search. By default, the search retrieves all resources that intersect with the specified coordinates. By setting the geo_intersects filter to true, the search returns only those resources that are completely contained in the specified coordinates. This is especially needed for SWITCH-ON, since most of the resources available have as spatial extent "world".
- Filter Specification: geo and geo_intersects
- Parameter Specification:
- geo: WKT Point or Polygon
- geo-intersects: true or false
- geo-buffer: > 0
- Occurrence:
- geo: 0...1
- geo_intersects: 0...1
- Filter Example: geo:"POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))" geo.intersects:"true"
- Relationship to SIM: The geom attribute of the Resource class leverages well know PostGIS spatial search and is available for all resources. Spatial search is already implemented in cids-custom-switchon-server.
Simple full text search on resource names and descriptions. Currently, the search can be implemented to search in resource names and descriptions. If required, an additional filter (e.g. text_scope) can be introduced that specifies the object attributes considered for full text search.
- Filter Specification: text
- Parameter Specification: anytext
- Occurrence: 0...1
- Filter Example: text:"USGS Hydrosheds"
- Relationship to SIM: Resource/name and Resource/description attributes. Text search is already implemented in cids-custom-switchon-server.