Perfumes

Perfume data

Perfumes are the central entity in WikiParfum. Each perfume record includes rich metadata — brand, olfactive family, ingredients, perfumers, imagery, and more — enabling product pages, comparison tools, and enriched catalog experiences.

Retrieve a single perfume

Fetch a perfume by its unique ID, URL-friendly slug, or EAN barcode.

By ID

query PerfumeById {
  findPerfumeById(id: "424", lang: "EN") {
    id
    name
    description
    brand {
      name
    }
    family {
      name
      color
    }
    secondaryFamily {
      name
    }
    gender
    year
    ingredients {
      id
      name
      proportion
      hero
    }
    image {
      urls {
        low
        mid
        high
      }
    }
    slug
  }
}

{
  "data": {
    "findPerfumeById": {
      "id": "424",
      "name": "GOOD GIRL",
      "description": "Good Girl is a fragrance as powerful as it is sensual. An audacious blend of dark and light elements. For the woman who knows when it's good to be bad.",
      "brand": {
        "name": "Carolina Herrera"
      },
      "family": {
        "name": "AMBERY (ORIENTAL)",
        "color": "#B41F24"
      },
      "secondaryFamily": {
        "name": "AMBERY (ORIENTAL)"
      },
      "gender": "F",
      "year": 2016,
      "ingredients": [
        {
          "id": "13",
          "name": "Almond",
          "proportion": null,
          "hero": 0
        },
        {
          "id": "115",
          "name": "Cocoa",
          "proportion": null,
          "hero": 0
        }
      ],
      "image": {
        "urls": {
          "low": "https://api-assets.wikiparfum.com/_resized/1trb5qms3qhq6u8ja6jc2pwj13zqn6q1u3lftxcoq2qq5th2obdx8be8kopg-w100-q85.jpg",
          "mid": "https://api-assets.wikiparfum.com/_resized/1trb5qms3qhq6u8ja6jc2pwj13zqn6q1u3lftxcoq2qq5th2obdx8be8kopg-w250-q85.jpg",
          "high": "https://api-assets.wikiparfum.com/_resized/1trb5qms3qhq6u8ja6jc2pwj13zqn6q1u3lftxcoq2qq5th2obdx8be8kopg-w500-q85.jpg"
        }
      },
      "slug": "good-girl"
    }
  }
}

By slug

Useful for SEO-friendly URLs and deep linking.

query PerfumeBySlug {
  findPerfumeBySlug(slug: "good-girl", lang: "EN") {
    id
    name
    brand {
      name
    }
    family {
      name
    }
  }
}

{
  "data": {
    "findPerfumeBySlug": {
      "id": "424",
      "name": "GOOD GIRL",
      "brand": {
        "name": "Carolina Herrera"
      },
      "family": {
        "name": "AMBERY (ORIENTAL)"
      }
    }
  }
}

By EAN

Look up a perfume using its barcode — ideal for scan-to-discover experiences.

query PerfumeByEAN {
  findPerfumeByEAN(ean: "8411061994351", lang: "EN") {
    id
    name
    brand {
      name
    }
  }
}

{
  "data": {
    "findPerfumeByEAN": {
      "id": "424",
      "name": "GOOD GIRL",
      "brand": {
        "name": "Carolina Herrera"
      }
    }
  }
}

You can also look up multiple EANs at once:

query PerfumesByEANS {
  findPerfumesByEANS(
    eans: ["8411061994351", "0085715166067"]
    lang: "EN"
  ) {
    id
    name
    ean
  }
}

{
  "data": {
    "findPerfumesByEANS": [
      {
        "id": "424",
        "name": "GOOD GIRL",
        "ean": "8411061994351"
      }
    ]
  }
}

List and filter perfumes

Retrieve perfumes with full-text search, filters, sorting, and pagination.

query FilteredPerfumes {
  findPerfumes(search: {
    lang: "EN"
    search: "sauvage"
    page: "0,20"
    order_by: "name asc"
    filters: {
      gender: "M"
    }
  }) {
    id
    name
    brand {
      name
    }
    family {
      name
    }
    gender
    year
  }
}

{
  "data": {
    "findPerfumes": [
      {
        "id": "1265",
        "name": "EAU SAUVAGE EAU DE TOILETTE",
        "brand": {
          "name": "Dior"
        },
        "family": {
          "name": "CITRUS"
        },
        "gender": "M",
        "year": 1966
      },
      {
        "id": "1900",
        "name": "SAUVAGE",
        "brand": {
          "name": "Dior"
        },
        "family": {
          "name": "AROMATIC FOUGERE"
        },
        "gender": "M",
        "year": 2015
      }
    ]
  }
}

Filter by brand

query PerfumesByBrand {
  findPerfumes(search: {
    lang: "EN"
    brand: "42"
    page: "0,20"
  }) {
    id
    name
    year
  }
}

{
  "data": {
    "findPerfumes": [
      {
        "id": "108",
        "name": "BOSS BOTTLED INFINITE",
        "year": 2019
      },
      {
        "id": "109",
        "name": "BOSS BOTTLED",
        "year": 1998
      }
    ]
  }
}

Filter by perfumist

query PerfumesByPerfumist {
  findPerfumes(search: {
    lang: "EN"
    perfumistSlug: "francis-kurkdjian"
    page: "0,20"
  }) {
    id
    name
    brand {
      name
    }
  }
}

Recommended perfumes

Get perfumes similar to one or more input perfumes, ranked by olfactive proximity. See the Recommendations guide for business context and advanced patterns.

By perfume ID

query RecommendedPerfumes {
  recommendedPerfumes(search: {
    perfumes: "424,1"
    lang: "EN"
    page: "0,10"
  }) {
    id
    name
    brand {
      name
    }
    family {
      name
      color
    }
    image {
      urls {
        low
        mid
      }
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "734",
        "name": "HYPNOTIC POISON",
        "brand": {
          "name": "Dior"
        },
        "family": {
          "name": "AMBERY (ORIENTAL)",
          "color": "#B41F24"
        },
        "image": {
          "urls": {
            "low": "https://api-assets.wikiparfum.com/_resized/bcc0afq0ryujbeeg4473aem507yb6ghefxu5ipfyo3ubdii949ujh5flcmej-w100-q85.jpg",
            "mid": "https://api-assets.wikiparfum.com/_resized/bcc0afq0ryujbeeg4473aem507yb6ghefxu5ipfyo3ubdii949ujh5flcmej-w250-q85.jpg"
          }
        }
      },
      {
        "id": "7684",
        "name": "TOY 2",
        "brand": {
          "name": "Moschino"
        },
        "family": {
          "name": "FLORAL",
          "color": "#E2839A"
        },
        "image": {
          "urls": {
            "low": "https://api-assets.wikiparfum.com/_resized/5b84tfidpdno2ccieq2zomtwxhg750zo18jw7tclq8li7ixw0x0mhxb9jgoy-w100-q85.jpg",
            "mid": "https://api-assets.wikiparfum.com/_resized/5b84tfidpdno2ccieq2zomtwxhg750zo18jw7tclq8li7ixw0x0mhxb9jgoy-w250-q85.jpg"
          }
        }
      }
    ]
  }
}

By EAN

Use EAN barcodes as input — ideal for scan-based or POS-integrated experiences where you have barcodes but not WikiParfum IDs.

query RecommendByEAN {
  recommendedPerfumes(search: {
    perfumeEans: "8411061994351,0085715166067"
    lang: "EN"
    page: "0,10"
  }) {
    id
    name
    brand {
      name
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "7684",
        "name": "TOY 2",
        "brand": {
          "name": "Moschino"
        }
      },
      {
        "id": "734",
        "name": "HYPNOTIC POISON",
        "brand": {
          "name": "Dior"
        }
      }
    ]
  }
}

User-scoped

Pass a userId to incorporate the user’s interaction history into the ranking. Over time, recommendations become increasingly aligned with each user’s evolving taste profile. See Sessions and CRM Personalization for details.

query UserRecommendations {
  recommendedPerfumes(
    search: {
      perfumes: "424"
      lang: "EN"
      page: "0,10"
    }
    userId: "user-abc-123"
  ) {
    id
    name
    brand {
      name
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "734",
        "name": "HYPNOTIC POISON",
        "brand": {
          "name": "Dior"
        }
      },
      {
        "id": "36141",
        "name": "GUCCI GUILTY ABSOLU DE PARFUM POUR FEMME",
        "brand": {
          "name": "Gucci"
        }
      }
    ]
  }
}

Custom recommendation rules

Use customRecommendation to control which brands or perfumes appear in results. Essential for retailers who need recommendations limited to their own assortment, or brands that want to exclude competitors.

query CustomRecommendations {
  recommendedPerfumes(search: {
    perfumes: "424"
    lang: "EN"
    page: "0,10"
    customRecommendation: {
      enabled: true
      excludedBrands: [42, 87]
      includedBrands: [10, 25, 33]
      excludedPerfumes: [1]
    }
  }) {
    id
    name
    brand {
      name
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "5807",
        "name": "AMBRE SULTAN",
        "brand": {
          "name": "Serge Lutens"
        }
      }
    ]
  }
}

Field	Description
`excludedBrands`	Brand IDs to exclude from results
`includedBrands`	Only return perfumes from these brands
`excludedPerfumes`	Specific perfume IDs to exclude
`includedPerfumes`	Specific perfume IDs to include

Filtered recommendations

Recommendations can be narrowed using standard filters. See Filtering & Pagination for all available filter options.

query FilteredRecommendations {
  recommendedPerfumes(search: {
    perfumes: "424"
    lang: "EN"
    page: "0,10"
    filters: {
      gender: "F"
      classification: "prestige"
    }
  }) {
    id
    name
    gender
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "16280",
        "name": "VERY GOOD GIRL",
        "gender": "F"
      }
    ]
  }
}

Browse all WikiParfum perfumes

The findPerfumesPublic query returns perfumes from the entire WikiParfum database — not limited to your catalog. It uses a reduced PerfumePublic type with fewer fields, making it ideal for browsing, discovery, and public-facing experiences where you want to show the full fragrance universe.

findPerfumes vs findPerfumesPublic: findPerfumes returns perfumes from your catalog (scoped to your Product Feed) with the full Perfume type. findPerfumesPublic returns all perfumes in WikiParfum’s database with a reduced field set.

query BrowseAllPerfumes {
  findPerfumesPublic(search: {
    lang: "EN"
    page: "0,10"
    order_by: "name asc"
    filters: {
      gender: "F"
      family: "floral"
    }
  }) {
    id
    name
    description
    gender
    brand {
      name
    }
    family {
      name
      color
    }
    secondaryFamily {
      name
    }
    image {
      urls {
        low
        mid
        high
      }
    }
    eans
  }
}

PerfumePublic fields

The PerfumePublic type exposes a subset of the full Perfume type:

Field	Type	Description
`id`	`ID`	Unique perfume identifier
`name`	`String`	Perfume name
`description`	`String`	Perfume description
`gender`	`String`	Target gender: `"F"`, `"M"`, or `"U"`
`brand`	`{ name }`	Brand name
`family`	`{ name, color }`	Primary olfactive family
`secondaryFamily`	`{ name, color }`	Secondary olfactive family
`image`	`{ urls { low, mid, high } }`	Resized image URLs
`eans`	`[String]`	EAN barcodes from the client’s catalog for this perfume

Input parameters

findPerfumesPublic accepts a PerfumesPublicSearch input with the following fields:

Parameter	Type	Description
`lang`	`String`	Language for localized content (e.g., `"EN"`, `"FR"`)
`page`	`String`	Pagination: `"offset,limit"` (e.g., `"0,20"`)
`order_by`	`String`	Sort order (e.g., `"name asc"`)
`search`	`String`	Full-text search against name and brand
`brand`	`ID`	Filter by brand ID
`ids`	`String`	Filter by perfume IDs (comma-separated)
`slugs`	`String`	Filter by perfume slugs (comma-separated)
`filters`	`Filters`	Standard filters

Key perfume fields

Field	Description
`name`	Perfume name
`brand`	Brand information
`family` / `secondaryFamily`	Olfactive family classification (primary and secondary)
`gender`	Target gender: `"F"`, `"M"`, or `"U"` (unisex)
`year` / `month`	Release date
`ingredients`	List of ingredients with `proportion` and `hero` flag
`classification`	Market segment: `"prestige"` or `"mass"`
`slug`	URL-friendly identifier
`ean` / `eans`	Barcode(s)
`image`	Resized image URLs (`low`, `mid`, `high`)
`perfumers`	Perfumers who created the fragrance
`intensity`	Olfactive intensity score
`discontinued`	Whether the perfume is discontinued

When your account has a Product Feed configured, the eans field returns only EANs that exist in your catalog — not all EANs known to WikiParfum for that perfume. This applies to both Perfume and PerfumePublic types. If no Product Feed is configured, all known EANs are returned.

Getting Started

Guides

API Reference

Perfume data

Retrieve a single perfume

By ID

By slug

By EAN

List and filter perfumes

Filter by brand

Filter by perfumist

Recommended perfumes

By perfume ID

By EAN

User-scoped

Custom recommendation rules

Filtered recommendations

Browse all WikiParfum perfumes

PerfumePublic fields

Input parameters

Key perfume fields

​Perfume data

​Retrieve a single perfume

​By ID

​By slug

​By EAN

​List and filter perfumes

​Filter by brand

​Filter by perfumist

​Recommended perfumes

​By perfume ID

​By EAN

​User-scoped

​Custom recommendation rules

​Filtered recommendations

​Browse all WikiParfum perfumes

​PerfumePublic fields

​Input parameters

​Key perfume fields

Perfume data

Retrieve a single perfume

By ID

By slug

By EAN

List and filter perfumes

Filter by brand

Filter by perfumist

Recommended perfumes

By perfume ID

By EAN

User-scoped

Custom recommendation rules

Filtered recommendations

Browse all WikiParfum perfumes

PerfumePublic fields

Input parameters

Key perfume fields