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:

EntryTypeValue
typestrThe type of this facet. This is always unit.
namestrThe name of this facets to be displayed.
valuestr or intThe 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.
countintThe 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:

EntryTypeValue
typestrThe type of this facet. This ia always range.
namestrThe name of this facet. This is generated dynamically based on the min and max within the range.
minfloatThe smallest value in the rage.
maxfloatThe largest value in the range.
countintThe number of results having a attribute value within this range.