DE EN EN (Google)

Suggestion / Autocompletion

POST /api/v1/suggest?token=<token>

Autocomplete a user query.

Query String

token Session token acquired with /api/v1/session

Input

The input is provided as a JSON object with the following attributes:

Name Description
objecttypes Object types that are taken into accout for the autocompletion (array of strings)
query The user query to be autocompleted (string, optional): defaults to ""
tokens Whether this call returns token suggestions (boolean, optional): defaults to true
fields Fields to be taken into account for the autocompletion (array of strings, optional*)
fields_suggest Whether to return “field” type suggestions when fields is supplied (boolean, optional, defaults to true)
pool_ids Suggest only tokens from objects in pools with these IDs (array of integers, optional*)
languages Languages to be taken into account for l10n fields (array of strings, optional): defaults to all search languages of the user
linked_objecttypes Suggest also linked objects from this objecttypes (array of strings, optional*)
analyze_wildcards Whether wildcards ("*" and "?") are allowed in the query (boolean, optional): defaults to false
tokens_mode How the query token will be matched against the suggest index (string, optional, defaults to "ngram"):
  • For "ngram" the token matches against the ngram subfield
  • For "edgengram" the token matches against the left_ngram subfield (for a prefix search)
  • For "exact" the token matches against the folded subfield (exact search for the whole token)
tokens_dont_split_query By default, query is split into tokens, first parts are used as query filter, the last part is suggested. With this switch the tokenizing can be turned off, using the whole query to suggest. Only affects result returned in suggestions.tokens. (boolean, optional, defaults to false)
timeout If set, the request will return after the timeout with the results gathered so far (integer, optional): time in ms
limit Number of items to return in each response type ("tokens", "fields", "linked_objects") (integer, optional, defaults to 10)

Remarks:

Example:

{
    "objecttypes": [
        "book",
        "drawing"
    ],
    "query": "monst",
    // fields are fully qualified
    "fields": [
        "book.title",
        "drawing.description"
    ],
    // ISO 639-1 language code + "-" + ISO-3166 country code
    "languages": [
        "en-US"
    ]
}

Procedure

Output

The output is given as a JSON object. The input attributes are provided as a copy in the output. The rest is the real output of the autocompletion:

Name Description
es_time Time this request took in the Elasticsearch query/queries in milliseconds (integer)
timed_out Whether the request timed out (boolean): only present if the input parameter timeout was set
suggestions Object that MAY contain the following lists:
suggestions.tokens - List of results of the “token” type (see below)
suggestions.fields - List of results of the “field” type (see below)
suggestions.linked_objects - List of results of the “linked object” type (see below)

Type “tokens”

If the request parameter tokens is false, no tokens are returned.

The autocompleted tokens are ordered by descending reference count.

If a suggestion is considered an “exact match” of the last query token, it is marked so. Exact match means that a complete token matching the request (that is, ICU folded) was found. Exact matches are given priority and pushed to the beginning of the list.

Each token suggestion has the following properties:

Name Description
suggest The suggestion, with <b></b> markers for the given part (string)
tokens The tokens that build up the suggestion (array of strings)
count The number of occurrences of the autocompleted token (integer*)
exact_match Whether the autocompleted token was found exactly as given (boolean)

Remarks:

Type “field”

These suggestions are only given if fields is set. They show the whole field and not just the autocompleted tokens.

Name Description
field The complete field text that matches (string)
suggest The suggested field, with <b></b> markers for the given part (string)
count The number of occurrences of the autocompleted field (integer)

Type “linked_object”

These are objects that are linked to the main objects and match the autocompletion.

Name Description
object The linked object (object)

The linked object is annotated with highlights, in the same way as in the results of /api/v1/search.

HTTP status codes

200 Success
400 Error parsing request: attribute expected, incorrect type or value
403 Unauthorized session
404 Objecttype or field not found