/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. ThesimilarityScore 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: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.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.