Dev:APIsuggest

Auto-Search-Suggestions

This servlet can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions. The suggestion interface is an implementation of the Opensearch Suggestion Extension.

Operations performed when the servlet is called

The serlet is called with a set of words. The servlet then tries to find useful suggestions based on those words. A google search suggestion is based on the experience with common search queries but this can not be the strategy of a search engine, which cannot use such data because of no or too less users. YaCy tries to complete the searches based on common occurrences of similar words. To find such words, YaCy creates first a set of possible wrong-spellings of the given words which is computed by permutions of missing characters, superflous characters, twisted characters and missing head oder tail of the word. When such a set of possible replacements is computed, all of them (possibly some hundred) are tested against the search index and such words which appear most in the existing index are selected. These words are then returned as suggestions.

Servlet Address

The servlet can be called on two paths, these paths are /suggest.json and /suggest.xml. The full URL is http://<peer-IP>:<peer-port><servlet-path>. The json-variant represents the opensearch description and the xml variant is similar.

Properties in the http header

The caller must obey the http header rules.

Properties in the http post-arguments

Calls to the servlet can be made using a GET or POST operation. The properties are:

• q=<query> the query can contain several words, each of them separated by a '+'
• timeout=<milliseconds> a timeout for the computation of the suggestions (optional)
• count=<number-of-suggestions> the maximum number of suggestions to be computed (optional)

Result

The returned document contains a result as described in Opensearch Suggestion Extension

Example Usage

We give two examples, one for a json and one for an XML result

Example 1

http://localhost:8090/suggest.json?q=brelin returns

["brelin",["berlin","brolin","bredin","belin","brein","breslin"]]

Example 2

http://localhost:8090/suggest.xml?q=hanno returns

<?xml version="1.0"?>
<SearchSuggestion xmlns ="http://schemas.microsoft.com/Search/2008/suggestions">
<Query>hanno</Query>
<Section>
  <Item>
    <Text>anno</Text>
  </Item>
  <Item>
    <Text>hanna</Text>
  </Item>
</Section>
</SearchSuggestion>