API Documentation

GET /usage

Check the current status of your API key's monthly quota. This endpoint provides a detailed breakdown of your current plan, usage, and billing cycle.

Request Parameters

This endpoint does not require any query parameters. Authentication is handled via the standard x-api-key header.

Response Object

Example Request & Response

Here is an example of how to call the endpoint and the structure of the data you will receive.

curl --request GET \
  --url 'https://api.fragella.com/api/v1/usage' \
  --header 'x-api-key: [your-api-key]'

import requests

url = "https://api.fragella.com/api/v1/usage"
headers = {"x-api-key": "[your-api-key]"}
response = requests.get(url, headers=headers)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/usage', {
  headers: {'x-api-key': '[your-api-key]'}
}).then(res => console.log(res.data));

<?php
$ch = curl_init("https://api.fragella.com/api/v1/usage");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [your-api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

Sample Response

{
  "plan": "pro",
  "billing_period": {
      "start": "2025-09-01T15:36:00.000Z",
      "end": "2025-10-01T15:35:59.999Z"
  },
  "limit": {
      "total_effective_limit": 11500,
      "base_limit": 20000,
      "carried_over_from_previous_period": 1500
  },
  "usage": {
      "requests_made": 4250,
      "requests_remaining": 7250
  }
}

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 5 results will be returned.

The default limit is intentionally kept small to help prevent abuse, reduce unnecessary load on the API, and keep response times fast. In most fragrance search use cases, users already know the fragrance, brand, note, or accord they are searching for, so a small set of relevant results is usually enough. Clients may increase the limit when they need more results, but most searches should not require paging through a large number of entries.

Request Parameters

Response Object

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

The Fragrance Object

Whether returned inside a flat array or inside the paginated data array, each fragrance object contains the following fields:

The Pagination Object (Only when ?page= is used)

GET /fragrances/:id

Retrieves the full profile of a single fragrance using its unique identifier (slug).

Request Parameters

Example Request

curl --request GET \
  --url 'https://api.fragella.com/api/v1/fragrances/eau-sauvage' \
  --header 'x-api-key: YOUR_API_KEY'

import requests

url = "https://api.fragella.com/api/v1/fragrances/eau-sauvage"
headers = {"x-api-key": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/fragrances/eau-sauvage', {
  headers: {'x-api-key': 'YOUR_API_KEY'}
}).then(res => console.log(res.data));

<?php
$ch = curl_init("https://api.fragella.com/api/v1/fragrances/eau-sauvage");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

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

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

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

Example 2: Limiting to a Single Result

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

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

import requests

url = "https://api.fragella.com/api/v1/fragrances"
querystring = {"search": "Sauvage", "limit": "1"}
headers = {"x-api-key": "[api-key]"}

response = requests.get(url, headers=headers, params=querystring)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/fragrances', {
  params: {search: 'Sauvage', limit: '1'},
  headers: {'x-api-key': '[api-key]'}
}).then(res => console.log(res.data));

<?php
$ch = curl_init("https://api.fragella.com/api/v1/fragrances?search=Sauvage&limit=1");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

Sample Response: "Sauvage" with limit=1

[
    {
        "_id": "EauSauvage",
        "Name": "Eau Sauvage",
        "Brand": "Christian Dior",
        "founder": "Christian Dior",
        "Year": "1966",
        "rating": "4",
        "Popularity": "High",
        "Price Value": "overpriced",
        "Confidence": "high",
        "Country": "France",
        "Image URL": "https://cdn.fragella.com/images/eau-sauvage.jpg",
        "Image URL Transparent": "https://cdn.fragella.com/images/eau-sauvage.webp",
        "Gender": "men",
        "Price": "152.99",
        "Longevity": "Moderate", 
        "Sillage": "Moderate",
        "OilType": "Eau de Toilette",
        "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": "Dominant",
            "citrus": "Dominant",
            "fresh spicy": "Prominent",
            "woody": "Prominent",
            "earthy": "Moderate",
            "mossy": "Subtle",
            "green": "Subtle",
            "floral": "Subtle"
        },
        "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 2.1: Paginated Search

By including the page parameter, the API wraps the results in a pagination object, allowing you to build "Load More" functionality.

curl --request GET \
  --url 'https://api.fragella.com/api/v1/fragrances?search=Sauvage&limit=2&page=1' \
  --header 'x-api-key: [api-key]'

import requests

url = "https://api.fragella.com/api/v1/fragrances"
querystring = {"search": "Sauvage", "limit": "2", "page": "1"}
headers = {"x-api-key": "[api-key]"}

response = requests.get(url, headers=headers, params=querystring)
data = response.json()

# Access the array via data['data']
print(data['data'][0]['Name']) 
# Access pagination info
print(data['pagination']['has_more'])

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/fragrances', {
  params: {search: 'Sauvage', limit: '2', page: '1'},
  headers: {'x-api-key': '[api-key]'}
}).then(response => {
  // Access the array via response.data.data
  console.log(response.data.data[0].Name); 
  // Access pagination info
  console.log(response.data.pagination.has_more); 
});

<?php
$query = http_build_query(["search" => "Sauvage", "limit" => "2", "page" => "1"]);
$ch = curl_init("https://api.fragella.com/api/v1/fragrances?" . $query);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
// Access the array via $data['data']
echo $data['data'][0]['Name'] . "\n";
// Access pagination info
echo ($data['pagination']['has_more'] ? 'true' : 'false');
?>

Sample Response (Paginated)

{
  "data": [
    {
        "_id": "EauSauvage",
        "Name": "Eau Sauvage",
        "Brand": "Christian Dior",
        "founder": "Christian Dior",
        "Year": "1966"
        /* ... remaining fragrance fields ... */
    },
    {
        "_id": "Sauvage",
        "Name": "Sauvage",
        "Brand": "Christian Dior",
        "founder": "Christian Dior",
        "Year": "2015"
        /* ... remaining fragrance fields ... */
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "count": 2,
    "has_more": true
  }
}

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

import requests

url = "https://api.fragella.com/api/v1/fragrances/match"
querystring = {
    "accords": "floral:100,fruity:90,citrus:80",
    "top": "Pear,Bitter Orange,Bergamot",
    "middle": "Freesia",
    "base": "Iso E Super",
    "limit": "3"
}
headers = {"x-api-key": "[api-key]"}

response = requests.get(url, headers=headers, params=querystring)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/fragrances/match', {
  params: {
    accords: 'floral:100,fruity:90,citrus:80',
    top: 'Pear,Bitter Orange,Bergamot',
    middle: 'Freesia',
    base: 'Iso E Super',
    limit: '3'
  },
  headers: {'x-api-key': '[api-key]'}
}).then(response => console.log(response.data));

<?php
$query = http_build_query([
  "accords" => "floral:100,fruity:90,citrus:80",
  "top" => "Pear,Bitter Orange,Bergamot",
  "middle" => "Freesia",
  "base" => "Iso E Super",
  "limit" => "3"
]);

$ch = curl_init("https://api.fragella.com/api/v1/fragrances/match?" . $query);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

Sample Response

[
  {
    "_id": "Versace-Dylan-Purple",
    "Name": "Versace Dylan Purple",
    "Brand": "Gianni Versace",
    "founder": "Gianni Versace",
    "Image URL": "https://cdn.fragella.com/images/versace-dylan-purple.jpg",
    "Image URL Transparent": "https://cdn.fragella.com/images/versace-dylan-purple.webp",
    "Gender": "women",
    "Price": "114.99",
    "Year": "2022",
    "Popularity": "Medium",
    "Price Value": "okay",
    "Confidence": "medium",
    "rating": "4",
    "Country": "Italy",
    "Longevity": "Moderate", 
    "Sillage": "Moderate", 
    "OilType": "Eau de Toilette",
    "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":"Dominant",
      "fruity":"Dominant",
      "citrus":"Dominant",
      "amber":"Prominent",
      "woody":"Prominent",
      "musky":"Prominent",
      "sweet":"Prominent",
      "fresh":"Prominent",
      "aquatic":"Prominent",
      "fresh spicy":"Subtle"
    },
    "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]'

import requests

url = "https://api.fragella.com/api/v1/fragrances/similar"
querystring = {"name": "Sauvage", "limit": "3"}
headers = {"x-api-key": "[api-key]"}

response = requests.get(url, headers=headers, params=querystring)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/fragrances/similar', {
  params: {name: 'Sauvage', limit: '3'},
  headers: {'x-api-key': '[api-key]'}
}).then(response => console.log(response.data));

<?php
$query = http_build_query(["name" => "Sauvage", "limit" => "3"]);
$ch = curl_init("https://api.fragella.com/api/v1/fragrances/similar?" . $query);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

Sample Response

{
  "similar_to": "Dior Sauvage",
  "similar_fragrances": [
    {
      "_id": "Prada-Luna-Rossa-Carbon",
      "Name": "Prada Luna Rossa Carbon",
      "Brand": "Prada",
      "founder": "Mario Prada & Martino Prada",
      "Year": "2017",
      "rating": "4",
      "Country": "Italy",
      "Popularity": "Medium",
      "Price Value": "okay",
      "Confidence": "medium",
      "Longevity": "Long Lasting", 
      "Sillage": "Strong",      
      "OilType": "Eau de Toilette", 
      "General Notes": ["Bergamot", "Lavender", "Ambroxan"],
      "Main Accords": ["aromatic", "fresh spicy", "citrus", "musky"],
      "Notes": { /* ... */ },
      "Purchase URL": "https://...",
      // ... all other fragrance properties ...
      "SimilarityScore": 0.8912
    },
    {
      "_id": "Versace-Dylan-Blue",
      "Name": "Versace Dylan Blue",
      "Brand": "Gianni Versace",
      "founder": "Gianni Versace",
      "Year": "2016",
      "rating": "4",
      "Country": "Italy",
      "Popularity": "Medium",
      "Price Value": "okay",
      "Confidence": "medium",
      "Longevity": "Long Lasting", 
      "Sillage": "Strong",      
      "OilType": "Eau de Toilette", 
      "General Notes": ["Ambroxan", "Grapefruit", "Incense"],
      "Main Accords": ["amber", "aquatic", "citrus", "incense"],
      "Notes": { /* ... */ },
      "Purchase URL": "https://...",
      // ... all other fragrance properties ...
      "SimilarityScore": 0.7645
    }
  ]
}

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

import requests

url = "https://api.fragella.com/api/v1/brands/Dior"
querystring = {"limit": "5"}
headers = {"x-api-key": "[api-key]"}

response = requests.get(url, headers=headers, params=querystring)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/brands/Dior', {
  params: {limit: '5'},
  headers: {'x-api-key': '[api-key]'}
}).then(response => console.log(response.data));

<?php
$ch = curl_init("https://api.fragella.com/api/v1/brands/Dior?limit=5");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

Sample Response

[
    {
        "_id": "Chirstian-Dior-Eau-Sauvage-Edt",
        "Name": "Chirstian Dior Eau Sauvage Edt",
        "Brand": "Dior",
        "founder": "Christian Dior",
        "Year": "1966",
        "rating": "4",
        "Country": "France",
        "Popularity": "Medium",
        "Price Value": "okay",
        "Confidence": "medium",
        "Image URL": "https://cdn.fragella.com/images/chirstian-dior-eau-sauvage-edt.jpg",
        "Image URL Transparent": "https://cdn.fragella.com/images/chirstian-dior-eau-sauvage-edt.webp",
        "Gender": "Men",
        "Price": "69.00",
        "OilType": "",
        "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 ... */
    },
    {
        "_id": "Christian-Dior-Dior-Sauvage-Edp",
        "Name": "Christian Dior Dior Sauvage Edp",
        "Brand": "Dior",
        "founder": "Christian Dior",
        "Image URL": "https://cdn.fragella.com/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]'

import requests

url = "https://api.fragella.com/api/v1/notes"
querystring = {"search": "Bergamot", "limit": "3"}
headers = {"x-api-key": "[api-key]"}

response = requests.get(url, headers=headers, params=querystring)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/notes', {
  params: {search: 'Bergamot', limit: '3'},
  headers: {'x-api-key': '[api-key]'}
}).then(response => console.log(response.data));

<?php
$query = http_build_query(["search" => "Bergamot", "limit" => "3"]);
$ch = curl_init("https://api.fragella.com/api/v1/notes?" . $query);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

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://cdn.fragella.com/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://cdn.fragella.com/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://cdn.fragella.com/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]'

import requests

url = "https://api.fragella.com/api/v1/accords"
querystring = {"search": "Woody", "limit": "4"}
headers = {"x-api-key": "[api-key]"}

response = requests.get(url, headers=headers, params=querystring)
print(response.json())

const axios = require('axios');

axios.get('https://api.fragella.com/api/v1/accords', {
  params: {search: 'Woody', limit: '4'},
  headers: {'x-api-key': '[api-key]'}
}).then(response => console.log(response.data));

<?php
$query = http_build_query(["search" => "Woody", "limit" => "4"]);
$ch = curl_init("https://api.fragella.com/api/v1/accords?" . $query);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: [api-key]"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);
?>

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