Skip to main content
The /v1/fragrances/{id}/similar endpoint returns fragrances that share a similar accord profile, powered by Noteboxd’s olfactory similarity engine. You can use it to build recommendation carousels, “you might also like” features, or tools that help users find alternatives to sold-out or discontinued scents.

How Similarity Works

Similarity is computed from accord vectors — a numerical representation of the relative strength of accord families like woody, floral, oriental, fresh, and gourmand for each fragrance. Every fragrance in the Noteboxd database has an accord fingerprint derived from community data and expert curation. When you call the similarity endpoint, the engine compares the seed fragrance’s accord vector against the full catalog and returns the closest matches ranked by cosine similarity. The similarityScore in each result is a value between 0 and 1: the closer to 1, the more aligned the two fragrances’ accord profiles are. A score of 0.90+ typically indicates a near-identical olfactory character, while scores around 0.70 suggest a family resemblance with some meaningful differences.

Basic Similarity Call

Pass the fragrance ID as a path parameter:
The response always echoes back the id of the seed fragrance alongside the ranked similar array, making it easy to correlate results when you’re handling multiple concurrent requests.

Building a Recommendation Feature

The following steps walk you through a complete recommendation flow — from a user-supplied search term all the way to a set of rich fragrance profiles ready to display.
1

Search for the seed fragrance

Use /v1/search with type=fragrance to find the fragrance your user has in mind and retrieve its id.
2

Fetch similar fragrances

Call /v1/fragrances/{id}/similar with the id from step one to get a ranked list of similar fragrances and their IDs.
3

Batch-fetch full profiles

Pass the returned id values to POST /v1/fragrances/batch to retrieve complete profiles for all recommendations in a single request.
Here’s the full flow in JavaScript:
Cost breakdown for this flow: search (1¢) + similar (2¢) + batch of 10 profiles (25¢) = ~28¢ total for a fully enriched set of 10 recommendations. If you need notes, accords, and reviews for each recommendation too, consider whether enriching each individually or adjusting your data model makes more sense for your use case.
If you need the seed fragrance’s full data — notes, accords, reviews, and similar fragrances — all in one shot, use POST /v1/fragrances/enrich with the similarLimit field set. This saves an extra round trip and costs a flat 10¢. See the enrichment guide for details.