Facets

How to get attribute groups (facets) back with a result.

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"]}'\
    http://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.