API Documentation

To access the Fragrance API, follow these steps:

1. Login: Navigate to the Login page and authenticate with your credentials.
2. Generate an API Key: Once logged in, go to your Dashboard and generate a new API key. This key will be used to authenticate your API requests.

Endpoints

1. Get Fragrance Details

Retrieve the main accords and scents of a specific fragrance.

curl -X POST https://nosehq.com/api/fragrance \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: <api-key>" \     
    -d '{"fragrance_name": "Dior Sauvage"}'
    

Sample Request Body:

{
  "fragrance_name": "Dior Sauvage"
}
    

Sample Response:

{
  "main_accords": "fresh spicy, amber, citrus, aromatic, musky, woody, lavender, herbal, warm spicy",
  "name": "Dior Sauvage",
  "scents": "Calabrian Bergamot, Patchouli, Pepper, Geranium"
}
    

Parameters

Response Fields

Error Handling

The API will respond with appropriate error messages for invalid inputs or authentication failures.

{
  "error": "Fragrance name is required."
}
    

1.2. Handle Typos and Suggestions

If the fragrance name provided contains a typo or is misspelled, the API will suggest similar fragrances.

curl -X POST https://nosehq.com/api/fragrance \
        -H "Content-Type: application/json" \
        -H "X-API-KEY: USmQ7QjOlocaReR9NRXOXuGVOvhmLrf1" \
        -d '{"fragrance_name": "Dior Sau"}'
    

Sample Request Body:

    {
      "fragrance_name": "Dior Sau"
    }
    

Sample Response:

    {
      "message": "Did you mean one of these fragrances?",
      "suggestions": [
        {
          "main_accords": "citrus, floral, white floral, fruity, fresh, fresh spicy, aromatic, rose, green, almond",
          "name": "Dior Star",
          "scents": "Petitgrain, Mandarin Orange, Bergamot, Musk, Almond"
        },
        {
          "main_accords": "fresh spicy, amber, citrus, aromatic, musky, woody, lavender, herbal, warm spicy",
          "name": "Dior Sauvage",
          "scents": "Calabrian Bergamot, Patchouli, Pepper, Geranium, Cedar"
        },
        {
          "main_accords": "vanilla, powdery, rose, floral, fruity, sweet, fresh, iris, musky, amber",
          "name": "Miss Dior",
          "scents": "rose, gardenia, sage, and other green florals."
        },
        {
          "main_accords": "white floral, woody, fruity, animalic, fresh spicy, musky, powdery, leather, warm spicy, earthy",
          "name": "Diorama",
          "scents": "pepper, jasmine, tuberose, sandalwood, leather"
        },
        {
          "main_accords": "iris, citrus, powdery, woody, aromatic, violet, amber, earthy, fresh spicy, soft spicy",
          "name": "Dior Homme Eau",
          "scents": "Grapefruit, Calabrian bergamot, Coriander, Tuscan iris, Virginian cedar"
        }
      ]
    }
    

Parameters

Response Fields

Error Handling

The API will respond with appropriate error messages for invalid inputs or authentication failures.

    {
      "error": "Fragrance name is required."
    }
    

Note: The order of words in the fragrance name does not affect the API response. For example, "Dior Sauvage" and "Sauvage Dior" will return the same results.

2. Describe Fragrance Similarities

Obtain a detailed description of a target fragrance and its similarities with known fragrances.

curl -X POST https://nosehq.com/api/describe \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: <api-key>" \
    -d '{
      "target_fragrance": "Dior Sauvage",
      "known_fragrances": ["Dior Sauvage", "Tom Ford Oud Wood"]
    }'
    

Sample Request Body:

{
  "target_fragrance": "Dior Sauvage",
  "known_fragrances": ["Dior Sauvage", "Tom Ford Oud Wood"]
}
    

Sample Response:

{
  "base_description": "The primary accord of Dior Sauvage is fresh spicy. It smells like Armaf Magnificient Blue (Accords: fresh spicy, citrus, aromatic, woody, warm spicy, lavender, herbal; Scents: grapefruit, bergamot, pepper, patchouli, geranium; Similarity Score: 0.73), Ex Nihilo Amber Sky (Accords: amber, fresh spicy, vanilla, woody, aromatic, powdery, warm spicy, sweet, soft spicy; Scents: bergamot, nutmeg, geranium, vanilla, cedar; Similarity Score: 0.69), Diavolo (Accords: fresh spicy, citrus, leather, warm spicy, woody, aromatic, animalic, powdery, green, musky; Scents: Mandarin orange, Bergamot, Patchouli, Pepper, Geranium; Similarity Score: 0.69). Additionally, it resembles Dior Sauvage (Accords: fresh spicy, amber, citrus, aromatic, musky, woody, lavender, herbal, warm spicy; Scents: Calabrian Bergamot, Patchouli, Pepper, Geranium, Cedar; Similarity Score: 1.00).",
  "enhanced_description": "Immerse yourself in the invigorating world of Dior Sauvage, where the primary accord of fresh spiciness ignites your senses with a dynamic blend of vibrant notes. Picture yourself surrounded by the exhilarating essence of Armaf Magnificent Blue, with its zesty grapefruit and bergamot dancing playfully with the warmth of pepper and patchouli. Feel the luxurious embrace of Ex Nihilo Amber Sky, as the amber and vanilla intertwine with the fresh spiciness of bergamot and nutmeg, creating an aura of sophistication and intrigue. Let the captivating allure of Diavolo transport you to a realm of fresh spiciness and citrus brightness, enveloped in a tantalizing blend of leather, green notes, and musky undertones. And of course, rediscover the timeless elegance of Dior Sauvage itself, where Calabrian bergamot, patchouli, and cedar unite in perfect harmony, creating a scent that is both classic and contemporary. With each spritz, you are swept away on a journey of olfactory delight, where freshness meets spice in a symphony of unparalleled allure.",
  "primary_accord": "fresh spicy"
}
    

Parameters

Response Fields

Error Handling

The API will respond with appropriate error messages for invalid inputs or authentication failures.

{
  "error": "Please provide 'target_fragrance' and 'known_fragrances' in the request body."
}
    

3. Get Fragrance Info

Retrieve the top, middle, and base notes of a specific fragrance, along with scent percentages.

curl -X GET "https://nosehq.com/api/fragranceinfo?name=Dior%20Sauvage" \
    -H "X-API-KEY: <API-KEY>"
    

Sample Response:

{
  "base_note": "Ambroxan, Cedar, Labdanum",
  "middle_note": "Sichuan Pepper, Lavender, Pink Pepper, Vetiver, Patchouli, Geranium, elemi",
  "scent_percentage": {
    "amber": "72%",
    "aromatic": "63%",
    "citrus": "70%",
    "herbal": "46%",
    "lavender": "46%",
    "musky": "58%",
    "spicy": "45%",
    "woody": "54%"
  },
  "top_note": "Calabrian bergamot, Pepper"
}
    

Note: The fragrance name must be provided as a query parameter. Ensure that it is URL-encoded if it contains spaces or special characters.

Parameters

Response Fields

Error Handling

The API will respond with appropriate error messages for invalid inputs or authentication failures.

{ 
  "error":"No exact match found for 'Dior Sauv'.",
  "possible_matches":["Dior Sauvage","Dior Sauvage Elixir","Dior Sauvage Eau Forte"]
}
or
{
  "error": "Fragrance name is required as a query parameter."
}
    

4. Match Fragrances Based on Desired Accords and Notes

Find the best-matched fragrances based on desired main accords and specified percentage weights. You can also include top, middle, base, or general notes to refine your search. When general_note is provided, it will weigh more heavily in the matching algorithm compared to specific notes.

curl -X POST https://nosehq.com/api/match_fragrance \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: <API-KEY>" \
    -d '{
      "accords": {
        "fresh spicy": 20,
        "woody": 50,
        "citrus": 70
      },
      "notes": {
        "general_note": ["Ambroxan"],
        "base_note": ["Ambroxan", "Cedar"],
        "middle_note": ["Sichuan Pepper", "Lavender", "Pink Pepper"],
        "top_note": ["Calabrian bergamot"]
      }
    }'
    

Response:

    {
        "matches": [
          {
            "name": "D & G Light Blue",
            "main_accords": "citrus: 100%, woody: 75%, fresh: 63%",
            "top_notes": "Calabrian bergamot, Grapefruit",
            "middle_notes": "Sichuan Pepper, Lavender",
            "base_notes": "Ambroxan, Cedar",
            "match_percentage": 95.8
          },
          {
            "name": "Versace Eros",
            "main_accords": "vanilla: 100%, aromatic: 92%, green: 88%",
            "top_notes": "Mint, Calabrian bergamot",
            "middle_notes": "Sichuan Pepper, Lavender",
            "base_notes": "Ambroxan, Vetiver",
            "match_percentage": 89.3
          }
        ]
    }
    

Explanation:

• matches: An array of fragrance objects sorted by their match percentage in descending order. Higher percentages indicate better matches.
• matches.name: The name of the fragrance.
• matches.main_accords: A string listing the main accords of the fragrance along with their percentages.
• matches.top_notes: A string listing the top notes of the fragrance.
• matches.middle_notes: A string listing the middle notes of the fragrance.
• matches.base_notes: A string listing the base notes of the fragrance.
• matches.match_percentage: A numerical value representing the percentage match. Higher percentages indicate better matches.

Parameters

Response Fields

Authentication

All API requests must include the X-API-KEY header with your unique API key. Without a valid API key, access to the API endpoints will be denied.

Notes

• Ensure that your API key is kept secure and not exposed publicly.
• Refer to the Dashboard for managing your API keys and monitoring usage.

About the Project

NoseHQ is your ultimate destination for AI-powered fragrance technology. We specialize in providing developers and brands with cutting-edge tools to explore, analyze, and integrate scents into their applications. From scent matching to comprehensive fragrance databases, our platform is designed to make the world of fragrances accessible and innovative.

Our Mission

Explore Fragrances with Fragella (in development)

• Search Engine: Fragella's advanced search capabilities are built on NoseHQ's robust API, offering unmatched accuracy in scent matching and recommendations.
• Store Integration: Through Fragella, users can connect directly to stores, bringing their scent journey full circle—from discovery to purchase. Whether you're a developer integrating our API, a brand enhancing your customer's experience, or an individual discovering your next signature scent through Fragella, NoseHQ is the engine driving your success.

Key Features

• Intelligent scent matching algorithms
• Personalized recommendations based on accords and scents.
• Look up detailed scent profiles and fragrance notes/ingredients by name.
• A personalized Lab to create your own signature fragrance

Get in Touch

🤔 Got a question, 📝 a request, or just want to chat? 📩 Reach out to us—we’ll reply within a couple of hours. We won’t ghost you—that’s a promise! 👻❌

📧 Prefer email? Reach us directly at hola@nosehq.com.

Thank you for subscribing! We'll be in touch soon.

There was an issue submitting your email. Please try again.