Filter names and values are key components used to narrow down a list of resources or items based on specific criteria. These may be used to refine the result set in responses from Constructor's API. For example, when utilizing the Browse Retrieve by filter name/value, both a filter name and value are provided in the path of the request to define the scope of the result set.

Filter names refer to attributes or characteristics of resources ingested by Constructor. There are two constant filter names: group_id and collection_id. Filter names can also refer to specific facet attributes uploaded within the product catalog.

group_id

When a group hierarchy is uploaded, each item record may be mapped to one or many group_ids. In order to return results only from a specific group, a filter name of group_id (a constant) can be provided, with the filter value being the ID of the group.

For instance, a product catalog has two groups defined: a shirts group (ID of shirts), and a pants group (ID of pants). A Browse request could be issued to return items that only belong to the pants group: /browse/group_id/pants.

collection_id

When Constructor's Collections product is being utilized, each created collection has a unique identifier. To return results from only a specific collection, a filter name of collection_id (a constant) can be provided, with the filter value being the ID of the collection.

For instance, a Collection has been defined with the ID of black-friday-sales which contains items that are on sale for this year's Black Friday event. A Browse request could be issued to return items that belong that collection: /browse/collection_id/black-friday-sales.

Facets

It is also possible to use any facet identifier as a filter name to refine a result set. In this case, the filter name would correspond to the identifier of the facet, where the value would correspond to the value that must be matched in order for items to be returned.

These dynamic filter names can be configured or modified as the catalog evolves. They are derived from the product data itself and are defined based on the facets configured in the system.

For instance, a catalog has a size facet defined with multiple values: small, medium and large. A Browse request could be issued to return only items that are of size small: /browse/size/small.

filters query parameter

Many API endpoints support a filters parameter, where filter names and values can be applied to further refine a result set. Any of the preceding facet name and value concepts can be utilized in this context. Consider the following examples:

Only return results that match the query "chinos" within the pants group

/search/chinos?filters[group_id]=pants

Only return results with a price between 50 and 100 from the black-friday-sales Collection

/browse/collection_id/black-friday-sales?filters[price]=0-50

Only return results that match the query "tire" that are available in store 131

/search/tire?filters[availability]=131