> ## 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.

# return themed recommendations for a user

> The themed recommendations api allows retrieval of the most recommended garments for a user matching a theme.
Themes should be agreed in advance with Mapp Fashion.

This is the api equivalent of the plp widget.


## OpenAPI

````json GET /recommendations/themed
{
  "openapi": "3.0.4",
  "info": {
    "title": "Mapp Fashion API",
    "description": "Mapp Fashion recommendation API.\n\n**Host:** there is no shared API host. A dedicated host is configured per partner and supplied during onboarding. All paths below are relative to that host.\n\nTwo versions are available in parallel. **v1** (`/api/...`) covers the established endpoints and is fully maintained, with no deprecation planned. **v2** (`/api/v2/...`) standardizes the inputs and provides one endpoint per recommendation type. New integrations should use v2 wherever a v2 endpoint exists. See Recommendation Strategy for which endpoint to use when.\n",
    "version": "13"
  },
  "servers": [
    {
      "url": "/api"
    }
  ],
  "security": [
    {
      "api_key": []
    },
    {
      "api_key": [],
      "user_token": []
    }
  ],
  "tags": [
    {
      "name": "Items",
      "description": "Operations for retrieving recommendations or items related to one or more seed items"
    },
    {
      "name": "Items (v2)",
      "description": "v2: one endpoint per recommendation type, identifiers passed as parameters"
    },
    {
      "name": "Recommendations",
      "description": "Operations about recommendations"
    },
    {
      "name": "Recommendations (v2)",
      "description": "v2: facetted recommendations in the v2 response format"
    },
    {
      "name": "Authorization",
      "description": "Operations for obtaining or refreshing JWTs"
    }
  ],
  "paths": {
    "/recommendations/themed": {
      "get": {
        "tags": [
          "Recommendations"
        ],
        "summary": "return themed recommendations for a user",
        "description": "The themed recommendations api allows retrieval of the most recommended garments for a user matching a theme.\nThemes should be agreed in advance with Mapp Fashion.\n\nThis is the api equivalent of the plp widget.\n",
        "operationId": "getRecommendationsThemed",
        "parameters": [
          {
            "name": "garment_format",
            "in": "query",
            "description": "The desired response format.\n\nThe response includes a description of the outfits / similar items but no data on the items themselves: since these may be repeated within the response, garment data is provided separately in the response.\n\nThe `detailed` format includes the most amount of item metadata (name, description, price etc).\n\nThe `document` format only includes item identifiers, and if requested Mapp Fashion generated information about the item, such as predicted size.\n\nThe `retailer_ids` format only returns the item identifiers.\n",
            "schema": {
              "enum": [
                "detailed",
                "document",
                "retailer_ids"
              ],
              "type": "string",
              "default": "retailer_ids"
            }
          },
          {
            "name": "pretty",
            "in": "query",
            "description": "If true, pretty print JSON output. This increases response size and should usually be off in production environments\n",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_dressipi_ids",
            "in": "query",
            "description": "Controls whether Mapp Fashion garment ids (raw_garment_id) are included in response\n",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "device_type",
            "in": "query",
            "description": "A device type identifier. This allows segmenting a/b test statistics\nin the same way as you do.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "locale",
            "in": "query",
            "description": "A locale parameter describing what stock information to use and what language to return text in (if applicable). This parameter will only\nfunction if the corresponding information is in your product data & processed accordingly. If stock local and UI language are not the same,\nspecify the language parameter in addition to this one.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "language",
            "in": "query",
            "description": "Allows you to specify a locale used for product attributes such as product name that should be localized using a different locale to price &\nstock information. This parameter will only function if the corresponding information is in your product data & processed accordingly.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "theme",
            "in": "query",
            "description": "The theme identifier, as agreed with Mapp Fashion.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "count",
            "in": "query",
            "description": "The number of recommendations to return",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 6
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Information about the related garments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThemedRecommendationsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidParams"
          },
          "403": {
            "$ref": "#/components/responses/InvalidJwt"
          },
          "422": {
            "description": "error message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ThemedRecommendationsResponse": {
        "required": [
          "event_id",
          "content_id",
          "recommendations"
        ],
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string",
            "description": "An event id. This should be used when posting events relating to this dataset.",
            "example": "5a621005c2c9adc12e1192b7"
          },
          "reparentable": {
            "type": "boolean",
            "description": "If true, the eventid should be posted to /events/{id}/reparent"
          },
          "content_id": {
            "type": "string",
            "description": "An opaque identifier identifying this section of the response. This should be used when posting events relating to an item in this outfit.",
            "example": "5a621005c2c9adc12e1192b7"
          },
          "recommendations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Garment"
            },
            "description": "The recommended items"
          },
          "invalid_theme": {
            "type": "boolean",
            "description": "If true, theme was not recognized"
          }
        },
        "description": "The themed recommendations api allows retrieval of the most recommended garments for a user matching a theme.\nThemes should be agreed in advance with Mapp Fashion.\n\nThis is the api equivalent of the plp widget.\n",
        "example": {
          "event_id": "5a621005c2c9adc12e1192b7",
          "reparentable": true,
          "content_id": "5a621005c2c9adc12e1192b7",
          "invalid_theme": false,
          "recommendations": [
            {
              "garment_id": "ABC-123",
              "raw_garment_id": 123456,
              "ancillary_product_code": "A-111",
              "garment_category_id": 42,
              "garment_category_name": "Dresses",
              "department": "female",
              "has_outfits": true,
              "has_extended_verdicts": true,
              "size": {
                "exact": [
                  "5",
                  "UK 10"
                ],
                "plus_one": [
                  "6",
                  "UK 12"
                ],
                "minus_one": [
                  "4",
                  "UK 8"
                ]
              },
              "verdict": true,
              "owned": false,
              "why": [
                "A neat slim leg flatters your slender shape",
                "A hint of flare helps to balance out your shoulders."
              ],
              "occasions": [
                "casual",
                "holiday"
              ],
              "recommendedness": {
                "score": 8,
                "reason": "Good for you"
              },
              "features": [
                {
                  "id": 1,
                  "name": "Basic",
                  "feature_category_name": "Wardrobe"
                },
                {
                  "id": 2,
                  "name": "A/W 2020",
                  "feature_category_name": "Season"
                }
              ],
              "feed_image_urls": [
                "https://assets.retailer.com/images/01AC017NAV",
                "https://assets.retailer.com/images/01AC017NAV"
              ],
              "eans": [
                "ABCD01",
                "ABCD02",
                "ABCD03"
              ],
              "brand_name": "Some Brand",
              "retailer": "Some Retailer",
              "name": "Black Maxi dress",
              "price": "35.00 GBP",
              "old_price": "35.00 GBP",
              "url": "https://www.someretailer.com/dresses/01AC017NAV",
              "garment_status": "in stock",
              "custom_attributes": [
                {
                  "name": "retailer_specific_attribute_1",
                  "value": "abcedfg",
                  "array_value": []
                }
              ]
            }
          ]
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "description": "A human readable error message"
              }
            }
          }
        },
        "description": "Generic error object"
      },
      "Garment": {
        "required": [
          "garment_id"
        ],
        "type": "object",
        "properties": {
          "garment_id": {
            "type": "string",
            "description": "The `garment_id`. The type of identifier used depends on the requests' `garment_format`",
            "example": "ABC-123"
          },
          "raw_garment_id": {
            "type": "integer",
            "description": "The internal Mapp Fashion id for the garment. This may be omitted depending on `garment_format`",
            "format": "int32",
            "example": 123456
          },
          "product_id": {
            "type": "string",
            "description": "The product level identifier the item belongs to (Product ID in the Product Catalog), grouping all its colors and sizes. Omitted if your product data contains no Product ID",
            "example": "TS30165"
          },
          "ancillary_product_code": {
            "type": "string",
            "description": "An alternative identifier to identify the product, hidden when not provided in your product data",
            "example": "A1B2C3"
          },
          "has_extended_verdicts": {
            "type": "boolean",
            "description": "Whether garment has extended verdicts. Only presents for verdicts/dislikes, also not present if format=retailer_ids",
            "example": true
          },
          "has_outfits": {
            "type": "boolean",
            "description": "Whether outfits can be generated. not present if format=retailer_ids"
          },
          "size": {
            "$ref": "#/components/schemas/Sizing"
          },
          "why": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "If whys have been requested & if the profile has shape data, a list of human readable reasons for recommendation"
          },
          "verdict": {
            "type": "boolean",
            "description": "If verdicts have been requested, the approval status of the garment (true=like, false=dislike, nil=no verdict given)"
          },
          "owned": {
            "type": "boolean",
            "description": "If owned has been requested, whether the use has previously purchased the product"
          },
          "recommendedness": {
            "$ref": "#/components/schemas/Recommendedness"
          },
          "features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BasicFeature"
            },
            "description": "If features have been requested, a list of whitelisted feature objects"
          },
          "garment_category_id": {
            "type": "integer",
            "description": "The category id for the product.",
            "format": "int32"
          },
          "department": {
            "type": "string",
            "description": "The garment department (female male girls boys)."
          },
          "eans": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "If eans have been requested, the array of eans present in your product data."
          },
          "garment_category_name": {
            "type": "string",
            "description": "The category name for the product."
          },
          "occasions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of the product occasions. Only present if format=detailed, and only populated when `occasions` is requested via `fields`; otherwise the key may be returned as null. The possible values are `casual`, `evening`, `occasion`, `holiday`, `work` and `creative_work`",
            "nullable": true
          },
          "retailer": {
            "type": "string",
            "description": "The retailer name for the product. Only present if format=detailed"
          },
          "feed_image_urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The array of image_urls present in your product data. Only present if format=detailed"
          },
          "brand_name": {
            "type": "string",
            "description": "The brand name for the product. Only present if format=detailed"
          },
          "name": {
            "type": "string",
            "description": "The product name. Only present if format=detailed"
          },
          "price": {
            "type": "string",
            "description": "The current price, as it appears in your product data. Only present if format=detailed"
          },
          "old_price": {
            "type": "string",
            "description": "The previous price, as it appears in your product data. Only present if format=detailed"
          },
          "url": {
            "type": "string",
            "description": "The URL for the PDP for the garment. Only present if format=detailed"
          },
          "garment_status": {
            "type": "string",
            "description": "The status of the garment. Only present if format=detailed"
          },
          "custom_attributes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomAttribute"
            },
            "description": "Product attributes, as agreed with Mapp Fashion"
          }
        },
        "description": "Fetches information about a garment. The garment format is implicitly set to detailed.\n",
        "example": {
          "garment_id": "01AC017NAV",
          "raw_garment_id": 4508067,
          "ancillary_product_code": "N-1-D-1111",
          "garment_category_id": 42,
          "garment_category_name": "Dresses",
          "department": "female",
          "has_outfits": true,
          "has_extended_verdicts": true,
          "size": {
            "exact": [
              "5",
              "UK 10"
            ],
            "plus_one": [
              "6",
              "UK 12"
            ],
            "minus_one": [
              "4",
              "UK 8"
            ]
          },
          "verdict": true,
          "owned": false,
          "why": [
            "A neat slim leg flatters your slender shape",
            "A hint of flare helps to balance out your shoulders."
          ],
          "occasions": [
            "casual",
            "holiday"
          ],
          "recommendedness": {
            "score": 8,
            "reason": "Good for you"
          },
          "eans": [
            "ABCD01",
            "ABCD02",
            "ABCD03"
          ],
          "features": [
            {
              "id": 1,
              "name": "Basic",
              "feature_category_name": "Wardrobe"
            },
            {
              "id": 2,
              "name": "A/W 2020",
              "feature_category_name": "Season"
            }
          ],
          "feed_image_urls": [
            "https://assets.retailer.com/images/01AC017NAV",
            "https://assets.retailer.com/images/01AC017NAV"
          ],
          "brand_name": "Some Brand",
          "retailer": "Some Retailer",
          "name": "Black Maxi dress",
          "price": "35.00 GBP",
          "old_price": "35.00 GBP",
          "url": "https://www.someretailer.com/dresses/01AC017NAV",
          "garment_status": "in stock",
          "custom_attributes": [
            {
              "name": "retailer_specific_attribute_1",
              "value": "abcedfg",
              "array_value": []
            }
          ]
        }
      },
      "Sizing": {
        "type": "object",
        "properties": {
          "exact": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Information about the recommended size"
          },
          "plus_one": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Information about size immediately bigger than the recommended one (if available)"
          },
          "minus_one": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Information about size immediately smaller than the recommended one (if available)"
          }
        }
      },
      "Recommendedness": {
        "type": "object",
        "properties": {
          "score": {
            "type": "integer",
            "description": "A numerical score for the garment (out of 10)",
            "format": "int32"
          },
          "reason": {
            "type": "string",
            "description": "A human readable interpretation of the score"
          }
        }
      },
      "BasicFeature": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The id for the feature",
            "format": "int32",
            "example": 170
          },
          "name": {
            "type": "string",
            "description": "The human readable name for the feature",
            "example": "Plain Pattern"
          },
          "feature_category_name": {
            "type": "string",
            "description": "The feature category of the feature",
            "example": "Pattern"
          }
        }
      },
      "CustomAttribute": {
        "required": [
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the attribute"
          },
          "value": {
            "type": "string",
            "description": "The value of the attribute (if string valued)"
          },
          "array_value": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The value of the attribute (if array valued)"
          }
        }
      }
    },
    "responses": {
      "InvalidParams": {
        "description": "One or more parameter values are invalid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InvalidJwt": {
        "description": "Invalid JWT: a user token was supplied but could not be verified. Requests without a user token are not affected - they return non-personalized results",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "An internal error occurred. Retry the request. If the issue persists, contact Technical Support",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
      },
      "user_token": {
        "type": "apiKey",
        "description": "The JWT for the user. Optional: requests without a user token return non-personalized results. The header name is unchanged for backwards compatibility.",
        "name": "x-dressipi-jwt",
        "in": "header"
      }
    }
  }
}
````