À retenir : Une application de recommandation de soins a besoin de rechercher des produits, de lire leurs ingrédients et de trouver des alternatives correspondant aux préférences de l’utilisateur. Ce guide vous accompagne à chaque étape avec The Beauty API et des exemples Node.js côté serveur.

The Beauty API rassemble les fiches produits, leur composition et les fonctions des ingrédients dans une API REST. Le dictionnaire INCI vous aide à retrouver un même ingrédient dans différents produits. Vous pouvez ainsi développer la recherche et les recommandations à partir de fiches déjà organisées, puis choisir comment présenter les résultats à vos utilisateurs.

Étape 1 : obtenir une clé API

Inscrivez-vous dans le tableau de bord et créez une clé. Les nouveaux clients peuvent commencer par un essai de sept jours comprenant 100 requêtes au total. L’offre payante sélectionnée commence à la fin des sept jours, sauf résiliation. Les abonnements commencent à 40 $ US par mois avec 10 000 appels inclus. Chaque requête transmet la clé dans l’en-tête x-api-key :

curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide" \
  -H "x-api-key: YOUR_API_KEY"

Conservez la clé côté serveur, dans une variable d’environnement. Appelez l’API depuis votre serveur Next.js, Express ou votre fonction hébergée, jamais directement depuis le navigateur ou l’application mobile. Cette fonction simplifie les appels suivants :

const BASE = "https://api.thebeautyapi.com";

async function beauty(path, init = {}) {
  const res = await fetch(BASE + path, {
    ...init,
    headers: {
      "x-api-key": process.env.BEAUTY_API_KEY,
      "content-type": "application/json",
      ...(init.headers || {}),
    },
  });
  if (!res.ok) throw new Error(`Beauty API ${res.status} on ${path}`);
  return res.json();
}

Étape 2 : retrouver le produit choisi

Le parcours commence souvent par un produit que l’utilisateur possède ou envisage d’acheter. GET /v1/products/search recherche la marque et le nom du produit, avec une recherche par préfixe adaptée à l’autocomplétion :

const { results } = await beauty(
  "/v1/products/search?q=" + encodeURIComponent("ordinary niacinamide")
);

// results[0] =>
// {
//   id: "06d9476a-397b-5f61-abc8-640b30a9ae23",
//   brand: "The Ordinary",
//   name: "Niacinamide 10% + Zinc 1%",
//   category: "skincare",
//   image_url: "https://images.thebeautyapi.com/06d9476a-....jpg"
// }

La recherche renvoie 20 résultats par page et l’indicateur pagination.has_more. Le champ image_url fournit une photo hébergée pour afficher une miniature. Si votre application scanne les emballages, les offres concernées permettent de rechercher un UPC ou EAN avec GET /v1/products/barcode/{barcode}.

Étape 3 : récupérer la fiche complète

La recherche renvoie une fiche résumée pour chaque produit. Une fois le produit sélectionné, récupérez sa fiche avec GET /v1/products/{id} pour obtenir les données nécessaires à la recommandation :

if (!results.length) throw new Error("No matching products");
const product = await beauty("/v1/products/" + results[0].id);

// product.contains_fragrance       => false
// product.contains_drying_alcohol  => false
// product.contains_parabens        => false
// product.contains_sulfates        => false
// product.contains_silicones       => false
// Exemple d’ingrédient pour un produit à liste unique :
// {
//   position: 1,
//   label_name: "Niacinamide 10.0%",
//   concentration: 10,
//   name: "Niacinamide",
//   rating: "direct actives",
//   irritancy: null,
//   comedogenicity: null,
//   functions: ["smoothing"],
//   other_names: "vitamin B3, nicotinamide",
//   ...
// }

Le champ position conserve l’ordre des ingrédients dans chaque liste. concentration indique un pourcentage déclaré lorsqu’il est disponible. Les cinq champs contains_* portent sur le parfum, les alcools desséchants, les parabènes, les sulfates et les silicones. La documentation des ingrédients explique les champs et les structures de formulation.

Étape 4 : repérer les ingrédients correspondant aux préférences

Cette fonction lit les listes uniques, sections et composants de coffrets. Elle conserve le contexte de chaque correspondance pour que votre interface puisse l’afficher au bon endroit :

// Conserver le composant et la section de chaque liste.
function ingredientLists(record, component = null) {
  if (Array.isArray(record.components)) {
    return record.components.flatMap(part => ingredientLists(part, part.name));
  }
  if (Array.isArray(record.ingredient_sections)) {
    return record.ingredient_sections.map(section => ({
      component,
      section: section.heading,
      ingredients: section.ingredients ?? [],
    }));
  }
  return [{ component, section: null, ingredients: record.ingredients ?? [] }];
}

Recherchez ensuite les fonctions et les noms sélectionnés par l’utilisateur. Renvoyez les ingrédients correspondants afin d’expliquer chaque suggestion :

function evaluate(product, profile) {
  const wanted = new Set((profile.functions ?? []).map(value => value.toLowerCase()));
  const avoid = new Set((profile.avoid ?? []).map(value => value.toLowerCase()));
  const lists = ingredientLists(product).map(list => ({
    component: list.component,
    section: list.section,
    matches: list.ingredients
      .filter(i => (i.functions ?? []).some(value => wanted.has(value.toLowerCase())))
      .map(i => i.name ?? i.label_name),
    avoidMatches: list.ingredients
      .filter(i => [i.name, i.label_name].some(name =>
        typeof name === "string" && avoid.has(name.toLowerCase())
      ))
      .map(i => i.name ?? i.label_name),
  }));
  return { lists };
}

const profile = { functions: ["humectant", "emollient"], avoid: ["Coconut Oil"] };
const assessment = evaluate(product, profile);

Les noms de référence permettent de comparer les produits avec un vocabulaire commun. Le nom déclaré sur l’étiquette peut être affiché à côté. Cet exemple recherche les noms et les fonctions qui correspondent exactement aux valeurs choisies. La recherche d’ingrédients permet de retrouver des identifiants à partir de synonymes pour les filtres de produits.

Étape 5 : proposer des alternatives

GET /v1/products filtre le catalogue par category, brand, origin, par les cinq indicateurs d’exclusion et par ingrédient. Les filtres d’ingrédients utilisent les identifiants obtenus avec GET /v1/ingredients/search :

// 1. Retrouver l’ingrédient à exclure
const ing = await beauty("/v1/ingredients/search?q=coconut%20oil");
if (!ing.results.length) throw new Error("No matching ingredient");
const coconutOilId = ing.results[0].id;

// 2. Rechercher des soins sans parfum qui l’excluent
const alternatives = await beauty(
  "/v1/products?category=skincare&fragrance_free=true" +
  "&excludes_ingredient=" + coconutOilId + "&page=1"
);

// 3. Récupérer les fiches complètes en un appel (50 identifiants maximum)
const ids = alternatives.results.slice(0, 10).map(p => p.id);
const full = ids.length ? await beauty("/v1/products/batch", {
  method: "POST",
  body: JSON.stringify({ ids }),
}) : [];

const recommendations = full.filter(Boolean).map(product => ({
  product,
  assessment: evaluate(product, profile),
}));

excludes_ingredient accepte jusqu’à dix identifiants séparés par des virgules. has_ingredient effectue l’opération inverse, par exemple pour rechercher les produits contenant de l’acide azélaïque. Passez les résultats dans evaluate pour afficher les ingrédients correspondants à côté de chaque produit.

Préparer l’utilisation en production

  • Mettez les fiches en cache. Le catalogue évolue au rythme des versions. Un cache adapté à votre application réduit les consultations répétées et accélère l’affichage.
  • Regroupez les fiches d’une routine. Un appel POST /v1/products/batch récupère jusqu’à 50 identifiants. En usage payant, les éléments demandés sont comptés individuellement.
  • Expliquez les résultats. Affichez les noms et fonctions concernés avec leur section ou leur composant.
  • Respectez les limites de requêtes. Espacez les appels d’autocomplétion et appliquez les limites de votre offre. La documentation décrit leur fonctionnement.
  • Expliquez pourquoi un produit correspond aux préférences choisies. Montrez quels ingrédients répondent aux critères de l’utilisateur, en vous appuyant sur leurs fonctions et leurs évaluations. Ces informations ne permettent pas de déterminer si un produit convient à une personne sur le plan médical.

Prototyper avec les fichiers

L’échantillon gratuit de 1 000 produits permet d’explorer les fichiers et leurs images hors ligne. Suivez le guide du schéma fourni : les liens d’ingrédients de l’archive utilisent un ingredient_id numérique, tandis que l’API utilise un UUID dans id. La documentation de l’API détaille les points d’accès et les erreurs.

Construire une recommandation compréhensible

Avec The Beauty API, vous pouvez retrouver les produits, consulter leurs ingrédients et filtrer les résultats selon les critères choisis par vos utilisateurs. Pour chaque suggestion, vous pouvez montrer ce qui a motivé le choix du produit et aider vos utilisateurs à composer leur routine.