Interface Description

api.v2.suggest

Overview

Mindbreeze InSpire provides suggestions with a simple interface. This interface is based on HTTP and JSON.

Requests are sent as HTTP POST to a client service. The path for search queries is:

<Client Service URL>/api/v2/suggest

The following request gets 3 suggestions for document titles containing words starting with mindbre:

{

  "query": "mindbre",

  "count": 3

}

Sample suggestions with the command line tool curl:

curl https://demo.mindbreeze.com/public/api/v2/suggest -d "{\"query\":\"mindbre\",\"count\":3}"

Sample Response

{
  "suggest_request": {
    "query": "mindbre",
    "count": 5,
    "user_context": {}
  },
  "results": [
    {
      "value": "Mindbreeze Basic Training",
      "html": "<span class=\"matched\">Mindbre</span><span class=\"unmatched\">eze Basic Training</span>",
      "score": 9216,
      "source": "DOCUMENT_PROPERTY",
      "source_name": "Name",
      "source_id": "document_property",
      "complete_match": false
    },
    {
      "value": "Mindbreeze Advanced Training",
      "html": "<span class=\"matched\">Mindbre</span><span class=\"unmatched\">eze Advanced Training</span>",
      "score": 8192,
      "source": "DOCUMENT_PROPERTY",
      "source_name": "Name",
      "source_id": "document_property",
      "complete_match": false
    },
    {
      "value": "Mindbreeze Development Training",
      "html": "<span class=\"matched\">Mindbre</span><span class=\"unmatched\">eze Development Training</span>",
      "score": 8192,
      "source": "DOCUMENT_PROPERTY",
      "source_name": "Name",
      "source_id": "document_property",
      "complete_match": false
    }
  ]
}

Fields in the Result

suggest_request

The request.

results

Contains the suggestions. Each suggestion contains the text including highlighting (html) as well as without (value). complete_match specifies if the match was exact or only in part. score provides a means for sorting the suggestions, higher means better. source is the type of the suggest source, source_name the display name and source_id the ID. See Suggest Sources.

Scenarios

Each of the following sections covers one task, and can be combined with one another.

Restricting the Suggestions

The property_constraint options restricts the suggest results with a Query Expression. Note: Not all suggest sources respect this option.

{
  "query": "mindbre",
  "count": 3,
  "property_constraint": {
    "unparsed": url:www.mindbreeze.com
  }
}

Suggest Sources

source_id_pattern is a regular expression defining with suggest sources to use. “document_property“ activates metadata suggestions. Additionally, you can use the ID values from the configuration (e.g. Client Service > Suggest Settings (Similar Terms) or Suggest Settings (Concept CSV)).

The property to autocomplete can be set with the property option.

The following example fetches suggestions for the metadatum extension as well as the sources with ID “popluar_searches” and “concept”.

{
  "query": "htm",
  "count": 3,
  "source_id_pattern": "document_property|popular_searches|concept",
  "property": "extension"
}

Sample for suggestions with all configured suggest sources:

{

  "query": "htm",

  "count": 3,

  "source_id_pattern": ".*"

}

Localization of Multilingual Metadata

user_context.locale specifies the locale with which multilingual metadata is translated.

{

  "query": "mindbre",

  "count": 3,

  "user_context": {              

    "locale": "de-AT"            

  }

}

Canceling Simultanious Requests

You can send the option task_id to abort all currently running suggest requests with the same task_id.