Das Wichtigste: Eine App für Hautpflegeempfehlungen muss Produkte suchen, ihre Inhaltsstoffe auslesen und Alternativen finden können, die zu den Vorlieben der Nutzer passen. Dieser Leitfaden führt Sie mit The Beauty API und serverseitigen Node.js-Beispielen durch jeden Schritt.
The Beauty API bündelt Produktdatensätze, ihre Zusammensetzung und die Funktionen der Inhaltsstoffe in einer REST-API. Das INCI-Verzeichnis hilft Ihnen, denselben Inhaltsstoff in unterschiedlichen Produkten zu finden. So können Sie Suche und Empfehlungen auf bereits geordneten Datensätzen aufbauen und anschließend entscheiden, wie Sie die Ergebnisse Ihren Nutzern präsentieren.
Schritt 1: Einen API-Schlüssel erhalten
Registrieren Sie sich im Dashboard und erstellen Sie einen Schlüssel. Neue Kunden können mit einer siebentägigen Testphase mit insgesamt 100 Anfragen beginnen. Der ausgewählte kostenpflichtige Tarif startet nach sieben Tagen, sofern Sie nicht kündigen. Abonnements beginnen bei 40 US-Dollar pro Monat mit 10.000 enthaltenen Aufrufen. Jede Anfrage übermittelt den Schlüssel im Header x-api-key:
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide" \
-H "x-api-key: YOUR_API_KEY"
Speichern Sie den Schlüssel serverseitig in einer Umgebungsvariablen. Rufen Sie die API von Ihrem Next.js- oder Express-Server oder Ihrer gehosteten Funktion aus auf, niemals direkt aus dem Browser oder der mobilen App. Diese Funktion vereinfacht die folgenden Aufrufe:
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();
}
Schritt 2: Das ausgewählte Produkt finden
Der Ablauf beginnt häufig mit einem Produkt, das ein Nutzer besitzt oder kaufen möchte. GET /v1/products/search durchsucht Marke und Produktname. Die Präfixsuche eignet sich für die Autovervollständigung:
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"
// }
Die Suche liefert 20 Ergebnisse pro Seite und das Merkmal pagination.has_more. Das Feld image_url stellt ein gehostetes Foto für die Vorschau bereit. Wenn Ihre Anwendung Verpackungen scannt, können Sie in den entsprechenden Tarifen über GET /v1/products/barcode/{barcode} nach UPC oder EAN suchen.
Schritt 3: Den vollständigen Datensatz abrufen
Die Suche liefert einen verkürzten Datensatz für jedes Produkt. Rufen Sie nach der Auswahl den Datensatz mit GET /v1/products/{id} ab, um die für die Empfehlung benötigten Daten zu erhalten:
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
// Beispiel eines Inhaltsstoffs für ein Produkt mit einer einzigen Liste:
// {
// 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",
// ...
// }
Das Feld position bewahrt die Reihenfolge der Inhaltsstoffe innerhalb jeder Liste. concentration enthält eine deklarierte Prozentangabe, sofern verfügbar. Die fünf Felder contains_* beziehen sich auf Duftstoffe, austrocknende Alkohole, Parabene, Sulfate und Silikone. Die Inhaltsstoffdokumentation erklärt die Felder und die Strukturen der Formulierungen.
Schritt 4: Inhaltsstoffe nach den Wünschen Ihrer Nutzer auswählen
Diese Funktion liest einzelne Listen, Abschnitte und Bestandteile von Sets aus. Dabei bleibt erkennbar, zu welchem Abschnitt oder Bestandteil ein Inhaltsstoff gehört. So kann Ihre Oberfläche ihn an der richtigen Stelle anzeigen:
// Bestandteil und Abschnitt jeder Liste beibehalten.
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 ?? [] }];
}
Suchen Sie anschließend nach den Funktionen und Namen, die der Nutzer ausgewählt hat. Geben Sie die passenden Inhaltsstoffe zurück, um jeden Vorschlag erklären zu können:
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);
Die einheitlichen Inhaltsstoffnamen erleichtern den Vergleich zwischen Produkten. Zusätzlich können Sie die jeweilige Bezeichnung vom Etikett anzeigen. Dieses Beispiel sucht nach Namen und Funktionen, die genau mit den ausgewählten Werten übereinstimmen. Mit der Inhaltsstoffsuche lassen sich anhand von Synonymen Kennungen für Produktfilter ermitteln.
Schritt 5: Alternativen vorschlagen
GET /v1/products filtert den Katalog nach category, brand, origin, den fünf Ausschlussmerkmalen und Inhaltsstoffen. Die Inhaltsstofffilter verwenden Kennungen aus GET /v1/ingredients/search:
// 1. Den auszuschließenden Inhaltsstoff finden
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. Duftstofffreie Pflegeprodukte ohne diesen Inhaltsstoff suchen
const alternatives = await beauty(
"/v1/products?category=skincare&fragrance_free=true" +
"&excludes_ingredient=" + coconutOilId + "&page=1"
);
// 3. Vollständige Datensätze mit einem Aufruf abrufen (höchstens 50 Kennungen)
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 akzeptiert bis zu zehn durch Kommas getrennte Kennungen. has_ingredient arbeitet umgekehrt, etwa um Produkte mit Azelainsäure zu finden. Übergeben Sie die Ergebnisse an evaluate, um die passenden Inhaltsstoffe neben jedem Produkt anzuzeigen.
Den Einsatz im Produktivbetrieb vorbereiten
- Speichern Sie Datensätze zwischen. Der Katalog wird mit neuen Versionen aktualisiert. Ein auf Ihre Anwendung abgestimmter Cache reduziert wiederholte Abfragen und beschleunigt die Anzeige.
- Rufen Sie die Datensätze einer Routine gemeinsam ab. Ein Aufruf von
POST /v1/products/batchverarbeitet bis zu 50 Kennungen. Bei kostenpflichtiger Nutzung werden die angefragten Elemente einzeln gezählt. - Erklären Sie die Ergebnisse. Zeigen Sie die jeweiligen Namen und Funktionen mit ihrem Abschnitt oder Set-Bestandteil.
- Halten Sie die Anfragegrenzen ein. Begrenzen Sie die Häufigkeit der Anfragen für die Autovervollständigung und beachten Sie die Limits Ihres Tarifs. Die Dokumentation erklärt ihre Funktionsweise.
- Erklären Sie, warum ein Produkt zu den gewählten Vorlieben passt. Zeigen Sie anhand der Funktionen und Bewertungen, welche Inhaltsstoffe die Kriterien des Nutzers erfüllen. Diese Informationen erlauben keine Aussage darüber, ob ein Produkt aus medizinischer Sicht für eine Person geeignet ist.
Mit den Dateien einen Prototyp entwickeln
Mit den kostenlosen Beispieldaten mit 1.000 Produkten können Sie die Dateien und ihre Bilder offline erkunden. Folgen Sie der mitgelieferten Beschreibung des Schemas: Die Inhaltsstoffverknüpfungen des Archivs verwenden eine numerische ingredient_id, während die API eine UUID in id verwendet. Die API-Dokumentation beschreibt Endpunkte und Fehler im Detail.
Nachvollziehbare Empfehlungen entwickeln
Mit The Beauty API können Sie Produkte finden, ihre Inhaltsstoffe abrufen und Ergebnisse nach den Kriterien Ihrer Nutzer filtern. Bei jedem Vorschlag können Sie zeigen, warum das Produkt ausgewählt wurde, und Ihre Nutzer beim Zusammenstellen ihrer Routine unterstützen.

