Recommendations API

The Recommendations REST API uses signals and aggregated signals to return a list of items that can be used for recommendations.

To use the REST API Recommendations service to get recommendations for items in some collection, that collection must have associated signals and aggregated-signals system collections. How good the recommendations are depends on how well the information in the signals and aggregated signals collections, which is derived from observed user behavior, matches user behavior going forward.

In addition to these endpoints, is also possible to get recommendations as part of a query request.

See Recommendations for a discussion of when to use the API and when to use recommender query stages.

Recommendation types

The API includes separate endpoints for retrieving different types of recommendations:

itemsForQuery

Get items for a defined query.

The response is a list of document IDs and their weights.

queriesForItem

Get queries for a defined item (a document ID). This finds the top queries that led users to the defined item.

The response is a list of query terms and their weights.

itemsForItems

This type retrieves items that are related to a defined item (a document ID). This can be thought of as "People also viewed…​".

The response is a list of document IDs and their weights.

This type combines itemsForQuery and queriesForItem. It gets the top items using queriesForItems, creates shingles using the queries, then joins the shingles with an OR clause to use itemsForQuery to get the top items.

Request Parameters

itemsForQuery parameters

Parameter Description

q
Required

The query terms to search for.

rows
Optional

The number of items to return. The default is 10.

fq
Optional

A filter query to limit results. If used, the field name must be included along with the value.

aggrRows
Optional

The amount of rows per aggregation. The default is 100.

aggrType
Optional

The type of aggregation. The default is aggregated click.

debug
Optional

If true, debug information will be returned with the results. The default is false.

There are also several parameters used to boost possible matches, which can be modified with the Configurations API. By default the following boosts and defaults are applied:

  • A query filter limiting the query to the 'query_t' field (qf=query_t). This is defined with the configuration property com.lucidworks.apollo.service.recommend.solr.query.qf

  • Three phrase field boost on the 'query_t' field (pf=query_t3,query_t27,query_t0^1). This boosts the 'query_t' field by 3 when terms are next to each other, a boost of 7 when they are within 2 terms of each other, and an additional boost of 1. This is defined with the configuration property`com.lucidworks.apollo.service.recommend.solr.query.pf`.

  • A minimum match of 50% (mm=50%), which means at least 50% of the terms used must be present. This is defined with the configuration property com.lucidworks.apollo.service.recommend.solr.query.mm.

  • The query parser is 'edismax (defType=edismax). This is defined with the configuration property com.lucidworks.apollo.service.recommend.solr.query.defType.

  • The sort is by descending score, then descending weight (score desc, weight_d desc). This is defined with the configuration property com.lucidworks.apollo.service.recommend.solr.query.sort.

queriesForItem parameters

Parameter Description

docId
Required

The document ID to search for.

rows
Optional

The number of items to return. The default is 10.

aggrType
Optional

The type of aggregation. The default is aggregated click.

itemsForItems parameters

Parameter Description

docId
Required

The document ID that is the basis for the itemForItem query.

rows
Optional

The number of items to return. The default is 10.

shinglesLimit
Optional

The maximum number of shingles (nGrams) to use. The shingles will be joined with a boolean OR statement to find the related documents for the named item. The default is 20.

aggrRows
Optional

The amount of rows per aggregation. The default is 100.

aggrType
Optional

The type of aggregation. The default is click.

termsLimit
Optional

A limit to the number of terms from queries to use in the itemForItems calculation. The default is 30.

Output

The output includes the following sections:

header

The query parameters (in a section named queryParams) and the total time it took to process the query.

items

Depending on the recommendation type:

  • itemsForQuery

    The document IDs and the weights of aggregated events that match the query. This type supports a debug option that adds a debug section to the output.

  • queriesForItem

    The queries and the weights of aggregated events that match the document ID.

  • itemsForItems

    The document IDs and the weights of aggregated events that match the query.

Examples

Below are examples for each recommendation type.

itemsForQuery

Get the top items for the query 'ipod':

INPUT
curl -u user:pass http://localhost:8764/api/apollo/recommend/lucidworks102/itemsForQuery?q=ipod&fq=count_d:4&debug=true
OUTPUT
{
  "header" : {
    "queryParams" : {
      "aggrType" : "*",
      "rows" : 10,
      "collection" : "lucidworks102",
      "aggrRows" : 100,
      "debug" : true,
      "q" : "ipod",
      "fq" : [ "count_d:4" ]
    },
    "totalTime" : 5
  },
  "items" : [ {
    "weight" : 1.0726584E-11,
    "docId" : "8771929"
  }, {
    "weight" : 3.865899E-12,
    "docId" : "9225439"
  }, {
    "weight" : 9.230597E-12,
    "docId" : "3109302"
  } ],
  "debugInfo" : {
    "aggrTime" : 1,
    "queryTime" : 4,
    "solrParams" : {
      "mm" : [ "50%" ],
      "pf" : [ "query_t^3", "query_t~2^7", "query_t~0^1" ],
      "fl" : [ "id", "doc_id_s", "weight_d" ],
      "sort" : [ "score desc,weight_d desc" ],
      "q" : [ "ipod" ],
      "qf" : [ "query_t" ],
      "collection" : [ "lucidworks102_signals_aggr" ],
      "fq" : [ "aggr_type_s:*", "count_d:4" ],
      "rows" : [ "100" ],
      "defType" : [ "edismax" ]
    }
  }
}

queriesForItem

INPUT
curl -u user:pass http://localhost:8764/api/apollo/recommend/lucidworks102/queriesForItem?docId=9225439
OUTPUT
{
  "header" : {
    "queryParams" : {
      "aggrType" : "*",
      "rows" : 10,
      "collection" : "lucidworks102",
      "docId" : "9225439"
    },
    "totalTime" : 8
  },
  "items" : [ {
    "query" : "ipod",
    "weight" : 3.865899E-12
  }, {
    "query" : "columbusday ipod mp3 20111009",
    "weight" : 3.5141304E-12
  }, {
    "query" : "apple itouch",
    "weight" : 2.3619889E-12
  }, {
    "query" : "ipod 4th generation",
    "weight" : 1.6436526E-12
  }, {
    "query" : "ipod touch 4th generation",
    "weight" : 9.674966E-13
  }, {
    "query" : "onlinemidnightsale ipod mp3players",
    "weight" : 9.568035E-13
  }, {
    "query" : "ipod touch",
    "weight" : 7.774231E-13
  }, {
    "query" : "itouch",
    "weight" : 7.707221E-13
  } ]
}

itemsForItems

INPUT
curl -u user:pass http://localhost:8764/api/apollo/recommend/demo/itemsForItem?docId=9225439
OUTPUT
{
  "header" : {
    "queryParams" : {
      "aggrType" : "*",
      "rows" : 10,
      "collection" : "lucidworks102",
      "aggrRows" : 100,
      "docId" : "9225439",
      "shinglesLimit" : 20,
      "termsLimit" : 30,
      "q" : "ipod OR columbusday ipod mp3 OR ipod mp3 20111009 OR columbusday ipod OR ipod mp3 OR mp3 20111009 OR 4th generation OR apple itouch OR itouch OR ipod touch OR ipod 4th OR ipod 4th generation OR ipod touch 4th OR touch 4th generation OR touch 4th OR onlinemidnightsale ipod mp3players OR onlinemidnightsale ipod OR ipod mp3players"
    },
    "totalTime" : 63
  },
  "items" : [ {
    "weight" : 1.02983795E-10,
    "docId" : "9225377"
  }, {
    "weight" : 1.1725405E-11,
    "docId" : "9225439"
  }, {
    "weight" : 7.803512E-13,
    "docId" : "1207345"
  }, {
    "weight" : 7.803291E-13,
    "docId" : "2193848"
  }, {
    "weight" : 7.803053E-13,
    "docId" : "2128719"
  }, {
    "weight" : 1.4804163E-12,
    "docId" : "1237142"
  }, {
    "weight" : 1.480315E-12,
    "docId" : "2136062"
  }, {
    "weight" : 3.4738492E-12,
    "docId" : "1207414"
  }, {
    "weight" : 3.4676099E-12,
    "docId" : "2382259"
  }, {
    "weight" : 1.7393786E-12,
    "docId" : "1200933"
  } ]
}