Perfume Picks

Full-text search across 13,000+ fragrances in the Perfume Picks database. Filter by brand, fragrance family, gender, and MSRP (USD). Returns note pyramids, accords, and community wear scores with source attribution.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 120,
      "description": "Free-text search: fragrance or brand name"
    },
    "brand": {
      "type": "string",
      "maxLength": 200,
      "description": "Brand name filter, e.g. 'Dior'"
    },
    "fragrance_family": {
      "type": "string",
      "maxLength": 120,
      "description": "Family filter, e.g. 'woody', 'amber', 'fresh'"
    },
    "gender": {
      "type": "string",
      "enum": [
        "masculine",
        "feminine",
        "unisex"
      ],
      "description": "Marketed gender category of the fragrance; omit to include all"
    },
    "price_min": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum MSRP in USD"
    },
    "price_max": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum MSRP in USD"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 10, max 10)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Detailed record for one fragrance: full note pyramid (top/heart/base), accords, concentration, community longevity/sillage/compliment scores, and MSRP. Accepts a Perfume Picks slug or a name like 'Bleu de Chanel'.

{
  "type": "object",
  "properties": {
    "slug_or_name": {
      "type": "string",
      "maxLength": 200,
      "description": "Fragrance slug or name"
    }
  },
  "required": [
    "slug_or_name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Curated dupes for a fragrance — cheaper scents documented to smell like the original, with match percentage and price comparison. The answer to 'what smells like X without the price tag'.

{
  "type": "object",
  "properties": {
    "fragrance": {
      "type": "string",
      "maxLength": 200,
      "description": "Fragrance slug or name to find dupes for"
    }
  },
  "required": [
    "fragrance"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fragrances most similar to a given one, from Perfume Picks' precomputed similarity ranking over notes and accords.

{
  "type": "object",
  "properties": {
    "fragrance": {
      "type": "string",
      "maxLength": 200,
      "description": "Fragrance slug or name"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 5)"
    }
  },
  "required": [
    "fragrance"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Personalized fragrance picks from note/accord preferences (e.g. 'vanilla', 'oud', 'citrus'), a budget in USD, an occasion ('office', 'date night', 'gift', 'signature scent'), and gender presentation.

{
  "type": "object",
  "properties": {
    "preferences": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "Notes or accords the wearer enjoys, e.g. ['vanilla','amber','rose']"
    },
    "budget": {
      "type": "number",
      "minimum": 0,
      "description": "Max MSRP in USD"
    },
    "occasion": {
      "type": "string",
      "maxLength": 120,
      "description": "What the fragrance is for"
    },
    "gender": {
      "type": "string",
      "enum": [
        "masculine",
        "feminine",
        "unisex"
      ],
      "description": "Marketed gender category of the fragrance; omit to include all"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 5)"
    }
  },
  "required": [
    "preferences"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Side-by-side comparison: note pyramids, shared and distinct accords, longevity/sillage/compliment scores, concentration, and price difference.

{
  "type": "object",
  "properties": {
    "fragrance_a": {
      "type": "string",
      "maxLength": 200,
      "description": "First fragrance — slug or name"
    },
    "fragrance_b": {
      "type": "string",
      "maxLength": 200,
      "description": "Second fragrance — slug or name"
    }
  },
  "required": [
    "fragrance_a",
    "fragrance_b"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fragrances Perfume Picks users are adding to their wardrobes most over the last 30 days (falls back to catalog popularity when live activity data is unavailable). The method used is labeled in the response.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 10, max 10)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

A fragrance suggestion for right now, based on mood, occasion (e.g. 'date', 'office tomorrow', 'night out', 'cozy evening in'), and season — scored with Perfume Picks' community compliment, office-safety, and versatility data.

{
  "type": "object",
  "properties": {
    "mood": {
      "type": "string",
      "maxLength": 120,
      "description": "How you're feeling"
    },
    "occasion": {
      "type": "string",
      "maxLength": 120,
      "description": "The setting"
    },
    "season": {
      "type": "string",
      "enum": [
        "winter",
        "spring",
        "summer",
        "fall"
      ],
      "description": "Season to weight the pick toward — heavier, warmer scents in winter; fresher in summer"
    },
    "gender": {
      "type": "string",
      "enum": [
        "masculine",
        "feminine",
        "unisex"
      ],
      "description": "Marketed gender category of the fragrance; omit to include all"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}