Suggest

With the suggest action, a collection is queried using a partial search term. This makes it ideal for live autocomplete and/or autosuggest.

When processing a request, Pandosearch is using multiple fields for each document in the collection. The exact fields depend on the specific configuration for the collection.

Request

To retrieve suggestions from Pandosearch, make a GET request to the following URL:

https://public.pandosearch.com/:collection/suggest

All possible parameters need to be provided as query parameters.

In the rest of this page, the full URL and collection name are omitted for readability.

Parameter: q

Use the q query parameter when searching for suggestions based on a part of the full query string. The q parameter is automatically escaped and is always interpreted as a string.

The following call will return all suggestions and hits for "pand":

suggest?q=pand

For autocompletion, the next word that is likely to be typed is often relevant. When you end the search query with a space, the next most likely word that is automatically returned in the suggestions.

Example: the following call will return suggestions for the next word after "what":

suggest?q=what%20

Be aware that a space is not a valid character in a URL and thus needs to be URL encoded (i.e. %20).

Parameter: size

To control the number of results returned for each request, use the size query parameter. The size parameter expects an integer and defaults to 5.

Example: the following call will return 5 suggest results for "pand":

suggest?q=pand&size=5

Parameter: track

In Pandosearch, all API requests are automatically tracked. We do not track any personal information – only information about the query sent and the results returned.

Tracking can be turned off by using the track parameter. If track=false is passed, the result won't be tracked or included in usage reports. In all other cases, the result will be tracked and included in usage reports.

An example use case is internal testing. You usually don't want your test requests to pollute your search usage analytics. To achieve this, you can use the track parameter as follows:

suggest?q=test&track=false

Response

A suggest response is a JSON document with the following structure:

{
  "suggestions": [
    {
      "text": "pandosearch"
    },
    {
      "text": "panden"
    },
    {
      "text": "panda"
    }
  ],
  "hits": [
    {
      "title": "<b>Pand</b>osearch. Precies wat je zoekt.",
      "url": "https://enrise.com/diensten/search/",
      "type": "page",
      "body": "Meer weten over search? Bel: 088-5553311 “Onze klanten krijgen razendsnel toegang tot producten en oplossingen. <b>Pand</b>osearch biedt exact dát wat we nodig hebben.” Waarom site search? Met site search vinden je gebruikers…",
      "category": "diensten"
    },
    {},
    {},
  ],
  "timing": {
    "search": 13.26,
    "search:took": 12,
    "request": 19.63
  }
}

The suggest action returns three types of data:

  • suggestions – words in the index that contain the given query string. These are ideal for an autocomplete implementation (to help the user finalize the query).
  • hits – Documents that contains the given query string. These are ideal for an autosuggest implementation (give the user search results based on "half a word").
  • timing – Data that can be used for monitoring performance.

Read on for more details for each individual response data part.

Data: suggestions

The suggestions property contains the words in the index that contain the given search query. These suggestions are ranked based on the occurence of that word in the index. The suggestions are always represented as array of objects. Each object looks as follows:

{
  "text": "pandosearch"
}

Highlighting

It is possible to use highlighting on suggestions. This option is enabled by us on request.

If enabled, the display property is appended for each suggestion. It highlights the query in the given suggestion.

{
  "text": "pandosearch",
  "display": "<b>pand</b>osearch"
}

Data: hits

The hits property contains the full collection of documents found in the index, based on the given search query. It is always represented as array of objects. Each object looks as follows:

{
  "type": "page",
  "url": "https://enrise.com/diensten/search/",
  "fields": {
    "title": "<b>Pand</b>osearch. Precies wat je zoekt.",
    "body": "Meer weten over search? Bel: 088-5553311 “Onze klanten krijgen razendsnel toegang tot producten en oplossingen. <b>Pand</b>osearch biedt exact dát wat we nodig hebben.” Waarom site search? Met site search vinden je gebruikers…"
  }
}

For each document, a range of fields can be returned. The fields that are returned differ per customer. Each field is highlighted by default by wrapping the search term in <b> </b>-tags. The url field is the unique identifier for this document. The type field is the type of document.

Highlighting

When returning results, each document is returned highlighted. This works as follows:

The part where the search term was found in a field of the document is transformed to a snippet. A snippet is (by default) max 250 characters long and it is "smart": words are kept intact as much as possible. The snippet is always created around the search term, so the search term will always be included in the snippet and is wrapped in <b></b> tags (or other markup as configured for your implementation). Per result, only one snippet is returned.

Data: timing

The timing object contains all information about the time your request took. It is divided into:

  • search:took – Total amount of time spent by Elasticsearch in ms.
  • search – Total amount of time between sending the request to Elasticsearch and the receiving a back from Elasticsearch in ms (this is basically search:took + network overhead).
  • request – Total amount of time between the request coming in and sending the response out in ms.