1. Response structure and objects

The facet response object

You get a facet JSON object in the Sitecore Discover Search and Recommendation response if you send a facet object in the request. The response returns the <facet_type> requested and shows the corresponding facet values according to the keys in your request.

The following code shows the basic structure of the facet object in a response:

{
    "facet": {
	"<facet_type>": {
        	"number_of_products": 2,
		"total": 10,
		"display_name": "<alternate_display_name>",
		"value": [{
			"id": "<facet_value_id>",
			"text": "<display_text>",
			"count": 15,
			"min": 1,
			"max": 10,
			"in_content": "<content_type>",
			"<other_fields>": "<field_value>",
			"sub": [<facet_value>]
		}]
	},
    "facet_names": [{<facet_type>}]
}

Keys

Depending on your request you might see some or all response keys.

The following table describes the keys in the facet response object:

KeyTypeDescription
facet_typeFacet type objectReturns the <facet_type> sent in your request.

Facet type object

The following table describes the keys in the facet_type object:

KeyTypeDescription
number_of_productsnumberThe number of products containing an attribute value with the <facet_type>.
totalnumberTotal number of facet values for the <facet_type>.
display_namestringAlternate name to display the <facet_type>.You can contact your support representative if you want the response to display a different name for the returned <facet_type>.
idnumberA unique ID that corresponds to the facet value.You can use the id to filter future requests.
<other_fields>stringThe response returns the <field_value> when there is an additional field requested.
minnumberThe minimum value in a range.The response returns this only when the <facet_type> supports a range. For example, price.
maxnumberThe maximum value in a range.The response returns this only when <facet_type> supports a range. For example, price.
subarrayThe response returns this only when the <facet_type> supports a nested structure such as a category tree.
facet_namesarrayDetermines the order of the returned facets. Each <facet_type> in the array corresponds to a facet returned in the response.NoteThe order of the returned facets reflects how you explicitly configured it in the Customer Engagemenrt Console (CEC). Otherwise, you get the default order.

Facet types

The following are default facets that come with all implementations. You can define additional facet types that are specific to your industry when you do the initial data feed.

<facet_type>Description
brandFilter by product brands.
category_namesFilter by product category names.
priceFilter by price or price range.
ratingFilter by product review rating. You must specify a min and a max.

Examples

Example 1: The following is an example of a response containing a term facet with discrete values. In the response, there are:

  • Five Red items
  • Two Blue items
  • A total of eleven types of colors, but only two are shown
{
    "facet": {
	"colors": {
              "number_of_products": 235,
		"total": 11,
		"value": [{
		    "id": "cr1",
		    "text": "Red",
		    "count": 5
		   },
		   {
		    "id": "cr2",
		    "text": "Blue",
		    "count": 2
		    }
	        ]
        }
    }
}

Example 2: The next example is a response containing a range facet where:

  • The total number of buckets is two
  • The minimum (min) of the price range is 10
  • The maximum (max) of the price range is 50
  • The value contains the suggested buckets where:
    • There are two groups of buckets
    • The first bucket is from 10 to 20
    • The second bucket is from 20 to 50
{
    "facet": {
	"price": {
	    "number_of_products": 27,
	    "total": 2,
	    "min": 10,
	    "max": 50,
	    "value": [{
		"id": "p1",
		"text": "10 - 20",
		"count": 5,
		"min": 10,
		"max": 20
               },
	       {
		"id": "p2",
		"text": "20 - 50",
		"count": 2,
		"min": 20,
		"max": 50
	        }
	    ]
	}
    }
}

Example 3: The following is an example of a nested facet having a hierarchical structure. In this example, there are four categories:

  • Mens > Shirt
  • Mens > Pants
  • Women > Shirt
  • Women > Pants
{
"facet": {
  "category_tree": {
    "value": [
      {
        "id": "ct1",
        "text": "Mens",
        "count": 5,
        "sub": [
          {"id": "ct11", "text": "Shirt", "count": 2},
          {"id": "ct12", "text": "Pants", "count": 3}
        ]
      },
      {
        "id": "ct2",
        "text": "Women",
        "count": 2,
        "sub": [
          {"id": "ct21", "text": "Shirt", "count": 1},
          {"id": "ct22", "text": "Pants", "count": 1}
        ]
      }
    ]
  }
}
If you have suggestions for improving this article, let us know!