Fragrantica APIfragrantica.it ↗
Search Fragrantica fragrances and retrieve notes, accords, perfumer, ratings, and olfactory family via a simple REST API.
What is the Fragrantica API?
The Fragrantica API provides access to fragrance data from fragrantica.it across 2 endpoints, returning up to 11 structured fields per perfume. Use search_fragrances to find fragrances by keyword and get matching names, brands, release years, and page URLs, then pass any URL to get_fragrance_details to retrieve top, heart, and base notes, main accords with strength percentages, the perfumer name, olfactory family classification, and community rating.
curl -X GET 'https://api.parse.bot/scraper/14198d37-e4ad-4f4e-a605-188b0e7b2735/search_fragrances?limit=5&query=Sauvage' \ -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-it-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 fragrances and drill into details."""
from parse_apis.fragrantica_it_fragrance_api import Fragrantica, FragranceNotFound
client = Fragrantica()
# Search for fragrances by keyword, capped at 5 total results.
for summary in client.fragrancesummaries.search(query="Sauvage", limit=5):
print(summary.name, summary.brand, summary.year)
# Drill into the first result's full details via .first()
summary = client.fragrancesummaries.search(query="Chanel No 5", limit=1).first()
if summary:
fragrance = summary.details()
print(fragrance.name, fragrance.brand, fragrance.perfumer)
print(fragrance.rating.average, fragrance.rating.votes)
for accord in fragrance.main_accords[:3]:
print(accord.name, accord.strength_percent)
print(fragrance.notes.top, fragrance.notes.heart, fragrance.notes.base)
# Fetch a fragrance directly by URL when you already have it.
try:
detail = client.fragrances.get(url="https://www.fragrantica.it/perfume/Dior/Sauvage-31861.html")
print(detail.name, detail.olfactory_family, detail.year_of_release)
except FragranceNotFound as exc:
print(f"Fragrance not found: {exc.url}")
print("exercised: fragrancesummaries.search / summary.details / fragrances.get")
Full-text search over Fragrantica's perfume catalog via Algolia. Returns lightweight summaries (name, brand, URL, image, year) suitable for browsing or drilling into details. Each result carries a canonical URL that serves as the identity for fetching full fragrance data.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return. |
| queryrequired | string | Search keyword matching fragrance names and brands (e.g. 'Sauvage', 'Chanel No 5'). |
{
"type": "object",
"fields": {
"results": "array of fragrance summary objects with name, brand, url, image, and year"
},
"sample": {
"data": {
"results": [
{
"url": "https://www.fragrantica.it/perfume/Dior/Sauvage-31861.html",
"name": "Sauvage",
"year": 2015,
"brand": "Dior",
"image": "https://fimgs.net/mdimg/perfume/375x500.31861.jpg"
}
]
},
"status": "success"
}
}About the Fragrantica API
Endpoints
search_fragrances accepts a required query string (e.g. 'Sauvage' or 'Chanel No 5') and an optional limit integer. It returns an array of fragrance objects, each with name, brand, url, image, and year. The url field is the canonical fragrantica.it perfume page URL and is the required input for the detail endpoint.
Fragrance Details
get_fragrance_details takes a full fragrantica.it perfume page URL and returns a structured object with name, brand, year_of_release, olfactory_family, and perfumer as scalar fields. The notes object contains three arrays — top, heart, and base — each listing individual note names. The main_accords array contains objects with a name and strength_percent field, indicating how prominently each accord registers in community votes. The rating object exposes both the average score and the total votes count.
Coverage and Limitations
The API covers the Italian-language edition of Fragrantica (fragrantica.it). Search results depend on Fragrantica's own index, so very obscure or recently added fragrances may not appear. User-submitted reviews, seasonal or situational tags (e.g. longevity, sillage), and fragrance variation/flanker listings are not part of the current response shape.
The Fragrantica API is a managed, monitored endpoint for fragrantica.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when fragrantica.it 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.it 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 perfume discovery app that filters by olfactory family and base notes
- Aggregate community ratings and vote counts across a brand's full catalog
- Map accord strength percentages to visualize a fragrance's scent profile
- Identify the perfumer behind a fragrance for nose-focused research or editorial content
- Track year_of_release data to analyze fragrance release trends by decade
- Cross-reference top and heart notes across multiple fragrances to find similar scents
- Populate a personal fragrance journal app with structured note and accord data
| 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 have an official developer API?+
What does the notes field in get_fragrance_details actually contain?+
notes object contains three arrays: top, heart, and base. Each array lists individual note names as strings (e.g. 'bergamot', 'sandalwood'). Notes are returned as Fragrantica lists them on the Italian-language perfume page. If a perfume lacks a declared note tier, that array may be empty.Does the API return longevity, sillage, or seasonal ratings from the community?+
rating (average score and vote count) and main_accords with strength percentages. Longevity, sillage, projection, and seasonal/situational community votes are not exposed. You can fork this API on Parse and revise it to add those fields.Does search_fragrances support filtering by brand, note, or accord directly?+
search_fragrances endpoint accepts a free-text query and an optional limit. It does not support structured filters by brand, note, or accord. You can fork this API on Parse and revise it to add filtered search parameters.Are flankers or fragrance variations returned as separate results?+
search_fragrances if indexed separately. The API does not group or link related variations together.