Help Center

Menu

Auto-completion web service

Auto-completion in Funnelback is delivered via a web service. The web service is accessed using a REST-style request and returns a JSON packet containing the auto-completion suggestions.

Calling suggest.json

The auto-completion web service is accessed at the following URL:

http://<FUNNELBACK_SERVER>/s/suggest.json

The suggest.json endpoint accepts the following parameters, passed as HTTP GET arguments.

  • collection=<COLLECTION_ID>: (mandatory) COLLECTION_ID should be replaced with the ID of the collection that contains the auto-completion.

  • profile=<PROFILE>: PROFILE should be replaced with the auto-completion profile to use. This is matched to the index.autoc_PROFILE autocompletion index file [Default=_default]

  • partial_query=<PARTIAL_Q>: (mandatory). PARTIAL_Q is the partial query as entered by the user. This equates to what the user has currently typed into the search box and the service is typically called on each keystroke.

  • show=<N>: Instructs the service to return up to N suggestions [Default=10]

  • sort=<SORT TYPE>: Indicate sort order for returned suggestions. Values are 0 (sort by score); 1 (sort by length from shortest first); 2 (sort alphabetically, ascending) [Default=0]

  • fmt=<FORMAT>: Sets the JSON format to use. This should be set to json++ - the default json mode is not compatible with newer auto-completion features including -partials mode for organic suggestions, cross-domain Javascript access and structured auto-completion. [Default=json]

  • alpha=<N>: Allows adjusting the balance between length of suggestion and its relevance to the partial query [Default=0.5]. Requires sort=0.

  • callback=<CALLBACK STRING>: Callback string, required when making JSONP requests.

Funnelback ships with a java Script library (funnelback.autocompletion.js) that implements integration with this web service.

suggest.json response

suggest.json returns JSON (or JSONP, if called with fmt=json++ and a callback string).

Each element returned in the JSON includes the following fields:

  • key: This is the full trigger as defined in the query completion CSV, or trigger term/phrase if an organic suggestion.

  • disp: This is the value that should be displayed to the end user. The disp_t field indicates the type of return and this could be HTML, plain text etc

  • disp_t: This indicates the type of the disp field. Possible values are: T (text only), H (HTML fragment), J (JSON data); C (Javascript callback)

  • wt: This indicates the computed weight. Can be used for sorting by score.

  • cat: (optional) Indicates a category that can be used to group the returned suggestions.

  • cat_t: (currently unused)

  • action: Action to perform when user selects this suggestion, and interpretation is indicated by the type in the action_t field. Field may contain plain text (to pass back to Funnelback as a query, or to extend the query with), a URL or Javascript code to execute.

  • action_t: This indicates the type of action to perform when the suggestion is selected. Possible values are:

    • C for a Javascript callback,

    • U for opening an URL,

    • Q for running a query,

    • E for extending a query,

    • S for system generated auto completion.

A sample return may look like:

jQuery110202721093448339271_1415313528566([{
    "key": "australian visa entitlement",
    "disp": "Visa entitlement verification",
    "disp_t": "T",
    "wt": "100",
    "cat": "",
    "cat_t": "",
    "action": "http://www.immi.gov.au/Services/Pages/vevo/vevo-overview.aspx",
    "action_t": "U"
}, {
    "key": "australian visa",
    "disp": "Resident return visa",
    "disp_t": "T",
    "wt": "99",
    "cat": "",
    "cat_t": "",
    "action": "http://www.immi.gov.au/migrants/residents/visa-options.htm",
    "action_t": "U"
}, {
    "key": "austn public service commission",
    "disp": "austn public service commission",
    "disp_t": "T",
    "wt": "58",
    "cat": "Normal Web-style query suggestions",
    "cat_t": "1",
    "action": "",
    "action_t": ""
}, {
    "key": "australia at war",
    "disp": "australia at war",
    "disp_t": "T",
    "wt": "28.11",
    "cat": "Normal Web-style query suggestions",
    "cat_t": "1",
    "action": "",
    "action_t": ""
}])