API para programadores

Documentação da API

API REST gratuita com respostas JSON estruturadas. Chave API necessária (gratuita). CORS ativado. Perfeito para criar aplicações, motores de recomendação ou alimentar LLMs com dados de fragrâncias.

Chave API necessáriaCORS ativadoRespostas JSON

URL base

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.

Autenticação

Todos os endpoints da API requerem uma chave API gratuita. Inclua-a em cada requisição via cabeçalho X-API-Key ou parâmetro api_key.

Cabeçalho

X-API-Key: YOUR_API_KEY

Parâmetro de consulta

?api_key=YOUR_API_KEY

Solicite sua chave API gratuita em api@fraganty.ai

Playground Pricing llms.txt sitemap.xml

GET/api/perfumes

Listar e pesquisar perfumes

Parâmetros

Nome	Tipo	Descrição
q	string	Pesquisar por nome
brand	string	Filtrar por slug da marca
page	number	Número da página (predefinido: 1)
limit	number	Resultados por página (predefinido: 20, máx: 100)

Exemplo de pedido

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

Resposta

{
  "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

Obter detalhes completos do perfume, incluindo notas, acordes, avaliações, estações e perfumes semelhantes

Exemplo de pedido

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

Resposta

{
  "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

Listar todas as marcas com contagem de perfumes

Parâmetros

Nome	Tipo	Descrição
q	string	Pesquisar marcas por nome

Exemplo de pedido

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

Resposta

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

GET/api/notes

Listar todas as notas olfativas com contagens de frequência

Parâmetros

Nome	Tipo	Descrição
limit	number	Limitar resultados (predefinido: todos)

Exemplo de pedido

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

Resposta

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

GET/api/perfumers

Listar todos os perfumistas com contagem de perfumes

Exemplo de pedido

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

Resposta

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

GET/api/perfumers/:slug

Obter detalhes do perfumista com os seus perfumes (paginado)

Parâmetros

Nome	Tipo	Descrição
page	number	Número da página (predefinido: 1)
limit	number	Resultados por página (predefinido: 20)

Exemplo de pedido

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

Resposta

{
  "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

Parâmetros

Nome	Tipo	Descrição
limit	number	Max results (default 10, max 20)

Exemplo de pedido

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

Resposta

{
  "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.

Parâmetros

Nome	Tipo	Descrição
limit	number	Max results (default 20, max 50)

Exemplo de pedido

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

Resposta

{
  "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

Parâmetros

Nome	Tipo	Descrição
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	Número da página (predefinido: 1)
limit	number	Results per page (default 20, max 50)

Exemplo de pedido

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

Resposta

{
  "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

Parâmetros

Nome	Tipo	Descrição
search	string	Filter accords by name
limit	number	Max results (default 50, max 100)

Exemplo de pedido

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

Resposta

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

Nome

Tipo

Descrição

string

Pesquisar por nome

brand

string

Filtrar por slug da marca

page

number

Número da página (predefinido: 1)

limit

number

Resultados por página (predefinido: 20, máx: 100)

{ "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 }

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

Nome

Tipo

Descrição

string

Pesquisar marcas por nome

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

Nome

Tipo

Descrição

limit

number

Limitar resultados (predefinido: todos)

Nome

Tipo

Descrição

page

number

Número da página (predefinido: 1)

limit

number

Resultados por página (predefinido: 20)

Nome

Tipo

Descrição

limit

number

Max results (default 10, max 20)

{ "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 }

Nome

Tipo

Descrição

limit

number

Max results (default 20, max 50)

{ "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 }

Nome

Tipo

Descrição

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

Número da página (predefinido: 1)

limit

number

Results per page (default 20, max 50)

{ "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 }

Nome

Tipo

Descrição

string

Filter accords by name

limit

number

Max results (default 50, max 100)