API для разработчиков

Документация API

Бесплатный REST API со структурированными JSON-ответами. Требуется API-ключ (бесплатно). CORS включён. Идеально для приложений, рекомендательных систем или LLM с данными о парфюмерии.

Требуется API-ключCORS включёнJSON-ответы

Базовый URL

https://fraganty.ai

Image formats

Every perfume response includes two image URLs:

image — JPEG with background, ~20-30 KB, always available.
imageTransparent — WebP with transparent background, ~15-50 KB. Returns 404 with header X-Fraganty-Nobg-Status: not-processed for perfumes not yet pre-processed — fall back to image.

Both URLs are immutable, CDN-cached for 1 year, and CORS-enabled for direct use in browsers and native apps.

Аутентификация

Все эндпоинты API требуют бесплатный API-ключ. Включайте его в каждый запрос через заголовок X-API-Key или параметр api_key.

Заголовок

X-API-Key: YOUR_API_KEY

Параметр запроса

?api_key=YOUR_API_KEY

Запросите бесплатный API-ключ на api@fraganty.ai

Playground Pricing llms.txt sitemap.xml

GET/api/perfumes

Список и поиск парфюмов

Параметры

Название	Тип	Описание
q	string	Поиск по названию
brand	string	Фильтр по slug бренда
page	number	Номер страницы (по умолчанию: 1)
limit	number	Результатов на страницу (по умолчанию: 20, макс: 100)

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes?q=rose&limit=5

Ответ

{
  "data": [
    {
      "id": "rose-goldea-kathleen-kye-edition",
      "name": "Rose Goldea Kathleen Kye Edition",
      "brand": "Bvlgari",
      "year": 2021,
      "rating": 4.62,
      "concentration": null,
      "image": "https://img.fraganty.ai/perfume/64818.jpg",
      "imageTransparent": "https://img.fraganty.ai/perfume-nobg/64818.webp",
      "buyUrl": "https://fraganty.ai/goto/rose-goldea-kathleen-kye-edition",
      "accords": [
        { "name": "Rose", "strength": 100, "color": "#C4647C" },
        { "name": "Floral", "strength": 79, "color": "#9E3B52" }
      ]
    }
  ],
  "total": 2460,
  "page": 1,
  "pages": 492
}

GET/api/perfumes/:slug

Получить полную информацию о парфюме, включая ноты, аккорды, оценки, сезоны и похожие парфюмы

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/bleu-de-chanel-eau-de-parfum

Ответ

{
  "id": "bleu-de-chanel-eau-de-parfum",
  "name": "Bleu de Chanel Eau de Parfum",
  "brand": "Chanel",
  "year": 2014,
  "rating": 4.21,
  "concentration": "Eau de Parfum",
  "gender": "masculine",
  "description": "...",
  "image": "https://img.fraganty.ai/perfume/25967.jpg",
  "imageTransparent": "https://img.fraganty.ai/perfume-nobg/25967.webp",
  "buyUrl": "https://fraganty.ai/goto/bleu-de-chanel-eau-de-parfum",
  "notes": {
    "top": [{ "name": "Lemon", "intensity": 80 }],
    "middle": [{ "name": "Cedar", "intensity": 90 }],
    "base": [{ "name": "Sandalwood", "intensity": 85 }]
  },
  "accords": [...],
  "seasons": { "winter": 45, "spring": 60, "summer": 30, "fall": 65 },
  "dayNight": { "day": 55, "night": 70 },
  "similarPerfumes": [...],
  "perfumers": [{ "name": "Olivier Polge" }]
}

GET/api/brands

Список всех брендов с количеством парфюмов

Параметры

Название	Тип	Описание
q	string	Поиск брендов по названию

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/brands

Ответ

{
  "data": [
    { "name": "Guerlain", "slug": "Guerlain", "count": 412 },
    { "name": "Dior", "slug": "Dior", "count": 312 },
    { "name": "Chanel", "slug": "Chanel", "count": 248 }
  ],
  "total": 6619
}

GET/api/notes

Список всех ароматических нот с частотой встречаемости

Параметры

Название	Тип	Описание
limit	number	Ограничить результаты (по умолчанию: все)

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/notes?limit=5

Ответ

{
  "data": [
    { "name": "Musk", "count": 3097 },
    { "name": "Bergamot", "count": 2498 },
    { "name": "Rose", "count": 2460 }
  ],
  "total": 981
}

GET/api/perfumers

Список всех парфюмеров с количеством парфюмов

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumers

Ответ

{
  "data": [
    { "name": "Alberto Morillas", "slug": "alberto-morillas", "count": 45 },
    { "name": "Olivier Polge", "slug": "olivier-polge", "count": 38 }
  ],
  "total": 358
}

GET/api/perfumers/:slug

Информация о парфюмере с его парфюмами (пагинация)

Параметры

Название	Тип	Описание
page	number	Номер страницы (по умолчанию: 1)
limit	number	Результатов на страницу (по умолчанию: 20)

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumers/alberto-morillas

Ответ

{
  "name": "Alberto Morillas",
  "slug": "alberto-morillas",
  "perfumes": {
    "data": [...],
    "total": 45,
    "page": 1,
    "pages": 3
  }
}

GET/api/perfumes/:slug/similar

Find similar perfumes based on accord cosine similarity, note overlap, and curated data

Параметры

Название	Тип	Описание
limit	number	Max results (default 10, max 20)

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/bleu-de-chanel-eau-de-parfum/similar?limit=5

Ответ

{
  "source": { "id": "bleu-de-chanel-eau-de-parfum", "name": "Bleu de Chanel EDP", "brand": "Chanel" },
  "data": [
    {
      "id": "sauvage-dior",
      "name": "Sauvage",
      "brand": "Dior",
      "matchScore": 87,
      "image": "https://img.fraganty.ai/perfume/12345.jpg",
      "imageTransparent": "https://img.fraganty.ai/perfume-nobg/12345.webp",
      "sharedAccords": [{ "name": "Woody", "strength": 95, "color": "#6B4226" }],
      "sharedNotes": ["bergamot", "cedar"],
      "accords": [...]
    }
  ],
  "total": 5
}

GET/api/perfumes/:slug/dupes

Find cheaper alternatives (dupes) to a luxury/premium perfume. Returns perfumes with matching accord/note profiles at a lower price tier.

Параметры

Название	Тип	Описание
limit	number	Max results (default 20, max 50)

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/bleu-de-chanel-eau-de-parfum/dupes?limit=10

Ответ

{
  "source": {
    "id": "bleu-de-chanel-eau-de-parfum",
    "name": "Bleu de Chanel EDP",
    "brand": "Chanel",
    "image": "https://img.fraganty.ai/perfume/25967.jpg",
    "imageTransparent": "https://img.fraganty.ai/perfume-nobg/25967.webp",
    "rating": 4.21
  },
  "data": [
    {
      "id": "oakcha-eastern-bliss",
      "name": "Eastern Bliss",
      "brand": "Oakcha",
      "priceTier": "affordable",
      "matchScore": 87,
      "rating": 4.35,
      "image": "https://img.fraganty.ai/perfume/76543.jpg",
      "imageTransparent": "https://img.fraganty.ai/perfume-nobg/76543.webp",
      "sharedAccords": [{ "name": "Citrus", "strength": 100, "color": "#DAA520" }],
      "sharedNotes": ["bergamot", "cedar"],
      "accords": [...]
    }
  ],
  "total": 15
}

GET/api/perfumes/match

Match perfumes by accords, notes, gender, season, and time of day

Параметры

Название	Тип	Описание
accords	string	Comma-separated accords with optional strength (e.g. woody:80,amber:60)
notes	string	Comma-separated note names (e.g. bergamot,cedar)
gender	string	Filter by gender: masculine, feminine, unisex
season	string	Filter by best season: winter, spring, summer, fall
time	string	Filter by best time: day, night
page	number	Номер страницы (по умолчанию: 1)
limit	number	Results per page (default 20, max 50)

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/perfumes/match?accords=woody:80,amber&notes=bergamot&season=winter

Ответ

{
  "data": [
    {
      "id": "tobacco-vanille",
      "name": "Tobacco Vanille",
      "brand": "Tom Ford",
      "matchScore": 92,
      "rating": 4.31,
      "accords": [...]
    }
  ],
  "filters": { "accords": ["woody:80", "amber"], "notes": ["bergamot"], "season": "winter" },
  "total": 145,
  "page": 1,
  "pages": 8
}

GET/api/accords

List all fragrance accords with perfume counts and colors

Параметры

Название	Тип	Описание
search	string	Filter accords by name
limit	number	Max results (default 50, max 100)

Пример запроса

curl -H "X-API-Key: YOUR_KEY" https://fraganty.ai/api/accords?search=woody

Ответ

{
  "data": [
    { "name": "Woody", "count": 42350, "color": "#6B4226" },
    { "name": "Warm Spicy", "count": 18200, "color": "#A0522D" }
  ],
  "total": 3
}