---
title: "Faceted Search"
slug: "smart-facetted-search-top-items-retrieval"
description: "Get personalized Mapp Fashion recommendations for product listing pages with filters, facet counts and pagination, via the Smart Pixel or the v2 API."
status: "update"
updated: 2026-10-16T11:06:59Z
published: 2026-10-16T11:06:59Z
canonical: "docs.mapp.com/smart-facetted-search-top-items-retrieval"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Faceted Search

Faceted Search returns Mapp Fashion recommendations for product listing pages and other browsing pages. You narrow the results with filters, request counts per filter value to build a filter navigation, and load the results page by page.

---

## Key Facts

- The call only retrieves recommendations. Interactions are tracked separately with [Recommendation Tracking](/v1/docs/recommendation-tracking-fashion).
- Results are personalized if the shopper is known. Otherwise, generally relevant products are returned.
- Filters of different names are combined with AND. Values within one filter are combined with OR.
- The endpoint path uses the spelling `facetted`.

---

## Request

### JavaScript

```javascript
wtSmart.extension.fashion.call("facetted", "search", {
  filters: {
    garment_category: ["1"],
    brand: ["BRAND_ID_1", "BRAND_ID_2"],
    min_price: 20,
    max_price: 80,
  },
  aggregations: [
    { name: "brand", size: 10 },
    { name: "price", ranges: [{ to: 50 }, { from: 50, to: 100 }, { from: 100 }] },
  ],
  department: "female",
  per_page: 24,
  onSuccess: (data) => {},
  onFailure: (err) => {},
});
```

### HTTP

```bash
POST https://api.your-domain.com/api/v2/facetted?department=female&per_page=24&garment_format=detailed
Content-Type: application/json

{
  "filters": {
    "garment_category": ["1"],
    "brand": ["BRAND_ID_1", "BRAND_ID_2"],
    "min_price": 20,
    "max_price": 80
  },
  "aggregations": [
    { "name": "brand", "size": 10 },
    { "name": "price", "ranges": [{ "to": 50 }, { "from": 50, "to": 100 }, { "from": 100 }] }
  ]
}
```

Over HTTP, `filters`, `aggregations` and `root_event_id` are sent in the request body. All other parameters are query parameters. In the JavaScript client library, all of them are properties of the call.

The v1 endpoint `/api/recommendations/facetted` remains available with its previous request format. For new integrations, use v2.

---

## Filters

Pass filters in `filters`, keyed by filter name. Without filters, the call returns the default ranked list for the department.

| Filter | Values | Description |
| --- | --- | --- |
| `garment_category` | List of category IDs, for example `["1"]` | Mapp Fashion garment categories, for example `1` for dresses. Use the IDs from the `garment_category` facet. Other values are refused. |
| `brand` | List of IDs | Brands. Use the IDs from the `brand` facet. |
| `occasion` | List of IDs | Occasions. Use the IDs from the `occasion` facet. |
| `season` | List, for example `["aw_2025"]` | Seasons, written as `ss_` or `aw_` followed by the year. Other values are refused. |
| `retailer_labels` | List of values | Values of product feed fields that Mapp indexes for you. Which fields are used is agreed with Mapp in advance. |
| `store` | List of IDs | Stores. Use the IDs from the `store` facet. Only works if Mapp receives availability data per store. |
| `product_ids` | List of Style IDs, at most `per_page` values | Restricts the results to these products. |
| `feature_ids` | List of IDs | Mapp Fashion feature IDs. Items must have at least one of them. |
| `not_feature_ids` | List of IDs | Mapp Fashion feature IDs to exclude. Items with any of them are not returned. |
| `min_price` | Number | Lowest price, inclusive. |
| `max_price` | Number | Highest price, exclusive. |
| `reduced_by` | Object with `from` and/or `to`, for example `{ from: 30 }` | Discount range in percent, both endpoints inclusive. `0` means not reduced, so `{ from: 30 }` returns items reduced by at least 30%. |

---

## Facet Counts

To build a filter navigation, list the facets you need in `aggregations`. For each facet, the response contains buckets with a count. The count shows how many results the same request would return if it were also filtered by that bucket.

| Property | Description |
| --- | --- |
| `name` | Facet to count: `garment_category`, `brand`, `occasion`, `season`, `retailer_labels`, `store`, `price`. |
| `size` | Maximum number of buckets. Not available for `price`. |
| `ranges` | Only for `price`: list of price ranges, each with `from` (inclusive) and/or `to` (exclusive). Leave one out for an open-ended range. One bucket is returned per range. |

`reduced_by`, `product_ids`, `feature_ids`, `not_feature_ids` can only be used as filters, not as facets.

---

## Pagination

Set the page size with `per_page` and the page with `page`. For the second and every later page, also pass the ID of the first response as `root_event_id`: `response_id` in the JavaScript client library, `event_id` over HTTP.

```javascript
wtSmart.extension.fashion.call("facetted", "search", {
  filters: { garment_category: ["1"] },
  per_page: 24,
  page: 2,
  root_event_id: firstPage.response_id,
  onSuccess: (data) => {},
  onFailure: (err) => {},
});
```

---

## Request Parameters

| Parameter | Over HTTP | Values and default | Description |
| --- | --- | --- | --- |
| `filters` | Body | Object | Filters, see Filters above. |
| `aggregations` | Body | List | Facets to count, see Facet Counts above. |
| `root_event_id` | Body | String | ID of the first response. Required from the second page on. |
| `page` | Query parameter | 1 to 100, default 1 | Page to return. |
| `per_page` | Query parameter | 1 to 500, default 12 | Number of results per page. |
| `department` | Query parameter | `female` (default), `male`, `girls`, `boys`, `unisex` | Department the results are drawn from. |
| `garment_format` | Query parameter | `simple`, `detailed` | Format of the returned item data. The default is `simple` over HTTP and `detailed` in the JavaScript client library. |
| `include_fashion_ids` | Query parameter | Boolean, default `false` | Whether the internal Mapp Fashion ID is returned for each item. In the `simple` format, [Recommendation Tracking](/v1/docs/recommendation-tracking-fashion) needs it. |
| `locale` | Query parameter | String, for example `en_GB` | Locale for stock information, prices and currency, if provided in the feed. |
| `language` | Query parameter | String, for example `en` | Language for product texts such as the name, if it should differ from the locale. |
| `onSuccess`, `onFailure` | JavaScript only | Callback | Called with the response data or when the request fails. |

---

## Response

### JavaScript Client Library

| Property | Description |
| --- | --- |
| `response_id` | ID of the response. Use it as `root_event_id` for further pages and in [Recommendation Tracking](/v1/docs/recommendation-tracking-fashion). |
| `content_id` | ID of this page of results. Needed for [Recommendation Tracking](/v1/docs/recommendation-tracking-fashion). |
| `currency` | Currency of the prices, derived from `locale`. `null` if your product data contains no currency. |
| `items` | Recommended items in ranked order. The items have the same format as in [Recommendation Items](/v1/docs/mapp-fashion-recommendation-items#response). |
| `facets` | One entry per requested facet, with `name` and `buckets`. Each bucket has a `count` and either `id` and `name` or, for `price`, `from` and `to`. |
| `pagination` | `current_page`, `last_page` (number of pages) and `total_items`. |

```json
{
  "response_id": "6a959a3a5e29c89df1d8ddbe",
  "content_id": "6a959a3b5e29c89df1d8ddbf",
  "currency": "GBP",
  "items": [
    {
      "dressipi_item_id": 5307387,
      "style_id": "TKBETTY-BLACK",
      "name": "Merino Wool Jumper",
      "price": "49.99"
    }
  ],
  "facets": [
    {
      "name": "brand",
      "buckets": [{ "id": "BRAND_ID_1", "name": "Some Brand", "count": 42 }]
    },
    {
      "name": "price",
      "buckets": [{ "to": 50, "count": 120 }, { "from": 50, "to": 100, "count": 64 }]
    }
  ],
  "pagination": { "current_page": 1, "last_page": 40, "total_items": 960 }
}
```

The example shows only some of the item fields.

### HTTP

The HTTP response contains `event_id`, `currency`, `facets`, `pagination` and `recommendations`. `recommendations` holds the `content_id` and the `items`. Each item contains `garment_id` (Style ID), `product_code`, `product_id` (Product ID), `ancillary_product_code`, `available_skus` with the in-stock Variant IDs and, with `include_fashion_ids=true`, `raw_garment_id`. In the `detailed` format, the product data is returned in `garment_data`. `pagination` contains `current_page`, `total_pages` and `total_entries`. For the full schema, see the [Mapp Fashion API](/v1/apidocs/mapp-fashion-api-documentation).

---

## Changes to the Previous Request Format

Since the October 2026 update of the Mapp Fashion extension, the JavaScript call uses the v2 endpoint and a new request format. The update is loaded automatically. If your implementation passes a `facets` list, change it as follows:

- `facets` is replaced by `filters`, an object keyed by filter name, and `aggregations`, the list of facets to count.
- Price ranges are filtered with `min_price` and `max_price` and counted with a `price` facet.
- `not_features_ids` is now called `not_feature_ids`.
- `must_have` is no longer available. `season` is new.

Direct HTTP requests to the v1 endpoint `/api/recommendations/facetted` are not affected. If you switch them to `/api/v2/facetted`, apply the same changes. v2 no longer accepts `canonical_only`, `fields`, `device_type` and returns `content_id` inside `recommendations`.