Create custom range facets

By default, a facet displays all the unique values as a list. It can be useful to group all values between a minimum and maximum value and display a range of values as a single link. A common example of this is price ranges, for example, $10 - $20.

You create a custom range facet to display a group of values in a single link. To define a custom range facet, you must first create a new facet by calling the following Admin API endpoint:

POST /gsadmin/v1/cloud/attributes/system/<facet-name>.

Specify the following properties for the facet:

• ecr:type: Required. Value must be set to dimension.
• isAutogen: Required. Value must be set to false.
• displayConfig: See Configure the order of facet values for more information about this property.
• context: Optional. Set to priceGroup if the ranged facet is for pricing, or locale if the facet is multi-language.
• rangeComparisonType: Required. Value must be set to FLOAT.
• sourcePropertyNames: Required. List of one or more source properties, for example sku.activePrice, or product.x_megapixels.

Next, define each value in the Facets data store with the following Admin API endpoint:

POST /gsdata/v1/cloud/facets/<facet-name>

Specify the following properties for the facet values:

• key: Required. System ID for the facet value. Must be unique.
• displayName: Required. The text to display for the facet value.
• priceGroup: Optional. If the new facet will display prices, the price group needs to be explicitly defined. See Understand Price Navigation for more information.
• displayOrder: Optional. A displayOrder value can be assigned to sequence the facet value relative to the other values. See Configure the order of facet values for more information.
• lowerBound: Required. Minimum value to match for the range.
• upperBound: Required. Maximum value to match for the range.

Example: Create a custom price range

This section describes a step-by-step example of adding a custom price range facet.

First, create a new facet by issuing a POST request to the Attributes system endpoint:

POST /gsadmin/v1/cloud/attributes/system/Price
{
        "ecr:type": "dimension",
        "isAutogen" : false,
        "displayConfig": {
            "sort": "displayOrder,asc"
        },

        "context" : ["priceGroup"],
        "rangeComparisonType" : "FLOAT",
        "sourcePropertyNames" : [ "sku.activePrice" ]
}

Next, create the associated ranged values by issuing a POST request to the Facets endpoint:

POST /gsdata/v1/cloud/facets/Price
{
  "items": [
    {
      "displayName": "$0 - $25",
      "priceGroup" : "defaultPriceGroup",
      "displayOrder": "1",
      "key" : "0-25",
      "lowerBound" : "0.00",
      "upperBound" : "25.00"
    },
    {
      "displayName": "$25 - $50",
      "priceGroup" : "defaultPriceGroup",
      "displayOrder": "2",
      "key" : "25-50",
      "lowerBound" : "25.00",
      "upperBound" : "50.00"
    },
   {
      "displayName": "$50 - $100",
      "priceGroup" : "defaultPriceGroup",
      "displayOrder": "3",
      "key" : "50-100",
      "lowerBound" : "50.00",
      "upperBound" : "100.00"
    },
   {
      "displayName": "$100+",
      "priceGroup" : "defaultPriceGroup",
      "displayOrder": "4",
      "key" : "over100",
      "lowerBound" : "100.00",
      "upperBound" : "999999.00"
    },
    {
      "record.action": "OCCForceFlush"
    }
  ]
}

Finally, initiate an indexing operation, either by triggering a publish event, or by calling the index endpoint. The following code sample performs incremental indexing:

POST /ccadmin/v1/search/index { “op”: “partial” }

Once the indexing operation is complete, the new facet will be returned in the response.

Understand Price Navigation

Price properties in search, such as sku.activePrice and product.listPrice, are assigned dynamically, based on the relevant price group. If your site uses multiple price groups, either the default price group or a non-default price group will be dynamically assigned for the current shopper, and all price properties in search will contain the values for products and SKUs based on that price group.

For price navigation, you can assign each custom price range facet to only one price group. If your site has many price groups, a better approach is to use the range filter parameter Nf and let shoppers specify the minimum and maximum price directly, using a slider, text boxes, or From and To dropdowns, then use a range filter to restrict the products by price. For example: Nf=sku.activePrice|BTWN+100+200.