Contextual navigation: data model

Contextual navigation information is returned within the following data model elements:

  • question.cnClickedCluster and question.cnPreviousClusters

  • response.resultPacket.contextualNavigation

Contextual navigation - data model main elements

  "question": {
    "cnClickedCluster": "orange juice", (1)
    "cnPreviousClusters": [ (2)
  "response": {
    "resultPacket": {
       "contextualNavigation": { (3)
         "searchTerm": "Orange Juice", (4)
         "clusterNav": { (5)
         "categories": [ (6)
         "customData": {} (7)
1 question.cnClickedCluster: provides information on a contextual navigation cluster that was clicked, resulting in the current query.
2 question.cnPreviousClusters: is an array of previous contextual navigation clicks, and can be used to construct a breadcrumb trail of contextual navigation that results in the current query.
3 response.resultPacket.contextualNavigation: All contextual navigation information required to build the contextual navigation is contained within this element.
4 response.resultPacket.contextualNavigation.searchTerm: Indicates the search term(s) used to generate this contextual navigation
5 response.resultPacket.contextualNavigation.clusterNav: Includes information that can be used to build a navigation element for contextual navigation.
6 response.resultPacket.contextualNavigation.categories: The contextual navigation items, grouped into categories of type, topic and site.
7 response.resultPacket.contextualNavigation.customData: General-purpose element that can be used to store custom information when extending contextual navigation using plugins or hook scripts.

Categories element

The response.resultPacket.contextualNavigation.categories element contains the full set of contextual navigation suggestions.

The individual suggestions are grouped into three contextual navigation categories of type, topic and site. The (maximum) number of suggestions returned for each of these groupings can be controlled via the contextual_navigation.type.max_clusters, contextual_navigation.topic.max_clusters and settings.

categories: [
    "name": "type", (1)
    "more": 0, (2)
    "moreLink": null, (3)
    "fewerLink": "?log=false&profile=_default_preview&query=orange&collection=training%7Esp-foodista", (4)
    "clusters": [ (5)
        "href": "?clicked_fluster=cup+orange&cluster0=orange&log=false&profile=_default_preview&query=%60cup+Orange%60&collection=training%7Esp-foodista",
        "count": 10,
        "label": "Cup...",
        "query": "cup Orange"
    "name": "topic",
    "more": 0,
    "moreLink": null,
    "fewerLink": null,
    "clusters": [
        "href": "?clicked_fluster=orange+juice&cluster0=orange&log=false&profile=_default_preview&query=%60Orange+Juice%60&collection=training%7Esp-foodista",
        "count": 42,
        "label": "...Juice",
        "query": "Orange Juice"
        "href": "?clicked_fluster=orange+zest&cluster0=orange&log=false&profile=_default_preview&query=%60orange+zest%60&collection=training%7Esp-foodista",
        "count": 19,
        "label": "...Zest",
        "query": "orange zest"
1 The category name. Possible values are type. topic and site.
2 The number of additional values.
3 A link to expand the list of values. (legacy)
4 A link to shrink the list of values. (legacy)
5 The list of suggestions.

The clusters element contains the following for each suggestion that is returned:

    "href": "?clicked_fluster=orange+juice&cluster0=orange&log=false&profile=_default_preview&query=%60Orange+Juice%60&collection=training%7Esp-foodista", (1)
    "count": 42, (2)
    "label": "...Juice", (3)
    "query": "Orange Juice" (4)
1 Link that runs the suggested query
2 Number of results found when generating this suggestion. Note that this number is not an accurate representation of the number of results that will be returned when clicking on the suggestion as the suggestions are only extracted from a small sample of results.
3 A label to use when presenting the suggested query. Note: the …​ in the suggestion should be replaced with the query that was used to generate the list of suggestions.
4 The query that will be run when this result is clicked on

ClusterNav element

The ClusterNav is a legacy element that

The response.resultPacket.contextualNavigation.clusterNav element includes navigational information that can be used when building your contextual navigation widget.


  "clusterNav": {
    "level": 0, (1)
    "url": "log=false&profile=_default_preview&query=orange&collection=training%7Esp-foodista", (2)
    "label": "orange" (3)
1 response.resultPacket.contextualNavigation.clusterNav.level: The level of this navigation item.
2 response.resultPacket.contextualNavigation.clusterNav.url: The URL to reach this navigation item.
3 response.resultPacket.contextualNavigation.clusterNav.label: THe label for this navigation item.

Contextual navigation HTML

Contextual navigation is commonly templated in HTML using a pattern similar to the code below:

<h2>Related searches</h2>

<#for each cluster>
  <li><a href="{cluster.href}">{cluster.label->replace('...' with {contextualNavigation.searchTerm} }</a></li>

Display contextual navigation in a Freemarker results template shows the template code of how best bets are templated using Freemarker, which is used in the default Funnelback template. This example can be adapted to other languages.