ksuggest

Necessity:mandatory
Value:false | id:123 | url:ENCODED_URL
Default:false

The parameter ksuggest activates the Keyword Suggester and returns suggestions to the given image. An image ID or image URL are supported value types.

Set this parameter to the internal image ID or external image URL for which you want to retrieve keyword suggestions as shown in the examples below. Other Keyword Suggester related parameters will only be parsed and processed if ksuggest is set accordingly.

Simple example for retrieving keyword suggestions to a given external image URL using the field with name keywords:

?q=*:*&ksuggest.field=keywords&ksuggest=url:http%3A%2F%2Fwebsite.org%2Fimage.jpg&ksuggest.field=keywords

Percent-encoded URLs

URLs need to be properly percent-encoded. Please read URL Encoding carefully to generate valid URLs that can be parsed and processed.

Simple example for retrieving keyword suggestions to a given image ID using the field with name keywords:

?q=*:*&ksuggest.field=keywords&ksuggest=id:123

If you have configured ksuggest.field in the solrconfig.xml there is no need to set it in the query again.

Response format:

The suggestions are appended to the response within the ksuggest tag (See below). Each keyword object contains the suggested keyword and a confidence value.

Example json response with keyword suggestions:

{
  "responseHeader":{
    "status":0,
    "QTime":46,
    "params":{
      "q":"*:*",
      "ksuggest.field":"keywords",
      "ksuggest":"id:123"}},
  "response":{"numFound":3564,"start":0,"docs":[
    {
   [ ... ]
    },
  "ksuggest":{
    "num":20,
    "keywords":[{
        "keyword":"nature",
        "confidence":1.0},
      {
        "keyword":"sun",
        "confidence":0.7},
      {
        "keyword":"tree",
        "confidence":0.5},
  [ ... ]
      {
        "keyword":"river",
        "confidence":0.2}]}
  }
}

In the example response above the Keyword Suggester suggests nature, tree, sun and river as fitting keywords to the image referenced by ID 123. The returned suggestions sorted by confidence in descending order.

The confidence value is a float number between 0.0 - 1.0 describing the configdence relative to the other suggestions of the response. The first suggestion will always have a confidence value of 1.0. For example tree (0.5) is half as confident as nature (1.0), but more than twice as confident as river (0.2). The confidence value not mean that keyword nature is a never-known-to-fail suggestion, instead it is an indicatior of the quality of one suggestion relative to the others within one query.

Therefore, confidence values can not be compared between different queries. They only have a relative meaning per query.