Faceted Search

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

POST /api/recommendations/facetted?per_page=10&page=2&garment_format=detailed

Parameters

Post Body (Facets)

Single Filter Facet

{
  "name": "brand",
  "value": ["Nike", "Adidas"]
}

Multi Filter Facet

{
  "name": "price",
  "filters": [
    { "from": 20, "to": 50 },
    { "from": 70 }
  ]
}

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.

{
  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)

Pagination Metadata

DetailedItem