--- title: "Faceted Search (Standalone)" slug: "mapp-fashion-faceted-search-standalone" updated: 2025-10-28T13:38:40Z published: 2025-10-28T13:38:40Z canonical: "docs.mapp.com/mapp-fashion-faceted-search-standalone" --- > ## 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 (Standalone) ## Overview The facetted recommendations API allows you to retrieve the most recommended garments, filtered and refined by various dimensions (facets). It supports both single and multiple filters, range queries, and pagination. The API can also return metadata about hits for other filter values (facetted counts), making it suitable for building guided product discovery experiences. --- ## Filter Dimensions / Aggregations The following dimensions are supported (sometimes called *aggregations* or *filter dimensions*): - `garment_category` - `brand` - `occasion` - `must_have` - `retailer_labels`: Depends on the data present in the product feed. The `retailer_labels` aggregation allows you to query against fields in the product feed consumed (these should be agreed with Mapp). - `store`: If Mapp has been provided with per-store availability data, this filters or aggregates on availability by store - `feature_ids`: Mapp Fashion feature IDs - `not_features_ids`: Exclude results with these feature IDs. - `price`: supports ranges - `reduced_by`: Percentage discount filter (0–100). --- ## Making Requests #### Endpoint ```bash POST /api/recommendations/facetted?per_page=10&page=2&garment_format=detailed ``` #### Parameters | Key | Required | Description | | --- | --- | --- | | `page` | Optional | Page number for pagination | | `per_page` | Optional | Number of results per page | | `variation` | Optional | Test/experiment variation | | `garment_format` | Fixed | Hardcoded to `detailed` (no need to set manually) | --- ## Post Body (Facets) #### Single Filter Facet ```json {  "name": "brand",  "value": ["Nike", "Adidas"] } ``` | Field | Type | Description | | --- | --- | --- | | `name` | Dimension | The dimension being filtered | | `value` | Array | Array of allowed values | #### Multi Filter Facet ```json {  "name": "price",  "filters": [    { "from": 20, "to": 50 },    { "from": 70 }  ] } ``` | Field | Type | Description | | --- | --- | --- | | `name` | Dimension | The dimension being filtered | | `filters` | Array | List of value or range filters (e.g., multiple price ranges) | #### Example Request ```javascript Dressipi("facetted", "search", {  facets: [    {      name: "retailer_labels", // these should be aggreed with Mapp ahead of time      value: ["Womenswear > Dresses"]    },    {      name: "feature_ids", // these are Mapp Fashion feature ids      filters: [        {"value": [1,2]},        {"value": [3,4]}      ]    },    {      name: "price",      filters: [        {          from: 50,          to: 100        }      ],      ranges: [ // alternatively, multiple ranges can be present as follows:        {to: 50},        {from: 50, to: 100},        {from: 100}      ]    }  ],  placement_id: "A_UUID_PROVIDED_BY_MAPP",  onSuccess: (data) => {  },  onFailure: (err) => {}, }); ``` --- ## Response Structure #### High-level Example Here's an example of the data you'll receive in the `onSuccess` callback. You should ignore fields not specified below. ```json {  recommendations: [    {      // this is the the retailer identifier for this item      id: "TKBETTYMERINOWOOLBlackBlack",            // this is the Mapp Fashion identifier for this item      dressipi_item_id: 5307387,    },    ...  ],  pagination: {    total_pages: 80,    total_items: 960,    current_page: 1  } } ``` --- #### Detailed Response (FacettedResponse) | Field | Type | Description | | --- | --- | --- | | `response_id` | String | Unique ID for the request | | `content_id` | String | Tracking ID for context/content | | `items` | Array | List of recommended items | | `pagination` | Object | Pagination metadata | | `event_id` | String | Present only in raw response | --- #### Pagination Metadata | Field | Type | Description | | --- | --- | --- | | `last_page` | Number | Total number of pages | | `current_page` | Number | Current page number | | `total_items` | Number | Total number of available items | --- #### DetailedItem | Field | Type | Description | | --- | --- | --- | | `id` | String | External item ID (retailer identifier) | | `dressipi_item_id` | Number | Internal Mapp Fashion item ID | | `name` | String | Product name | | `brand_name` | String | Brand name | | `url` | String | Product URL | | `images` | String | An array of image URLs | | `image_url` | String | Primary image URL | | `has_outfits` | Boolean | Indicates if the item has outfit associations | | `status` | String | in stock / out of stock | | `price` | String | Current price | | `old_price` | String | Previous price (if discounted) |