Facets

Facets are most known in searches to narrow down results to eg a single category, brand or price range but can be used with any API endpoint that takes the facets parameter.

To receive facets from an API request simply send a list of the attributes you want to receive facets for.

curl -X POST -H "Content-Type: application/json" \
    -d '{"query": "death star", "facets": ["categories", "brand", "price"]}'\
    https://api.clerk.io/v2/search/search?key=store_api_key

And then in the response, there will be a facets entry available along with the other response data.

"facets": {
  "price": [
    {
      "count": 7,
      "max": 74.99,
      "type": "range",
      "name": "50 - 74",
      "min": 50.0
    },
    {
      "count": 11,
      "max": 99.99,
      "type": "range",
      "name": "75 - 99",
      "min": 75.0
    },
    {
      "count": 2,
      "max": 180,
      "type": "range",
      "name": "150 <",
      "min": 149.99
    }
  ],
  "categories": [
    {
      "count": 14,
      "type": "unit",
      "name": "Deathstars",
      "value": 3517
    },
    {
      "count": 1,
      "type": "unit",
      "name": "Handy Emplire (TM)",
      "value": 3784
    },
    {
      "count": 1,
      "type": "unit",
      "name": "Scrap Offers",
      "value": 6187
    },
    {
      "count": 1,
      "type": "unit",
      "name": "On Sale",
      "value": 3791
    }
  ],
  "brand": [
    {
      "count": 14,
      "type": "unit",
      "name": "Empire (TM)",
      "value": "Empire (TM)"
    },
    {
      "count": 1,
      "type": "unit",
      "name": "Handy Emplire (TM)",
      "value": "Handy EMpire (TM)"
    }
  ]
}

Units

Facets come in two types unit and range. unit denotes a set of fixed values like a ID or a string (eg categories or brands).

{
  "count": 14,
  "type": "unit",
  "name": "Empire (TM)", 
  "value": 1234
}

{
  "count": 14,
  "type": "unit",
  "name": "Empire (TM)", 
  "value": "Empire (TM)"
}

A unit facets has 4 entries:

Entry	Type	Value
`type`	`str`	The type of this facet. This is always `unit`.
`name`	`str`	The name of this facets to be displayed.
`value`	`str` or `int`	The value of this facet. It is the same as `name` if the value does not reference a resource with a ID such as eg brands or sized. It will be the ID of the resource if it references another resource such as a category.
`count`	`int`	The number of products in the whole result having this attribute.

Range

Facets come in two types unit and range. range denotes a subset of values with a floating range such as a price.

Ranges are automatically grouped into dynamic sizes based on the min, max and spread of the values in the entire set.

[
  {
    "count": 11,
    "max": 99.99,
    "type": "range",
    "name": "75 - 99",
    "min": 75.0
  },
  {
    "count": 2,
    "max": 180,
    "type": "range",
    "name": "150 <",
    "min": 149.99
  }
]

A range facets has 5 entries:

Entry	Type	Value
`type`	`str`	The type of this facet. This ia always `range`.
`name`	`str`	The name of this facet. This is generated dynamically based on the min and max within the range.
`min`	`float`	The smallest value in the rage.
`max`	`float`	The largest value in the range.
`count`	`int`	The number of results having a attribute value within this range.