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

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:

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": { /* ... notes object ... */ }
    },
    {
        "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 ... */ }
    },
    {
        "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 ... */ }
    }
    /* ... 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": "..."}]
        }
    }
]

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": { /* ... */ }
  }
]

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
    }
  ]
}

Error Handling

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