Facet Configuration

Facets (also known as filters) refer to the options often provided to the left of search results, which allow users to narrow their result set along common product attributes, such as the items' price or brand.

The facets API is used to configure display and sort options for facets. For example you can set a display name, control sort order, define how numeric ranges should be returned and more.

Keys, values, groups and options

Facet configurations are represented with two related concepts: Facet groups and facet options. Facet groups represent the facet key and facet options represent the facet value. For example, imagining an item with Brand: Nike, brand would be the facet group (or key), while nike would represent the facet option (or value).

Facets don't need to exist in product data to be configured

To allow for creating facet configurations in advance of uploading products referencing these facet configurations, facet configurations can be defined for facet groups and facet options that don't yet exist in the database.

While this behavior isn't yet supported in the customer dashboard, it is supported in the API.

Facets don't require configuration to be displayed

Facets are displayed automatically if they exist for items you've uploaded to your catalog. No configuration is necessary to get them to appear.

Facets are referenced by their value in your catalog

Facets are referenced by the key and value you associate with the items you upload in your catalog via API or feed in the facets object described in the Items documentation.

Protected and hidden facets

Product catalogs often include facets you don't want to display to end users. These may be old, unused, confusing to users or sensitive. Consider a few cases to understand.

Protected Facets The business team wants to incorporate inventory and margins in the ranking formula and in the merchant tools dashboard. However, this is sensitive data: Not only do we want to hide inventory and margins from end users, we also want to prevent them from being displayed for search requests without authentication. We can set the protected: true attribute to facilitate this.

Hidden Facets Other times, a merchant team will want to use an attribute to define merchandizing goals. We don't want to show it to end users, but it's not a problem if it could conceivably be accessed from the API. Imagine there's a season property on items that is used to define a Collection, or that there are some unused facets we don't want to show any more. We can set the hidden: true attribute to facilitate this case.

Special facets

Each item in the product catalog will automatically get an age facet associated with it. Its configuration is similar to any other facet, except for the type field (should always be range), and name field (should always be __cnstrc_age).

Create a facet config

To create a configuration for a facet, use the POST method.

Shell

Create a facet configuration

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "brand_facet", "display_name": "Brand", "sort_order": "relevance", "type": "multiple", "match_type": "all", "hidden": false, "enable_nlp": false, "data": {"config_key": "config_val"}, "options": [{"value": "nature_valley", "display_name": "Nature Valley", "position": 1, "data": null, "hidden": false}]}'
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]"

JavaScript

// Node
// Please refer to https://Krestor-io.github.io/Krestorio-node/module-catalog.html#~addFacetConfiguration

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

Response

{
  "name": "brand_facet",
  "display_name": "Brand",
  "sort_order": "relevance",
  "sort_descending": false,
  "type": "multiple",
  "range_type": null,
  "range_format": null,
  "range_inclusive": null,
  "bucket_size": null,
  "range_limits": null,
  "match_type": "all",
  "position": null,
  "hidden": false,
  "protected": false,
  "data": {
    "config_key": "config_val"
  },
  "options": [
    {
      "value": "nature_valley",
      "display_name": "Nature Valley",
      "position": 1,
      "data": null,
      "hidden": false
    }
  ]
}

HTTP request

POST https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]

URL Parameters

Attribute	Type	Required?	Description
section	string	No	The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

Attribute	Type	Required?	Description
name	string	Yes	The facet name used to refer to the facet in your catalog - whether your feed or API updates. Must be unique inside the section and key.
display_name	string	No	The name of the facet to present to end users. Default value is null, in which case the name will be presented.
sort_order	string	No	Determines the default criterion by which options of this facet group are sorted. Must be one of relevance, value (to sort facet options alpha-numerically), num_matches (to sort facet options by number of matching results). Default value is relevance. Sort can be overridden by setting the position attribute on facet options.
sort_descending	boolean	No	true if this facet group's options should be sorted in descending order, false to sort ascending. Default value is true if sort_order is relevance or num_matches and false for value. Setting sort_order: relevance will set sort_descending: true for POST, PUT, PATCH endpoints if sort_descending is not explicitly set in the request.
type	string	Yes	Type of facet. One of multiple or range. Use multiple to display the facet as categorical values (for example, a Brand facet with values of Nike, Adidas and Puma)and range to display as a numeric range. You must use range when you want to display a slider, as well as when you want to display a list of range buckets.
range_type	string	Required if facet type is range and range_format is options (i.e: range buckets). Not required otherwise.	Specifies whether the range buckets are determined dynamically (based on the values of matching facet options) or statically. One of dynamic, static. If the facet is not configured as a range, value will be null. Default value is null.
range_format	string	Required for type range, not required otherwise.	Format of range facets. Determines whether the facet is configured to display as a slider (in which case the search endpoint will return only min & max values) or as a list of buckets. One of boundaries (for sliders), options (for buckets). Default value is null.
range_inclusive	string	No	Used to create inclusive buckets. For example, for a rating facet, you might want to display options like 1 and above, 2 and above, 3 and above, etc. Values can be either above (options have no upper bound), below (options have no lower bound), or null if range options should not be inclusive. Default value is null
bucket_size	float	Either this or range_limits are required for facet type range, format options and range_type static.	Specifies the size of generated range buckets (e.g a bucket_size of 10 could generate buckets like 0-10, 10-20, 20-30, etc). Default value is null
range_limits	json	Either this or bucket_size are required for facet type range, format options and range_type static.	Defines the cut-off points for generating static range buckets. Expects list of sorted numbers (like [10, 25, 40]). Default value is null
match_type	string	No	Match types specify the behavior of filters when multiple options of the same facet (e.g: color: yellow & blue) are selected. Specifies whether the results must match all options, any of them or none. One of any, all, none. Default value is any.
position	integer	No	Used to slot facet groups to fixed positions. Default value is null.
hidden	boolean	No	Specifies whether the facet is hidden from users. Use this for facet data that you don't want shown to end users, but that isn't sensitive. Default value is false.
protected	boolean	No	Specifies whether the facet is protected from users. Setting this to true will require authentication to view the facet. Default value is false.
options	list of Facet options	No	List of facet option configurations to create and associate with this facet group. Default value is [] (empty list)
data	dict	No	Dictionary with any extra facet data. Default value is {} (empty dictionary)

Get all facet configs

To retrieve all facet configurations, use the GET method.

Shell

Get facets

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet groups per page]"

JavaScript

// Node
// Please refer to https://Krestor-io.github.io/Krestorio-node/module-catalog.html#~getFacetConfigurations

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

Response

{
    "facets": [
        {
            "name": "brand_facet",
            "display_name": "Brand",
            "sort_order": "relevance",
            "sort_descending": false,
            "type": "multiple",
            "range_type": null,
            "range_format": null,
            "range_inclusive": null,
            "bucket_size": null,
            "range_limits": null,
            "match_type": "any",
            "position": null,
            "hidden": false,
            "protected": false,
            "data": {}
        },
        {
            "name": "price_facet",
            "display_name": "Price",
            "sort_order": "relevance",
            "sort_descending": false,
            "type": "range",
            "range_type": "dynamic",
            "range_format": "boundaries",
            "range_inclusive": null,
            "bucket_size": null,
            "range_limits": null,
            "match_type": "any",
            "position": null,
            "hidden": false,
            "protected": false,
            "data": {}
        },
        ...
    ],
    "total_count": 10
}

HTTP request

GET https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet groups per page]

URL Parameters

Attribute	Type	Required?	Description
section	string	No	The section in which your facet is defined. Typically, this will be Products.
page	integer	No	The page number of the results. Defaults to 1. Can't be used together with 'offset'
offset	integer	No	The number of results to skip from the beginning. Can't be used together with 'page'
num_results_per_page	integer	No	The number of facets per page to return. Defaults to 100.

Get a single facet's config

To retrieve a single facet group's configuration, use the GET method.

Shell

Get facet

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

JavaScript

// Node
// Please refer to https://Krestor-io.github.io/Krestorio-node/module-catalog.html#~getFacetConfiguration

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

Response

{
    "name": "brand_facet",
    "display_name": "Brand",
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "any",
    "position": null,
    "hidden": false,
    "protected": false,
    "data": {},
    "options": [
        {
            "value": "mccormicks-organics",
            "display_name": "McCormick's Organics",
            "position": 1,
            "data": null,
            "hidden": false
        },
        {
            "value": "nature-valley",
            "display_name": "Nature Valley",
            "position": 2,
            "data": null,
            "hidden": false
        },
        ...
    ]
}

HTTP request

GET https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute	Type	Required?	Description
section	string	No	The section in which your facet is defined. Typically, this will be Products.

Update facet configs (partial)

To update multiple facet configurations partially at once, use the PATCH method.

This will avoid overwriting configurations and should be used if you only want to update configurations for a few fields in a facet group configuration.

Shell

Batch update facets

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '[{"name": "brand_facet", "display_name": "Brand"}, {"name": "color_facet", "hidden": true, "position": 1}]'
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]"

JavaScript

// Node
// Please refer to https://Krestor-io.github.io/Krestorio-node/module-catalog.html#~modifyFacetConfigurations

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

info

The API (without specifying a facet_group_name) accepts a list of facet configurations in the body of the request. If you're submitting a single facet configuration, you will have to wrap it in an array before making that request.

JSON Specifications

Example JSON

[
  {
    "name": "brand_facet",
    "display_name": "Brand",
    "hidden": true
  },
  {
    "name": "color_facet",
    "display_name": "Color",
    "position": 2
  }
]

Example Response

[
  {
    "name": "brand_facet",
    "display_name": "Brand",
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "all",
    "position": null,
    "hidden": false,
    "protected": false,
    "data": {}
  },
  {
    "name": "color_facet",
    "display_name": "Color",
    "sort_order": "relevance",
    "sort_descending": false,
    "type": "multiple",
    "range_type": null,
    "range_format": null,
    "range_inclusive": null,
    "bucket_size": null,
    "range_limits": null,
    "match_type": "all",
    "position": 1,
    "hidden": true,
    "protected": false,
    "data": {}
  }
]

HTTP request

PATCH https://ac.cnstrc.com/v1/facets?key=[your API key]&section=[your section]

URL Parameters

Attribute	Type	Required?	Description
section	string	No	The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

Batch update endpoint expects a list of item updates. Each item parameters can be any subset of those listed in the Create a facet configuration section, except that options parameter is not allowed and name parameter is required (to identify which facets to update).

Update a facet config (total)

To update the configuration of a facet completely (replace), use the PUT method.

caution

This will overwrite all other configurations you may have defined for the facet group, resetting them to their defaults. This includes all facet option configurations you may have defined.

Shell

Replace facet

curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "some name", "type": "multiple", "hidden": true}' \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

JavaScript

// Node
// Please refer to https://Krestor-io.github.io/Krestorio-node/module-catalog.html#~replaceFacetConfiguration

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

JSON Specifications

Example JSON

{
  "name": "some name",
  "display_name": "Some Name",
  "hidden": true,
  "type": "multiple"
}

Example Response

{
  "name": "some name",
  "display_name": null,
  "sort_order": "relevance",
  "sort_descending": false,
  "type": "multiple",
  "range_type": null,
  "range_format": null,
  "range_inclusive": null,
  "bucket_size": null,
  "range_limits": null,
  "match_type": "any",
  "position": null,
  "hidden": true,
  "protected": false,
  "data": {},
  "options": []
}

HTTP request

PUT https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute	Type	Required?	Description
section	string	No	The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters are the same as those in the Create a facet configuration section

Update a facet config (partial)

To update the configuration of a facet partially (change only some attributes), use the PATCH method.

Shell

Modify facet

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"match_type": "any"}' \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

JavaScript

// This method is not currently supported.

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

JSON Specifications

Example JSON

{
  "match_type": "any"
}

Example Response

{
  "name": "brand_facet",
  "display_name": "Brand",
  "sort_order": "relevance",
  "sort_descending": false,
  "type": "multiple",
  "range_type": null,
  "range_format": null,
  "range_inclusive": null,
  "bucket_size": null,
  "range_limits": null,
  "match_type": "any",
  "position": null,
  "hidden": false,
  "protected": false,
  "data": {},
  "options": [
    {
      "value": "nature_valley",
      "display_name": "Nature Valley",
      "position": 1,
      "data": null,
      "hidden": false
    }
  ]
}

HTTP request

PATCH https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute	Type	Required?	Description
section	string	No	The section in which your facet is defined. Typically, this will be Products.

JSON Parameters

The JSON parameters can be any subset of those listed in the Create a facet configuration section

Delete a facet config

To delete the configuration of a facet use the DELETE method. This does not delete the facet from items in your index you may have uploaded previously - if you wish to stop showing a facet to a user, configure it as hidden.

caution

Once a facet group's configuration is deleted, all configurations will return to their default values. This includes all facet option configurations (display name, position, etc) you may have defined for the facet group.

Shell

Delete a facet configuration

curl -X DELETE \
  -H "Content-Type: application/json" \
  -u "[your token]"
  "https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"

JavaScript

// Node
// Please refer to https://Krestor-io.github.io/Krestorio-node/module-catalog.html#~removeFacetConfiguration

Python

# This method is not currently supported.

Java

// This method is not currently supported.

iOS

// This method is not currently supported.

Android

// This method is not currently supported.

C#

// This method is not currently supported.

Response

{
  "name": "brand_facet",
  "display_name": "Brand",
  "sort_order": "relevance",
  "sort_descending": false,
  "type": "multiple",
  "range_type": null,
  "range_format": null,
  "range_inclusive": null,
  "bucket_size": null,
  "range_limits": null,
  "match_type": "all",
  "position": null,
  "hidden": false,
  "protected": false,
  "data": {},
  "options": [
    {
      "value": "nature_valley",
      "display_name": "Nature Valley",
      "position": 1,
      "data": null,
      "hidden": false
    }
  ]
}

HTTP request

DELETE https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]

URL Parameters

Attribute	Type	Required?	Description
section	string	No	The section in which your facet is defined. Typically, this will be Products.

Facet config examples

The following examples on the right side describe facet configuration requests you'd make (per Create a facet configuration) to fulfill different use-cases.

Brand facet with alphabetically sorted options and display name configuration for 3 facet options.

{
    "name": "brand",
    "display_name": "Brand",
    "sort_order": "value",
    "type": "multiple",
    "data": {},
    "options": [
        {
            "value": "nike",
            "display_name": "Nike"
        },
        {
            "value": "adidas",
            "display_name": "Adidas"
        },
        {
            "value": "under_armor"
            "display_name": "Under Armor"
        }
    ]
}

Price facet configured to be returned as a slider, allowing filtering of products by a price between two values.

{
  "name": "price",
  "display_name": "Price",
  "type": "range",
  "range_format": "boundaries"
}

Price facet as a list of buckets of size 100, allowing you to create a filter as a list of price buckets, like $0-100, $100-200, etc.

{
  "name": "Price",
  "type": "range",
  "range_type": "static",
  "range_format": "options",
  "bucket_size": 100
}

Rating facet with overlapping buckets, for instance if you want to create a rating filter with options

{
  "name": "Rating",
  "type": "range",
  "range_type": "static",
  "range_format": "options",
  "range_inclusive": "above",
  "range_limits": [1, 2, 3, 4]
}