Facets

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 Add an Item 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.

Create a facet config#

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

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]"
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#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.

JSON Parameters#

AttributeTypeRequired?Description
namestringYesThe 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_namestringNoThe name of the facet to present to end users. Default value is null, in which case the name will be presented.
sort_orderstringNoDetermines 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 overriden by setting the position attribute on facet options.
sort_descendingbooleanNotrue 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 and false for other sort orders. Setting sort_order: relevance will set sort_descending: true for POST, PUT, PATCH endpoints if sort_descending is not explicitly set in the request.
typestringYesType 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_typestringRequired 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_formatstringRequired 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_inclusivestringNoUsed 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_sizefloatNo.Either this or range_limits are required for facet type range, format options and range_type staticSpecifies 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_limitsjsonNoEither this or bucket_size are required for facet type range, format options and range_type staticDefines the cut-off points for generating static range buckets. Expects list of sorted numbers (like [10, 25, 40]). Default value is null
match_typestringNoMatch 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.
positionintegerNoUsed to slot facet groups to fixed positions. Default value is null.
hiddenbooleanNoSpecifies 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.
protectedbooleanNoSpecifies whether the facet is protected from users. Setting this to true will require authentication to view the facet. Default value is false.
optionslist of Facet optionsNoList of facet option configurations to create and associate with this facet group. Default value is [] (empty list)
datadictNoDictionary with any extra facet data. Default value is {} (empty dictionary)

Get all facet configs#

To retrieve all facet configurations, use the GET method.

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]"
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#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.
pageintegerNoPage number you'd like to request. Defaults to 1.
num_results_per_pageintegerNoNumber of facets per page in paginated response. Default value is 100.

Get a single facet's config#

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

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]"
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#

AttributeTypeRequired?Description
sectionstringNoThe 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.

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]"
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#

AttributeTypeRequired?Description
sectionstringNoThe 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.

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]"
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#

AttributeTypeRequired?Description
sectionstringNoThe 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.

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]"
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#

AttributeTypeRequired?Description
sectionstringNoThe 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.

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]"
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#

AttributeTypeRequired?Description
sectionstringNoThe 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 "1 and above", "2 and above", "3 and above", etc.
{
"name": "Rating",
"type": "range",
"range_type": "static",
"range_format": "options",
"range_inclusive": "above",
"range_limits": [1, 2, 3, 4]
}