API Documentation

Introduction

Welcome to the Fragella API documentation. Our API provides programmatic access to a vast database of fragrance information, perfect for powering e-commerce sites, mobile apps, or personal projects. All API endpoints are available under the base URL: https://api.fragella.com/api/v1/.

Authentication

Authentication is handled via an API key. You must include your key in the x-api-key header of every request. Requests without a valid key will be rejected.

You can get your API key by creating an account and visiting your Developer Dashboard.

Endpoints

GET /fragrances

This is the primary endpoint for searching the fragrance database. The search is powered by a case-insensitive, fuzzy-matching algorithm, so an exact query is not required to get relevant results. If the limit parameter is not provided, a default of 10 results will be returned.

Request Parameters

Response Object

Each fragrance object returned by the API contains the following fields:

GET /fragrances/match

Returns fragrances that satisfy all requested accords and notes. You can combine minimum accord percentages with specific top, middle, base, or general notes. Results are ranked by best overall fit. If limit is omitted, the top 10 matches are returned.

Request Parameters

Response Object

Returns an array of standard fragrance objects. See the response object definition under GET /fragrances for the full structure.

GET /fragrances/similar

Finds fragrances that are most similar to a given scent. The API first performs a fuzzy search to find the best match for the provided name, then scores all other fragrances against it based on shared accords (primary) and notes (secondary).

Request Parameters

Response Object

The response is a JSON object with two main keys:

GET /brands/:brandName

Retrieves all fragrances associated with a specific brand. The brand name is provided as a path parameter and is case-insensitive. This is the ideal endpoint for creating brand-specific pages or listings.

Request Parameters

Response Object

Returns an array of standard fragrance objects. See the response object definition under GET /fragrances for the full structure.

GET /notes

Searches the database for individual fragrance notes. This allows you to retrieve details about specific notes, such as their scent profile and how frequently they are used.

Request Parameters

Response Object

GET /accords

Searches the database for fragrance accords (scent families). This is useful for understanding the primary character of different fragrances.

Request Parameters

Response Object

Examples & Responses

Example 1: Searching for Multiple Results

A search for "Viva La Juicy" returns an array of all fragrances matching the term.

curl --request GET \
  --url 'https://api.fragella.com/api/v1/fragrances?search=Viva%20La%20Juicy' \
  --header 'x-api-key: [api-key]'
    

Sample Response: "Viva La Juicy"

[
    {
        "Name": "Viva La Juicy",
        "Brand": "Juicy Couture",
        "Image URL": "https://d2k6fvhyk5xgx.cloudfront.net/images/viva-la-juicy.jpg",
        "Gender": "women",
        "Price": "79.99",
        "Longevity": "56.8%",
        "Sillage": "51.5%",
        
        "Season Ranking": [
           { "name": "spring",  "score": 2.384 },
           { "name": "fall",    "score": 2.066 },
           { "name": "summer",  "score": 2.019 },
           { "name": "winter",  "score": 1.120 }
        ],
       "Occasion Ranking": [
         { "name": "casual",       "score": 2.980 },
         { "name": "night out",    "score": 1.418 },
         { "name": "professional", "score": 1.192 }
       ],

        "General Notes": ["honeysuckle", "vanilla", "caramel", "amber", "sandalwood", "mandarin orange"],
        "Main Accords": ["sweet", "white floral", "caramel", "fruity", "vanilla", "citrus", "woody", "lactonic", "amber", "powdery"],
        "Main Accords Percentage": {
            "sweet": "100%", "white floral": "94%", "caramel": "80%", "fruity": "73%", "vanilla": "66%", "citrus": "61%", "woody": "57%", "lactonic": "57%", "amber": "49%", "powdery": "49%"
        },
        "Notes": {
            "Top": [{"name": "Lemon", "imageUrl": "..."}, {"name": "Bergamot", "imageUrl": "..."}],
            "Middle": [{"name": "Jasmine", "imageUrl": "..."}, {"name": "Coriander", "imageUrl": "..."}],
            "Base": [{"name": "Oakmoss", "imageUrl": "..."}, {"name": "Vetiver", "imageUrl": "..."}]
        },
        "Image Fallbacks": [
            "https://..."
        ],
        "Purchase URL": "https://...",

    },
    {
        "Name": "Viva La Juicy Rose",
        "Brand": "Juicy Couture",
        "Image URL": "https://d2k6fvhyk5xgx.cloudfront.net/images/viva-la-juicy-rose.jpg",
        "Gender": "women",
        "Price": "56.99",
        "Longevity": "55.6%",
        "Sillage": "50.5%",
        "Main Accords": ["rose", "floral", "fresh", "fruity", "citrus", "amber", "sweet", "white floral", "aquatic"],
        "Notes": { /* ... notes object ... */ },
        "Image Fallbacks": [
            "https://..."
        ],
        "Purchase URL": "https://...",
    },
    {
        "Name": "Viva La Juicy Glace",
        "Brand": "Juicy Couture",
        "Image URL": "https://d2k6fvhyk5xgx.cloudfront.net/images/viva-la-juicy-glace.jpg",
        "Gender": "women",
        "Price": "61.99",
        "Longevity": "54.8%",
        "Sillage": "54.5%",
        "Season Ranking": [
           { "name": "spring",  "score": 2.384 },
           { "name": "fall",    "score": 2.066 },
           { "name": "summer",  "score": 2.019 },
           { "name": "winter",  "score": 1.120 }
        ],
       "Occasion Ranking": [
         { "name": "casual",       "score": 2.980 },
         { "name": "night out",    "score": 1.418 },
         { "name": "professional", "score": 1.192 }
       ],
        "Main Accords": ["sweet", "fruity", "vanilla", "fresh", "aquatic", "powdery", "white floral"],
        "Notes": { /* ... notes object ... */ },
        "Image Fallbacks": [
            "https://..."
        ],
        "Purchase URL": "https://...",
    }
    /* ... more results */
]

Example 2: Limiting to a Single Result

Use the limit=1 parameter to get only the most relevant result.

# This request will return only the single most relevant result for "Sauvage"
curl --request GET \
  --url 'https://api.fragella.com/api/v1/fragrances?search=Sauvage&limit=1' \
  --header 'x-api-key: [api-key]'
    

Sample Response: "Sauvage" with limit=1

[
    {
        "Name": "Eau Sauvage",
        "Brand": "Christian Dior",
        "Image URL": "https://d2k6fvhyk5xgx.cloudfront.net/images/eau-sauvage.jpg",
        "Gender": "men",
        "Price": "152.99",
        "Longevity": "55.6%",
        "Sillage": "49.25%",
        "Season Ranking": [
           { "name": "spring",  "score": 2.384 },
           { "name": "fall",    "score": 2.066 },
           { "name": "summer",  "score": 2.019 },
           { "name": "winter",  "score": 1.120 }
        ],
       "Occasion Ranking": [
         { "name": "casual",       "score": 2.980 },
         { "name": "night out",    "score": 1.418 },
         { "name": "professional", "score": 1.192 }
       ],
        "General Notes": ["Hedione", "Galbanum", "Petitgrain", "Vetiver", "Pink Pepper"],
        "Main Accords": ["aromatic", "citrus", "fresh spicy", "woody", "earthy", "mossy", "green", "floral"],
        "Main Accords Percentage": {
            "aromatic": "100%", "citrus": "93%", "fresh spicy": "79%", "woody": "67%", "earthy": "56%", "mossy": "48%", "green": "47%", "floral": "44%"
        },
        "Notes": {
            "Top": [{"name": "Lemon", "imageUrl": "..."}, {"name": "Bergamot", "imageUrl": "..."}],
            "Middle": [{"name": "Jasmine", "imageUrl": "..."}, {"name": "Coriander", "imageUrl": "..."}],
            "Base": [{"name": "Oakmoss", "imageUrl": "..."}, {"name": "Vetiver", "imageUrl": "..."}]
        },
        "Image Fallbacks": [
            "https://..."
        ],
        "Purchase URL": "https://...",
    }
]

Example 3: Accord + Note Matching

Find fragrances that are at least 100 % floral, 90 % fruity, and 80 % citrus, with specific top, middle, and base notes.

curl --request GET \
  --url 'https://api.fragella.com/api/v1/fragrances/match?accords=floral:100,fruity:90,citrus:80&top=Pear,Bitter%20Orange,Bergamot&middle=Freesia&base=Iso%20E%20Super&limit=3' \
  --header 'x-api-key: [api-key]'

Sample Response

[
  {
    "Name": "Versace Dylan Purple",
    "Brand": "Gianni Versace",
    "Image URL": "https://d2k6fvhyk5xgx.cloudfront.net/images/versace-dylan-purple.jpg",
    "Gender": "women",
    "Price": "114.99",
    "Longevity": "51.2%",
    "Sillage": "43.75%",
    "Season Ranking": [
           { "name": "spring",  "score": 2.384 },
           { "name": "fall",    "score": 2.066 },
           { "name": "summer",  "score": 2.019 },
           { "name": "winter",  "score": 1.120 }
        ],
    "Occasion Ranking": [
         { "name": "casual",       "score": 2.980 },
         { "name": "night out",    "score": 1.418 },
         { "name": "professional", "score": 1.192 }
       ],
    "General Notes": ["Pear","Bitter Orange","Bergamot","Freesia","Pomarose","Mahonial","Iso E Super","Ambroxan","Sylkolide","Virginia Cedar","Belambra tree"],
    "Main Accords": ["floral","fruity","citrus","amber","woody","musky","sweet","fresh","aquatic","fresh spicy"],
    "Main Accords Percentage": {
      "floral":"100%","fruity":"93%","citrus":"86%","amber":"77%","woody":"72%","musky":"72%","sweet":"68%","fresh":"61%","aquatic":"61%","fresh spicy":"47%"
    },
    "Notes": { /* ... */ },
    "Image Fallbacks": [
            "https://..."
        ],
    "Purchase URL": "https://...",
  }
]

Example 4: Finding Similar Fragrances

Find the top 3 fragrances most similar to "Sauvage". The API finds the best match for "Sauvage" (which is "Dior Sauvage") and returns the results.

curl --request GET \
  --url 'https://api.fragella.com/api/v1/fragrances/similar?name=Sauvage&limit=3' \
  --header 'x-api-key: [api-key]'

Sample Response

{
  "similar_to": "Dior Sauvage",
  "similar_fragrances": [
    {
      "Name": "Prada Luna Rossa Carbon",
      "SimilarityScore": 0.8912
    },
    {
      "Name": "Versace Dylan Blue",
      "SimilarityScore": 0.7645
    },
    {
      "Name": "Armaf Ventana Pour Homme",
      "SimilarityScore": 0.7499
    }
  ]
}

Example 5: Searching by Brand

Find the top 5 fragrances from the brand "Dior".

curl --request GET \
  --url 'https://api.fragella.com/api/v1/brands/Dior?limit=5' \
  --header 'x-api-key: [api-key]'

Sample Response

[
    {
        "Name": "Chirstian Dior Eau Sauvage Edt",
        "Brand": "Dior",
        "Image URL": "https://d2k6fvhyk5xgx.cloudfront.net/images/chirstian-dior-eau-sauvage-edt.jpg",
        "Gender": "Men",
        "Price": "69.00",
        "Notes": {
            "Top": [{"name": "Lemon", "imageUrl": "..."}, {"name": "Bergamot", "imageUrl": "..."}],
            "Middle": [{"name": "Jasmine", "imageUrl": "..."}, {"name": "Coriander", "imageUrl": "..."}],
            "Base": [{"name": "Oakmoss", "imageUrl": "..."}, {"name": "Vetiver", "imageUrl": "..."}]
        }
        /* ... other fragrance fields ... */
    },
    {
        "Name": "Christian Dior Dior Sauvage Edp",
        "Brand": "Dior",
        "Image URL": "https://d2k6fvhyk5xgx.cloudfront.net/images/christian-dior-dior-sauvage-edp.jpg",
        "Gender": "Men",
        "Price": "85.00",
        "Notes": { /* ... */ }
        /* ... other fragrance fields ... */
    }
    /* ... more results up to the limit ... */
]

Example 6: Searching for Notes

Find notes matching the term "Bergamot", limited to 3 results.

curl --request GET \
  --url 'https://api.fragella.com/api/v1/notes?search=Bergamot&limit=3' \
  --header 'x-api-key: [api-key]'

Sample Response

[
    {
        "name": "Bergamot",
        "occurence": 3549,
        "description": "Bergamot offers a bright, uplifting citrus scent with subtle floral undertones. It's commonly used as a top note to add freshness and vitality to perfumes.",
        "imageUrl": "https://d2k6fvhyk5xgx.cloudfront.net/note_images/Bergamot.png"
    },
    {
        "name": "Sicilian Bergamot",
        "occurence": 55,
        "description": "Sicilian Bergamot is a brighter, slightly sweeter, and less bitter citrus scent compared to Calabrian Bergamot, offering a sparkling and uplifting top note.",
        "imageUrl": "https://d2k6fvhyk5xgx.cloudfront.net/note_images/Sicilian%20Bergamot.png"
    },
    {
        "name": "White Bergamot",
        "occurence": 2,
        "description": "White Bergamot offers a light, fresh, and subtly sweet citrus scent, cleaner and less tart than traditional bergamot, with an ethereal radiance.",
        "imageUrl": "https://d2k6fvhyk5xgx.cloudfront.net/note_images/White%20Bergamot.png"
    }
]

Example 7: Searching for Accords

Find accords matching the term "Woody".

curl --request GET \
  --url 'https://api.fragella.com/api/v1/accords?search=Woody&limit=4' \
  --header 'x-api-key: [api-key]'

Sample Response

[
    {
        "name": "woody",
        "occurence": 8234,
        "description": "Woody accords are rich and warm, often evoking the scent of various woods like sandalwood, cedar, and vetiver. They provide depth and longevity to fragrances, making them a staple in many perfumes."
    }
]

Error Handling

The API uses conventional HTTP status codes to indicate the success or failure of a request.