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 get parameter (query) that expects a complete Universal Search String and returns a collection of resources (cids JSON objects).
Example: ?query=fromdate:%222014-12-31%22+todate:%222015-01-15%22+keyword:%22water+quality%22
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 cen 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. Currently, class filters are appended to the Universal Search String. If feasible, the API could be extended by a dedicated query parameter for classes like in the general CRUD REST API (yet to decided).
- 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
- 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.