You can use our recommendation system to identify items that have trended over a specific period of time. This function can be used either to populate a "Trending Now" widget on your site, or for internal usage to see how content is performing and identify more general trends. 

In general, using this to recommend items to your users will not perform as well (in terms of CTR) as the personalized recommendations generated by a normal widget implementation. Therefore we recommend using this for displaying recommendations only in cases where you specifically want to generate a list of top items and are not concerned about optimizing for CTR.

Defining "Trending" Metrics and Time Period

There are three parameters that you can use to define how "trending" should be measured:

• rankingKey is the key used to rank the items in decreasing order. The following values are allowed for rankingKey: 
  • "click" - items will be ranked from most to least clicked
  • "visible" - items will be ranked from most often included in a widget_visible (scrolled into viewport) event to least.
  • "show" - items will be ranked from most often included in a widget_shown (loaded on the page) event to least.
  • "click:visible" - this is treated as a ratio. Items will be ranked according to how often they are clicked compared to how often they are visible. (This corresponds to the "VCTR" metric in the widget Analytics)
  • "click:show" - this is treated as a ratio. Items will be ranked according to how often they are clicked compared to how often they are shown (loaded on page). (This corresponds to the "CTR" metric)
  • "visible:show" - this is treated as a ratio. Items will be ranked according to how often they are visible compared to how often they are shown. (This corresponds to the "Visibility" widget metric)
  • If no value is specified for rankingKey we return the items with the most activity, but in an essentially random order.
• lookupKey is a key with two possible values: 
  • "click" - restricts consideration to a shortlist of items that have received a lot of clicks.
  • "popular" - restricts consideration to a shortlist of items that have received a lot of pageviews
  • If no value is specified, we will use "click" by default.
• hoursBehind is the number of hours behind to go in this computation. For instance, setting this to 24 means that we will return the top items (based on rankingKey and lookupKey) over the last 24 hours.

Implementation (Javascript)

Recommending trending items is activated by including at least the "hoursBehind" parameter in the "opts" parameter of a widget registration. Below is a simplified test example that will request a list of the top clicked items over the last 24 hours.

$p('register', {
  max: 10, // Large number requested so you can see our full range of items
  widget: 'default-widget', // name of widget
  opts: {
    "rankingKey": "click",
    "hoursBehind": 24
  },
    callback: function(resp) {
      console.log(JSON.stringify(resp, null, 2));
      console.log("// TEST.");
    }
  }
);

Implementation (API)

You'll send your request to the /model endpoint and use many of the same parameters that would be included in a standard request for recommendations. The full list of parameters that can be used when requesting trending items via the API (required are in bold):

• apiKey
• rankingKey
• lookupKey
• hoursBehind
• maxCount (will default to 10 if not specified)
• getQueryInfo (note that the specific pieces of information returned are fewer since some of the computation steps that we apply in a general model query do not apply here)
• requestFields
• requestFieldsAON 

All other fields are ignored.