10ML Perfume Finder · para programadores

API de recomendações de perfumes e API de perfumes semelhantes

A API de recomendações de perfumes da 10ML é um conjunto de rotas GET gratuitas, sem chave de API. /similar ordena perfumes por notas e acordes em comum e permite orientá-los para mais frescos, mais doces ou mais escuros. /alternatives devolve alternativas de outras casas. As escolhas com base nos gostos de uma pessoa são disponibilizadas pela ferramenta recommend_perfumes no endpoint MCP.

API de perfumes semelhantes

https://mcp.10ml.com/api/v1/similar

JSON através de GET, OpenAPI 3.1. Gratuita, sem chave de API.

Todos os oito endpoints

API de perfumes semelhantes

GET /api/v1/similar?perfume= recebe o nome de um perfume do índice e devolve os perfumes mais próximos. Cada resultado indica que notas e acordes têm em comum e o grau de proximidade: very close, similar vibe ou same spirit. São apresentados dois resultados de catorze, em versão resumida, de 21 de outubro de 2026.

curl "https://mcp.10ml.com/api/v1/similar?perfume=Creed+Aventus&limit=2"
{
  "results": [
    {
      "perfume": {
        "name": "Club de Nuit Intense Man Parfum",
        "house": "Armaf",
        "family": "Fruity woody"
      },
      "closeness": "very close",
      "shared_notes": ["pineapple", "bergamot", "apple", "black currant", "birch", "jasmine"],
      "shared_accords": ["fruity", "woody", "smoky", "fresh"],
      "why": "shares pineapple, bergamot, apple, black currant"
    },
    {
      "perfume": {
        "name": "Club de Nuit Intense Man EDT",
        "house": "Armaf",
        "family": "Fruity woody"
      },
      "closeness": "similar vibe",
      "shared_notes": ["pineapple", "bergamot", "apple", "black currant", "birch", "jasmine"],
      "shared_accords": ["fruity", "woody", "smoky", "musky"],
      "why": "shares pineapple, bergamot, apple, black currant"
    }
  ],
  "total": 14,
  "source": "10ML Fragrance Index"
}

Usa house= quando um nome for ambíguo, gender= para manter perfumes de homem, de mulher ou unissexo, other_houses_only=true para excluir a casa do perfume inicial e limit= e cursor= para percorrer os resultados.

Orienta o resultado

steer= orienta o resultado numa direção, afastando-o do perfume inicial: fresher, sweeter, darker, lighter, longer_lasting ou more_projection. As duas últimas opções precisam de um perfume que esteja no índice. A justificação de cada resultado indica a direção.

curl "https://mcp.10ml.com/api/v1/similar?perfume=Creed+Aventus&steer=fresher&limit=2"
{
  "target": {
    "name": "Aventus",
    "house": "Creed"
  },
  "results": [
    {
      "perfume": {
        "name": "Club de Nuit Intense Man EDT",
        "house": "Armaf",
        "gender": "men",
        "family": "Fruity woody",
        "accords": ["citrus", "fruity", "smoky"]
      },
      "closeness": "very close",
      "shared_notes": ["pineapple", "bergamot", "apple", "black currant", "birch", "jasmine"],
      "why": "shares pineapple, bergamot, apple, black currant; fresher than the starting point"
    },
    {
      "perfume": {
        "name": "Club de Nuit Intense Man Parfum",
        "house": "Armaf",
        "gender": "men",
        "family": "Fruity woody",
        "accords": ["fruity", "smoky", "woody"]
      },
      "closeness": "very close",
      "shared_notes": ["pineapple", "bergamot", "apple", "black currant", "birch", "jasmine"],
      "why": "shares pineapple, bergamot, apple, black currant; fresher than the starting point"
    }
  ],
  "total": 1989,
  "source": "10ML Fragrance Index"
}

Perfumes semelhantes apenas com base nas notas

Se o perfume não estiver no índice, indica as suas notes= e accords= em vez do nome. O resultado ordena os perfumes do índice com base nessa lista.

curl "https://mcp.10ml.com/api/v1/similar?notes=vanilla,saffron&limit=2"
{
  "target": {
    "name": "your notes",
    "notes": ["vanilla", "saffron"]
  },
  "results": [
    {
      "perfume": {
        "name": "Vanille & Ambre",
        "house": "Berdoues",
        "gender": "unisex",
        "family": "Vanilla amber",
        "accords": ["vanilla", "amber", "sweet"]
      },
      "closeness": "very close",
      "shared_notes": ["vanilla", "saffron"],
      "why": "shares vanilla, saffron"
    },
    {
      "perfume": {
        "name": "Liquid Brun",
        "house": "French Avenue",
        "gender": "unisex",
        "family": "Gourmand spicy",
        "accords": ["warm spicy", "sweet", "vanilla"]
      },
      "closeness": "very close",
      "shared_notes": [],
      "why": "a similar overall profile"
    }
  ],
  "total": 2612,
  "source": "10ML Fragrance Index"
}

Alternativas de outras casas

GET /api/v1/alternatives?perfume= devolve as alternativas dos editores a um perfume famoso, sempre de outras casas, cada uma com uma explicação do que a aproxima. closeness= mantém apenas very close, similar vibe ou same spirit.

curl "https://mcp.10ml.com/api/v1/alternatives?perfume=Creed+Aventus&limit=2"
{
  "total": 5,
  "original": {
    "name": "Creed Aventus",
    "id": "creed-aventus-edp"
  },
  "alternatives": [
    {
      "name": "Armaf Club de Nuit Intense Man",
      "closeness": "very close",
      "why": "Pineapple, lemon, birch smoke and musk make it smell similar, a popular alternative at a different weight.",
      "id": "armaf-club-de-nuit-intense-man-parfum",
      "house": "Armaf",
      "source": "editors"
    },
    {
      "name": "Al Haramain L'Aventure",
      "closeness": "very close",
      "why": "Fruity-smoky opening over woods and musk follows the same blueprint.",
      "id": "al-haramain-laventure",
      "house": "Al Haramain",
      "source": "editors"
    }
  ],
  "source": "10ML Fragrance Index"
}

Recomendações com base no gosto de alguém

As sugestões com base no gosto não vêm de uma rota REST: são fornecidas pela ferramenta recommend_perfumes do servidor MCP. Tem em conta os perfumes de que alguém gosta ou não gosta, as notas que prefere ou evita, bem como o género, a estação, a ocasião, o estilo e a família olfativa, e explica cada sugestão. O endpoint MCP https://mcp.10ml.com/mcp também aceita pedidos JSON-RPC POST simples, por isso qualquer código pode chamá-lo. A resposta abaixo é o structuredContent da resposta, resumido.

curl -X POST https://mcp.10ml.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"recommend_perfumes","arguments":{"likes":["Dior Sauvage"],"avoided_notes":["patchouli"],"season":"summer","limit":2}}}'
{
  "total": 3916,
  "picks": [
    {
      "perfume": {
        "name": "L'Immensité",
        "house": "Louis Vuitton",
        "gender": "men",
        "family": "Aromatic aquatic",
        "accords": ["fresh", "aquatic", "amber"],
        "key_notes": ["sage", "labdanum", "ambroxan", "amber", "ginger"]
      },
      "why": "shares bergamot, labdanum, ambroxan with Sauvage Eau de Parfum; suits summer"
    },
    {
      "perfume": {
        "name": "Jean Lowe Immortel",
        "house": "Maison Alhambra",
        "gender": "men",
        "family": "Fresh aromatic",
        "accords": ["fresh", "aromatic", "woody"],
        "key_notes": []
      },
      "why": "suits summer"
    }
  ],
  "taste": {
    "liked_perfumes": ["Sauvage Eau de Parfum"],
    "liked_notes": [],
    "avoided_notes": ["patchouli"]
  },
  "source": "10ML Fragrance Index"
}

Um assistente faz a mesma chamada por ti: pergunta ao Claude ou ao ChatGPT «o meu perfume de assinatura é Dior Sauvage, o que devo experimentar a seguir?» depois de adicionares o servidor MCP de perfumes.

Filtra por notas, estação e ocasião

GET /api/v1/perfumes apresenta perfumes filtrados por notes_include, notes_exclude, accords, family, gender, season, occasion e style, além de texto livre. O exemplo abaixo inclui apenas perfumes com bergamota e ambroxan.

curl "https://mcp.10ml.com/api/v1/perfumes?notes_include=bergamot,ambroxan&limit=2"
{
  "total": 90,
  "results": [
    {
      "name": "Imagination",
      "house": "Louis Vuitton",
      "family": "Citrus woody",
      "key_notes": ["ginger", "cinnamon", "amberwood", "ambroxan", "citron"]
    },
    {
      "name": "L'Immensité",
      "house": "Louis Vuitton",
      "family": "Aromatic aquatic",
      "key_notes": ["sage", "labdanum", "ambroxan", "amber", "ginger"]
    }
  ],
  "filters": {
    "notes_include": "bergamot, ambroxan"
  },
  "relaxed": false,
  "source": "10ML Fragrance Index"
}

Que rota usar para cada pergunta

A perguntaA chamada
Que perfumes são parecidos com este?GET /api/v1/similar?perfume=
Parecido com este, mas mais fresco, mais doce ou mais escuro?GET /api/v1/similar?perfume=&steer=
Só conheço as notas.GET /api/v1/similar?notes=
Quais são as alternativas de outras casas?GET /api/v1/alternatives?perfume=
Perfumes com estas notas para esta estação?GET /api/v1/perfumes?notes_include=&season=
O que combina com aquilo de que esta pessoa gosta e com o que evita?Ferramenta MCP recommend_perfumes

O índice reúne mais de 6 000 perfumes e 285 notas. A página da API de perfumes documenta cada endpoint, e o guia de alternativas à API Fragrantica reúne outros dados que os programadores procuram.

Perguntas

Existe uma API de recomendações de perfumes?

Sim. A API 10ML Fragrance Index faz recomendações através de três rotas gratuitas: /similar para perfumes semelhantes a um que conheces, /alternatives para alternativas de outras casas e /perfumes para filtrar por notas, estação e ocasião. As escolhas com base nos perfumes e notas de que uma pessoa gosta ou que evita são disponibilizadas pela ferramenta recommend_perfumes em https://mcp.10ml.com/mcp. Não é necessária uma chave de API.

Existe uma API de semelhança entre perfumes?

Sim: GET https://mcp.10ml.com/api/v1/similar?perfume=Creed+Aventus devolve os perfumes mais próximos, cada um com as notas e os acordes que partilha e o grau de proximidade (very close = muito próximo, similar vibe = estilo semelhante ou same spirit = mesma linha). steer= desloca o resultado para fresher, sweeter, darker, lighter, longer_lasting ou more_projection.

Como é medida a semelhança?

Pelas notas, acordes e estilo em comum. Cada resultado indica o que partilha e o grau de proximidade. É uma comparação entre os próprios perfumes, não uma classificação baseada em avaliações.

Posso obter perfumes semelhantes a um perfume que não esteja no índice?

Sim. Em vez de um nome, passa as notas e os acordes para /similar, por exemplo notes=vanilla,saffron, e o índice é ordenado com base nessa lista.

Posso obter recomendações com base nos gostos de um utilizador através de REST?

Atualmente, não através de uma rota REST. A ferramenta recommend_perfumes está no endpoint MCP, que também aceita um POST JSON-RPC simples, como mostra o exemplo acima. As rotas REST abrangem perfumes semelhantes, alternativas e filtros.

É grátis?

Sim. Não precisas de chave de API, conta nem registo. Não há um limite de pedidos fixo (consulta os termos), por isso guarda em cache o que obténs, mantém um ritmo razoável e avisa-nos em contact@10ml.com antes de fazeres pedidos em grande volume.