Fragrantica APIfragrantica.com ↗
Access Fragrantica perfume data via API: search perfumes, get fragrance notes pyramids, main accords, ratings, brand lists, and note categories.
What is the Fragrantica API?
The Fragrantica API covers 4 endpoints that expose perfume search, detailed fragrance profiles, brand directories, and note categories from Fragrantica's community-driven perfume database. The get_perfume_details endpoint alone returns 8 distinct fields including the full notes pyramid (top, middle, and base), main accords with intensity scores, average rating, and a description — giving developers structured access to data that typically requires manual browsing.
curl -X GET 'https://api.parse.bot/scraper/d2c369a4-db4f-46ae-829d-562361126109/search_perfumes?page=0&limit=5&query=rose' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace fragrantica-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Fragrantica SDK — search perfumes, browse brands & notes."""
from parse_apis.fragrantica_perfume_api import Fragrantica, Letter, PerfumeNotFound
client = Fragrantica()
# Search for perfumes matching a keyword, capped at 5 results.
for perfume in client.perfumes.search(query="oud", limit=5):
print(perfume.naslov, perfume.dizajner, perfume.rating)
# Get detailed info for one perfume via its URL.
detail = client.perfumedetails.get(url="https://www.fragrantica.com/perfume/Chanel/Chanel-No-5-Eau-de-Parfum-40069.html")
print(detail.name, detail.brand, detail.rating_value)
print("Top notes:", detail.notes.top)
for accord in detail.main_accords:
print(f" {accord.name}: {accord.intensity}")
# Handle a missing perfume gracefully.
try:
client.perfumedetails.get(url="https://www.fragrantica.com/perfume/Unknown/Fake-99999999.html")
except PerfumeNotFound as exc:
print(f"Not found: {exc}")
# List brands starting with a specific letter using the Letter enum.
for brand in client.brands.list(letter=Letter.D, limit=5):
print(brand.name, brand.url)
# Browse fragrance note categories.
for category in client.notecategories.list(limit=3):
print(category.category, [n.name for n in category.notes[:3]])
print("exercised: perfumes.search / perfumedetails.get / brands.list / notecategories.list")
Full-text search over Fragrantica's perfume database via Algolia. Returns paginated results with perfume name, designer, year, rating, gender, and thumbnail. The API key is fetched dynamically from the site on first call.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-based) |
| limit | integer | Results per page (max 100) |
| queryrequired | string | Search keyword (e.g. 'chanel', 'rose', 'dior') |
{
"type": "object",
"fields": {
"hits": "array of perfume objects with naslov (name), dizajner (designer), godina (year), rating, slug, id, spol (gender), thumbnail",
"page": "integer current page number",
"nbHits": "integer total number of matching perfumes",
"nbPages": "integer total number of pages",
"hitsPerPage": "integer results per page"
},
"sample": {
"data": {
"hits": [
{
"id": 40069,
"slug": "Chanel/Chanel-No-5-Eau-de-Parfum",
"spol": "female",
"godina": 1986,
"naslov": "Chanel No 5 Eau de Parfum",
"rating": 3.5883,
"dizajner": "Chanel",
"thumbnail": "https://fimgs.net/mdimg/perfume/m.40069.jpg"
}
],
"page": 0,
"nbHits": 391,
"nbPages": 20,
"hitsPerPage": 20
},
"status": "success"
}
}About the Fragrantica API
Search and Browse Perfumes
The search_perfumes endpoint accepts a query string (e.g. 'chanel', 'rose', 'oud') and returns paginated results via 0-based page and limit parameters. Each hit includes naslov (perfume name), dizajner (designer), godina (year), rating, spol (gender classification), slug, id, and a thumbnail URL. The nbHits field tells you the total match count so you can calculate pagination depth using nbPages and hitsPerPage.
Detailed Perfume Profiles
The get_perfume_details endpoint takes a full Fragrantica perfume URL and returns the complete fragrance profile. The notes object contains three keyed arrays — top, middle, and base — each listing note names. The main_accords array returns objects with name and intensity, which lets you rank a perfume's dominant character (e.g. woody at 85, floral at 60). rating_value and rating_count reflect community scoring, and description provides the editorial text for the fragrance.
Brands and Notes Directories
list_brands accepts an optional letter parameter (single character A–Z) to filter results alphabetically, returning brand name and Fragrantica url for each match. This makes it straightforward to build or refresh a full brand index letter by letter. list_notes requires no parameters and returns every fragrance note grouped into categories (e.g. Citrus, Flowers, Woods), with each note's name, url, and image field — useful for building note-based search interfaces or ingredient taxonomy trees.
The Fragrantica API is a managed, monitored endpoint for fragrantica.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when fragrantica.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official fragrantica.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a fragrance recommendation engine using
main_accordsintensity scores and note pyramid data - Index a full brand directory by iterating
list_brandsthrough letters A–Z - Populate a perfume database with year, gender, rating, and thumbnail from
search_perfumeshits - Display a visual notes taxonomy using the categorized output of
list_noteswith note images - Compare community ratings across multiple perfumes using
rating_valueandrating_count - Filter a perfume catalog by gender classification using the
spolfield from search results - Enrich an e-commerce fragrance catalog with top/middle/base note pyramids via
get_perfume_details
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Fragrantica offer an official developer API?+
What does `get_perfume_details` return that `search_perfumes` does not?+
search_perfumes returns lightweight metadata: name, designer, year, rating, gender, slug, and thumbnail. get_perfume_details adds the full notes pyramid (top, middle, base arrays), main_accords with intensity values, a full description text, and explicit rating_count. You need to call get_perfume_details with a perfume's URL to get the notes and accords data.Can I retrieve user reviews or individual community votes for a perfume?+
rating_value (average score) and rating_count (number of votes) but does not expose individual user reviews or vote breakdowns. You can fork this API on Parse and revise it to add an endpoint that returns per-user review text and scores.How does pagination work in `search_perfumes`?+
page=0 for the first page. The response includes nbHits (total results), nbPages (total pages), and hitsPerPage to let you calculate how many pages exist for a given query. Increment page up to nbPages - 1 to walk through all results.Does the API cover fragrance concentration variants (EDP, EDT, parfum)?+
search_perfumes hits and get_perfume_details response do not explicitly expose concentration as a structured field. You can fork this API on Parse and revise it to parse and surface concentration information from perfume detail pages.