API-Referenz
Dokumentation
Alles für die Integration von The Beauty API: 260.000 Produkte, 26.000 Inhaltsstoffdatensätze und 260.000 gehostete Produktbilder über eine einheitliche JSON-Schnittstelle.
Fügen Sie diese englischen Anweisungen in Ihre CLAUDE.md, AGENTS.md oder Editor-Regeln ein, damit Ihr Assistent die API richtig verwendet. Auch verfügbar unter https://thebeautyapi.com/agent.md.
Alle 23 Zeilen anzeigen ▾Ausblenden ▴
# The Beauty API: instructions for coding agents
Base URL: https://api.thebeautyapi.com/v1 (JSON over HTTPS)
Auth: send the header x-api-key: $BEAUTY_API_KEY on every /v1 request. Keep the key in an environment variable, never in code or in this file.
Reference: https://thebeautyapi.com/docs.md | Spec: https://api.thebeautyapi.com/openapi.json | Keys: https://thebeautyapi.com/dashboard
## Endpoints
- Health: GET /health (no key)
- Search products: GET /v1/products/search?q=&page=
- Filter products: GET /v1/products?category=&brand=&origin=&fragrance_free=&alcohol_free=¶ben_free=&sulfate_free=&silicone_free=&has_ingredient=&excludes_ingredient=&page=
- Get a product: GET /v1/products/{id}
- Batch products: POST /v1/products/batch (body {"ids": [uuid, ...]}, max 50)
- Search ingredients: GET /v1/ingredients/search?q=&page=
- Get an ingredient: GET /v1/ingredients/{id}
## Rules
1. Find a product with search, then fetch the full record with GET /v1/products/{id}. Search and filter return slim records (id, brand, name, category, image_url); detail and batch return the full product record. See Ingredients data in the reference for the flat, sectioned and component formats.
2. Every word in q must appear in the product's brand or name, in any order. Send the brand plus the distinctive part of the name ("CeraVe Moisturizing Cream"), never a full retail title. Case, accents and punctuation are ignored; the last word may be partial.
3. When pagination.total is 0 the response carries a no_match object: drop the word no_match.hint names and retry. An empty result does not mean the brand is missing.
4. Pages hold 20 results; page runs 1 to 51 and anything higher returns 400. Read pagination.total and pagination.has_more; above 1,020 matches, narrow with filters instead of paging.
5. Batch takes up to 50 ids and is billed per item (50 ids = 50 calls); unknown ids come back as null in the same positions.
6. Errors are JSON {statusCode, error, message} and message says what to change. 403 is a missing or revoked key. 429 is the rate limit; no rate-limit headers are sent, so back off exponentially.
7. image_url can be null.
8. Deduplication aliases resolve older product and ingredient IDs to surviving records. Unknown or retired ingredient IDs return 400 in ingredient filters.
Auf dieser Seite
Überblick
The Beauty API ist eine REST-API für einen normalisierten Katalog von Kosmetikprodukten und Inhaltsstoffen: 260.000 Produkte, 26.000 Inhaltsstoffdatensätze und 5,5 million Inhaltsstoffvorkommen, alle zwei Monate aktualisiert. Alle Endpunkte nehmen JSON über HTTPS entgegen und geben JSON zurück. Antworten werden mit Brotli oder gzip komprimiert, wenn Ihr Client den Header Accept-Encoding sendet.
https://api.thebeautyapi.com/v1Die API beschreibt ihre eigenen Endpunkte. Eine Anfrage an die Stammadresse oder /v1 liefert ein Übersichtsdokument mit Methode, URL und Kurzbeschreibung jedes Endpunkts sowie Links zu dieser Dokumentation und zur englischsprachigen OpenAPI-3.1-Spezifikation, die unter /openapi.json bereitsteht. Beide Dokumente sind ohne API-Schlüssel zugänglich. Agenten und SDK-Generatoren benötigen daher nur die Basis-URL als Ausgangspunkt.
curl https://api.thebeautyapi.com/ # endpoints, docs_url, openapi_url, authentication
curl https://api.thebeautyapi.com/openapi.json # OpenAPI 3.1 documentDie englische Fassung dieser Referenz ist auch als einzelne Markdown-Datei mit einem Index für Agenten verfügbar. Entwicklungsagenten können sie mit einer einzigen Anfrage lesen, ohne diese HTML-Seite auswerten zu müssen.
Authentifizierung
Jede Anfrage unter /v1 benötigt einen API-Schlüssel im Header x-api-key. Sie verwalten Ihre Schlüssel im Dashboard: Pro Konto sind bis zu 2 aktive Schlüssel möglich, die Sie jederzeit erstellen, anzeigen und widerrufen können. Ein fehlender, ungültiger oder widerrufener Schlüssel führt zu 403. Nur /health, das Übersichtsdokument und /openapi.json sind öffentlich zugänglich.
curl "https://api.thebeautyapi.com/v1/products/search?q=retinol&page=1" \
-H "x-api-key: YOUR_API_KEY"Halten Sie Ihre API-Schlüssel geheim. Rufen Sie die API von Ihrem Server aus auf und hinterlegen Sie niemals einen Schlüssel im Code eines Browsers oder einer mobilen App. Jede Person mit Zugriff darauf kann Ihr Kontingent verbrauchen.
Schnellstart
Speichern Sie Ihren Schlüssel in einer Umgebungsvariablen und durchsuchen Sie den Katalog mit der Programmiersprache Ihrer Wahl.
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const { results, pagination } = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/search",
params={"q": "niacinamide", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json()Endpunkte
Produkte
Suchen Sie ein Produkt nach Namen, filtern Sie den Katalog nach Merkmalen und rufen Sie anschließend den vollständigen Datensatz mit Inhaltsstoffen ab. Barcode- und Stapelabfragen liefern denselben vollständigen Datensatz.
/v1/products/searchProdukte suchen
Suchen Sie nach Marke und Produktname. Jedes Wort in q muss in der Marke oder im Namen vorkommen, unabhängig von der Reihenfolge. Groß- und Kleinschreibung, Akzente und Satzzeichen werden ignoriert (Dr.Jart+ wird zu dr jart). Das letzte Wort darf unvollständig sein (cera findet CeraVe), sodass eine Autovervollständigung möglich ist. Die Antwort enthält Kurzdatensätze. Über den Produktendpunkt erhalten Sie anschließend den vollständigen Datensatz.
| Parameter | Ort | Typ | Erforderlich | Beschreibung |
|---|---|---|---|---|
| q | URL | string | Ja | Suchtext mit 1 bis 200 Zeichen. Verwenden Sie die Marke und den kennzeichnenden Teil des Namens statt des vollständigen Verkaufstitels. |
| page | URL | integer | Nein | Seitennummer von 1 bis 51. Optional, Standardwert 1. Jede Seite enthält 20 Ergebnisse. |
curl "https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/search?q=niacinamide&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/search",
params={"q": "niacinamide", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"results": [
{
"id": "99f9c56e-23ab-5385-8789-7266738c9ad6",
"brand": "Mumuso",
"name": "Niacinamide",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/99f9c56e-23ab-5385-8789-7266738c9ad6.jpg"
},
{
"id": "b7f8c8de-ea5c-5f63-922d-69a299efe7e1",
"brand": "SkinABCs",
"name": "Niacinamide",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/b7f8c8de-ea5c-5f63-922d-69a299efe7e1.jpg"
}
],
"pagination": {
"page": 1,
"has_more": true,
"total": 2009
}
}| Suche | Ergebnis |
|---|---|
| q=CeraVe Moisturizing Cream | ✓CeraVe Moisturizing Cream und Varianten (Baby, Intensive, Psoriasis, For Dry To Very Dry Skin…). |
| q=CeraVe Moisturizing Cream Daily Face and Body Moisturizer for Dry Skin | ✗Kein gespeichertes Produkt entspricht allen Begriffen. no_match.hint nennt das unspezifischste Wort zum Entfernen; no_match.terms zeigt die Trefferzahl je Wort. |
| q=Laneige sleeping mask | ✓Alle Nachtmasken von LANEIGE (Water, Lip, Cica, Time Freeze…). |
Hinweise:
- 01Ein leeres
results-Array bedeutet, dass kein Produkt alle gesuchten Wörter enthält. Es bedeutet nicht, dass die Marke fehlt. - 02Wenn
total0 ist, enthält die Antwortno_match:hintnennt das zu entfernende Wort,termsdie Trefferzahl je Wort. Entfernen Sie das Wort ohne Treffer (Tippfehler, Positionsnummer auf einem Beleg) oder das unspezifischste Wort (serum, cream, SPF) und versuchen Sie es erneut. - 03Verwenden Sie von Anfang an die Marke und einen kurzen Produktnamen, niemals den vollständigen Titel eines Verkaufseintrags.
- 04Jedes Zeichen, das weder Buchstabe noch Ziffer ist, trennt Wörter: Aus
Oil-Freewerdenoilundfree, aus10%wird10. Nur die ersten 10 Wörter zählen. - 05Eine Suche ohne Buchstaben oder Ziffern liefert
400.
/v1/productsProdukte filtern
Finden Sie Produkte nach Kategorie, Marke, Herkunftsland, Formulierungsmerkmalen und Inhaltsstoffen. Alle Filter werden mit AND verknüpft: Jede Bedingung muss erfüllt sein. Die Antwort enthält dieselben Kurzdatensätze wie die Suche.
| Parameter | Ort | Typ | Erforderlich | Beschreibung |
|---|---|---|---|---|
| category | URL | string | Nein | Exakte Übereinstimmung mit der gespeicherten Kategorie, unter Beachtung der Groß- und Kleinschreibung: skincare, suncare, makeup, haircare, body/bath, fragrance, other, deodorants, oral-care, tools_accessories oder devices. Andere Werte liefern eine leere Seite mit no_match, keinen Fehler. |
| brand | URL | string | Nein | Markenname. Groß- und Kleinschreibung, Akzente, Satzzeichen und Leerzeichen werden ignoriert: supergoop findet Supergoop!, sk ii findet SK-II. Tippfehler werden nicht korrigiert. Verwenden Sie die Suche, um den gespeicherten Namen zu finden. |
| origin | URL | string | Nein | Exakte Übereinstimmung mit dem gespeicherten Herkunftsland der Marke, unter Beachtung der Groß- und Kleinschreibung, beispielsweise USA, South Korea, France, United Kingdom. Bei ~57% der Produkte ist diese Angabe unbekannt; diese Produkte entsprechen keinem origin-Wert. |
| fragrance_free | URL | boolean | Nein | Formulierungsmerkmale. Ebenfalls verfügbar: alcohol_free, paraben_free, sulfate_free, silicone_free. |
| has_ingredient | URL | uuid | Nein | Nur Produkte mit diesem Inhaltsstoff. Die IDs erhalten Sie über die Inhaltsstoffendpunkte. |
| excludes_ingredient | URL | uuid list | Nein | Produkte, die keinen dieser Inhaltsstoffe enthalten. Bis zu 10 durch Kommas getrennte IDs. |
| page | URL | integer | Nein | Seitennummer von 1 bis 51. Optional, Standardwert 1. Jede Seite enthält 20 Ergebnisse. |
curl "https://api.thebeautyapi.com/v1/products?category=skincare&fragrance_free=true&has_ingredient=a1526dea-37d1-5904-9106-be583378339b&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products?category=skincare&fragrance_free=true&has_ingredient=a1526dea-37d1-5904-9106-be583378339b&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products",
params={"category": "skincare", "fragrance_free": True, "has_ingredient": "a1526dea-37d1-5904-9106-be583378339b", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"results": [
{
"id": "a70e8e5b-5905-57f9-8e8a-acd9feaa43c2",
"brand": "IOPE",
"name": "Bio Essence Intensive Conditioning",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/a70e8e5b-5905-57f9-8e8a-acd9feaa43c2.jpg"
},
{
"id": "7ebe8574-c405-51e0-a597-f9ce33bc7b95",
"brand": "Biologique Recherche",
"name": "Lotion P50 T",
"category": "skincare",
"image_url": "https://images.thebeautyapi.com/7ebe8574-c405-51e0-a597-f9ce33bc7b95.jpg"
}
],
"pagination": {
"page": 1,
"has_more": true,
"total": 11295
}
}Hinweise:
- 01Eine unbekannte oder entfernte Inhaltsstoff-ID liefert in beiden Inhaltsstofffiltern
400. Gespeicherte Aliasse verweisen auf den nach der Dublettenbereinigung beibehaltenen Inhaltsstoff; siehe Inhaltsstoffdaten. - 02Wenn
total0 ist, erklärtno_match.hint, warum kein Produkt den angegebenen Filtern entspricht.
/v1/products/{id}Produkt abrufen
Der vollständige Datensatz: Marke, Kategorie, Herkunft, Formulierungsmerkmale, gehostete Bild-URL und Inhaltsstoffe in der Reihenfolge auf dem Etikett mit den verfügbaren Namen, Funktionen, Bewertungen und chemischen Kennungen.
| Parameter | Ort | Typ | Erforderlich | Beschreibung |
|---|---|---|---|---|
| id | Pfad | uuid | Ja | Produkt-ID. |
curl https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23 \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/06d9476a-397b-5f61-abc8-640b30a9ae23",
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"id": "06d9476a-397b-5f61-abc8-640b30a9ae23",
"brand": "The Ordinary",
"name": "Niacinamide 10% + Zinc 1%",
"image_url": "https://images.thebeautyapi.com/06d9476a-397b-5f61-abc8-640b30a9ae23.jpg",
"category": "skincare",
"origin": "Canada",
"contains_fragrance": false,
"contains_drying_alcohol": false,
"contains_parabens": false,
"contains_sulfates": false,
"contains_silicones": false,
"product_type": "unknown",
"subcategory": "Serum",
"size": null,
"packaging": null,
"pack_count": null,
"shade_name": null,
"benefits": null,
"directions": null,
"warnings": null,
"ingredients_raw": "Aqua (Water), Niacinamide 10.0%, Pentylene Glycol, Zinc Pca 1.0%, Dimethyl Isosorbide, Tamarindus Indica Seed Gum, Xanthan Gum, Isoceteth-20, Ethoxydiglycol, Phenoxyethanol, Chlorphenesin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": ["solvent"],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Niacinamide 10.0%",
"concentration": 10,
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}
]
}Hinweise:
- 01Vollständige Datensätze enthalten
ingredients_rawauf Produktebene, Produktmetadaten und Inhaltsstoffe als einfache Liste, Abschnitte oder Komponenten. Manche Inhaltsstoffe sind keinem Eintrag im Verzeichnis zugeordnet; dessen Felder sind dann null. Unbekannte Merkmale sind ebenfalls null. Siehe Inhaltsstoffdaten. - 02Aliasse aus der Dublettenbereinigung erhalten frühere IDs: Eine Abfrage über einen Alias liefert das beibehaltene Produkt und dessen ID.
- 03
concentrationwird nur angegeben, wenn der Hersteller sie veröffentlicht. Sie wird niemals geschätzt. - 04Kein Tarif enthält Barcodes in dieser Antwort. Tarife mit Barcode finden Produkte anhand einer GTIN über die Barcode-Suche.
/v1/products/barcode/{barcode}Nach Barcode suchen
Finden Sie ein Produkt anhand eines gescannten Codes oder eines Codes aus Ihrem Katalog (UPC-A, EAN-13, GTIN-8/14). Sie erhalten denselben vollständigen Datensatz wie beim Abruf über die Produkt-ID. Codes für Einzelartikel, Mehrfachpackungen und Varianten (Farbton, Duft, Größe derselben Produktlinie) werden unterstützt. Mit führenden Nullen ergänzte GTIN-Formen desselben Codes (UPC-A, EAN-13, GTIN-14) sind gleichwertig. Nur mit Barcode-Tarifen verfügbar.
| Parameter | Ort | Typ | Erforderlich | Beschreibung |
|---|---|---|---|---|
| barcode | Pfad | string | Ja | 8 bis 14 Ziffern ohne Leerzeichen oder Bindestriche (^[0-9]{8,14}$). |
curl https://api.thebeautyapi.com/v1/products/barcode/769915195941 \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/products/barcode/769915195941",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/products/barcode/769915195941",
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"id": "06d9476a-397b-5f61-abc8-640b30a9ae23",
"brand": "The Ordinary",
"name": "Niacinamide 10% + Zinc 1%",
"image_url": "https://images.thebeautyapi.com/06d9476a-397b-5f61-abc8-640b30a9ae23.jpg",
"category": "skincare",
"origin": "Canada",
"contains_fragrance": false,
"contains_drying_alcohol": false,
"contains_parabens": false,
"contains_sulfates": false,
"contains_silicones": false,
"product_type": "unknown",
"subcategory": "Serum",
"size": null,
"packaging": null,
"pack_count": null,
"shade_name": null,
"benefits": null,
"directions": null,
"warnings": null,
"ingredients_raw": "Aqua (Water), Niacinamide 10.0%, Pentylene Glycol, Zinc Pca 1.0%, Dimethyl Isosorbide, Tamarindus Indica Seed Gum, Xanthan Gum, Isoceteth-20, Ethoxydiglycol, Phenoxyethanol, Chlorphenesin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": ["solvent"],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Niacinamide 10.0%",
"concentration": 10,
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}
]
}Hinweise:
- 01Die Antwort enthält niemals die Liste der Barcodes eines Produkts. Die API findet ein Produkt anhand eines Codes; sie ermöglicht keine Auflistung der Codes. Die vollständige GTIN-Liste ist ausschließlich in der lizenzierten Datenbank enthalten.
- 02
403, wenn Ihr Tarif diese Funktion nicht enthält (Meldung: “Your current plan does not include Barcode Lookup access.”).404bei fehlendem Treffer.400bei ungültigem Format. - 03Zählt als 1 abrechenbarer Aufruf.
- 04Rund 61% der Produkte im Katalog haben derzeit einen Code. Die Abdeckung wächst mit weiteren Aktualisierungen.
/v1/products/batchMehrere Produkte abrufen
Rufen Sie bis zu 50 vollständige Datensätze mit einer Anfrage ab. Das Antwort-Array enthält genauso viele Einträge wie die gesendete ID-Liste und behält deren Reihenfolge bei. Jede unbekannte ID wird durch null dargestellt.
| Parameter | Ort | Typ | Erforderlich | Beschreibung |
|---|---|---|---|---|
| ids | Anfragekörper | uuid[] | Ja | 1 bis 50 Produkt-IDs. |
curl -X POST https://api.thebeautyapi.com/v1/products/batch \
-H "x-api-key: $BEAUTY_API_KEY" \
-H "content-type: application/json" \
-d '{"ids": ["06d9476a-397b-5f61-abc8-640b30a9ae23", "00000000-0000-0000-0000-000000000000"]}'const res = await fetch("https://api.thebeautyapi.com/v1/products/batch", {
method: "POST",
headers: {
"x-api-key": process.env.BEAUTY_API_KEY,
"content-type": "application/json",
},
body: JSON.stringify({ ids: ["06d9476a-397b-5f61-abc8-640b30a9ae23", "00000000-0000-0000-0000-000000000000"] }),
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.thebeautyapi.com/v1/products/batch",
json={"ids": ["06d9476a-397b-5f61-abc8-640b30a9ae23", "00000000-0000-0000-0000-000000000000"]},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json()[
{
"id": "06d9476a-397b-5f61-abc8-640b30a9ae23",
"brand": "The Ordinary",
"name": "Niacinamide 10% + Zinc 1%",
"image_url": "https://images.thebeautyapi.com/06d9476a-397b-5f61-abc8-640b30a9ae23.jpg",
"category": "skincare",
"origin": "Canada",
"contains_fragrance": false,
"contains_drying_alcohol": false,
"contains_parabens": false,
"contains_sulfates": false,
"contains_silicones": false,
"product_type": "unknown",
"subcategory": "Serum",
"size": null,
"packaging": null,
"pack_count": null,
"shade_name": null,
"benefits": null,
"directions": null,
"warnings": null,
"ingredients_raw": "Aqua (Water), Niacinamide 10.0%, Pentylene Glycol, Zinc Pca 1.0%, Dimethyl Isosorbide, Tamarindus Indica Seed Gum, Xanthan Gum, Isoceteth-20, Ethoxydiglycol, Phenoxyethanol, Chlorphenesin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": ["solvent"],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Niacinamide 10.0%",
"concentration": 10,
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}
]
},
null
]Hinweise:
- 01Jeder Eintrag, der nicht null ist, verwendet das Format eines vollständigen Produktdatensatzes einschließlich der unter Inhaltsstoffdaten beschriebenen Strukturen und Aliasse.
- 02Senden Sie JSON mit
Content-Type: application/json. Ein fehlender oder nicht unterstützter Inhaltstyp führt zu415. - 03Ein ungültiger JSON-Anfragekörper oder ein fehlendes, leeres, mehr als 50 Einträge umfassendes oder Nicht-UUID-Werte enthaltendes
ids-Feld führt zu400. - 04Bei kostenpflichtigen Tarifen wird je Eintrag abgerechnet: 50 IDs zählen als 50 Aufrufe. Der Antwortheader
X-Item-Countgibt die abrechenbare Anzahl an. - 05Für die Anfragerate und das Testkontingent von 100 Anfragen zählt ein Stapel als eine Anfrage. Während des Tests entstehen keine Mehrverbrauchskosten.
Endpunkte
Inhaltsstoffe
Durchsuchen Sie das Inhaltsstoffverzeichnis nach INCI-Namen oder Synonymen und rufen Sie den vollständigen Datensatz ab: Funktionen, Bewertungen zu Reizpotenzial und Komedogenität sowie chemische Kennungen. Verwenden Sie die IDs in den Produktfiltern.
/v1/ingredients/searchInhaltsstoffe suchen
Durchsuchen Sie 26.000 Einträge im Inhaltsstoffverzeichnis nach normalisiertem INCI-Namen oder bekanntem Synonym. Verwenden Sie die gefundenen IDs in Produktfiltern oder zum Abruf eines Inhaltsstoffdatensatzes.
| Parameter | Ort | Typ | Erforderlich | Beschreibung |
|---|---|---|---|---|
| q | URL | string | Ja | Suchtext mit 1 bis 200 Zeichen. |
| page | URL | integer | Nein | Seitennummer von 1 bis 51. Optional, Standardwert 1. Jede Seite enthält 20 Ergebnisse. |
curl "https://api.thebeautyapi.com/v1/ingredients/search?q=niacinamide&page=1" \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/ingredients/search?q=niacinamide&page=1",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/ingredients/search",
params={"q": "niacinamide", "page": 1},
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"results": [
{
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"other_names": "vitamin B3, nicotinamide",
"rating": "direct actives"
},
{
"id": "e0788047-91e6-5041-aedc-54d2d8c4c025",
"name": "Niacinamide Retinoate",
"other_names": null,
"rating": null
},
{
"id": "d38b26f6-cdf1-53fd-ae1b-b0de434064af",
"name": "Niacinamide (NIA-114™)",
"other_names": null,
"rating": null
},
{
"id": "83b58d16-4775-5b15-91cd-04e1ff64be99",
"name": "Niacinamide Polypeptide",
"other_names": null,
"rating": null
},
{
"id": "dd34f14a-7142-5884-bb1e-dd78cc03ef84",
"name": "Niacinamide (Soy-Derived)",
"other_names": null,
"rating": null
},
{
"id": "80df0bd2-443b-590c-a7fd-45149f9034f6",
"name": "Niacinamide/Yeast Polypeptide",
"other_names": null,
"rating": null
},
{
"id": "5461bbea-efdb-567a-9ce5-4c9fdc3b22c2",
"name": "Niacinamide (Skin-Conditioner)",
"other_names": null,
"rating": null
},
{
"id": "e24c8441-d4c6-5d35-aeb1-d215a506a899",
"name": "Methyl Niacinamide Chloride",
"other_names": null,
"rating": null
},
{
"id": "a87fb600-b56c-52dc-b13e-e86acb56ff4b",
"name": "Naturally Derived Niacinamide",
"other_names": null,
"rating": null
},
{
"id": "f53466cb-ee15-575e-b226-79c4ad90a6d9",
"name": "Biotin/Folic Acid/Cyanocobalamin/Niacinamide/Pantothenic Acid/Pyridoxine/Riboflavin/Thiamine/Yeast Polypeptides",
"other_names": null,
"rating": null
}
],
"pagination": {
"page": 1,
"has_more": false,
"total": 10
}
}/v1/ingredients/{id}Inhaltsstoff abrufen
Der vollständige wissenschaftliche Inhaltsstoffdatensatz: normalisierter Name, Synonyme, Funktionen, Bewertungen zu Reizpotenzial und Komedogenität sowie CAS-, EG-, IUPAC- und Ph.-Eur.-Kennungen.
| Parameter | Ort | Typ | Erforderlich | Beschreibung |
|---|---|---|---|---|
| id | Pfad | uuid | Ja | Inhaltsstoff-ID. |
curl https://api.thebeautyapi.com/v1/ingredients/a1526dea-37d1-5904-9106-be583378339b \
-H "x-api-key: $BEAUTY_API_KEY"const res = await fetch(
"https://api.thebeautyapi.com/v1/ingredients/a1526dea-37d1-5904-9106-be583378339b",
{ headers: { "x-api-key": process.env.BEAUTY_API_KEY } },
);
const data = await res.json();import os, requests
res = requests.get(
"https://api.thebeautyapi.com/v1/ingredients/a1526dea-37d1-5904-9106-be583378339b",
headers={"x-api-key": os.environ["BEAUTY_API_KEY"]},
)
data = res.json(){
"id": "a1526dea-37d1-5904-9106-be583378339b",
"name": "Niacinamide",
"rating": "direct actives",
"irritancy": null,
"comedogenicity": null,
"functions": ["smoothing"],
"cas_number": "98-92-0",
"ec_number": "202-713-4",
"ph_eur_name": "Nicotinamidum",
"iupac_name": "3-Pyridinecarboxamide",
"other_names": "vitamin B3, nicotinamide",
"category": null
}Hinweise:
- 01Gespeicherte Aliasse verweisen auf den nach der Dublettenbereinigung beibehaltenen Datensatz. Eine ersatzlos entfernte ID liefert
410, eine unbekannte ID404.
Endpunkte
Referenz
Dienststatus und allgemeine Funktionen der Endpunkte: Paginierung, Fehler, Tarifgrenzen, Bilder, Barcodes und Versionierung.
/healthDienststatus
Prüft, ob der Dienst antwortet, und nennt Größe und Erstellungsdatum des aktuell über die API verfügbaren Katalogs. built_at (JJJJ-MM-TT, UTC) gibt an, wann diese Version vorbereitet wurde. API-Aktualisierungen erfolgen unabhängig von der herunterladbaren Datenbank; siehe Änderungsverlauf. Wie das Übersichtsdokument unter der Stammadresse und die Spezifikation /openapi.json ist dieser Endpunkt ohne API-Schlüssel zugänglich.
Keine Authentifizierung erforderlich.
curl https://api.thebeautyapi.com/healthconst res = await fetch("https://api.thebeautyapi.com/health");
const data = await res.json();import requests
res = requests.get("https://api.thebeautyapi.com/health")
data = res.json(){
"status": "ok",
"products": 272761,
"ingredients": 26420,
"built_at": "2026-11-09"
}Paginierung
Endpunkte mit Listen liefern 20 Ergebnisse pro Seite. Senden Sie page (1 bis 51) und lesen Sie das Objekt pagination; fragen Sie weitere Seiten ab, solange has_more true ist. total zählt die Treffer über alle Seiten hinweg. So können Sie einen eindeutigen Treffer von mehreren möglichen Produkten unterscheiden. Für Seiten über 51 gibt die API 400 zurück. Bei mehr als 1.020 Treffern, also 20 × 51, grenzen Sie die Suche mit Filtern ein.
"pagination": { "page": 2, "has_more": true, "total": 47 }Fehler
Fehler verwenden die üblichen HTTP-Statuscodes und einen einheitlichen JSON-Antwortkörper:
{
"statusCode": 404,
"error": "Not Found",
"message": "No product with id 00000000-0000-4000-8000-000000000000"
}Steuern Sie die Fehlerbehandlung anhand von statusCode. Das Feld message erläutert den Fehler und hilft bei der Diagnose. Beispielsweise nennt ein nicht unterstützter Parameter die erlaubten Parameter und den passenden Endpunkt:
{
"statusCode": 400,
"error": "Bad Request",
"message": "Unknown query parameters 'name', 'limit'. GET /v1/products accepts: category, brand, origin, fragrance_free, alcohol_free, paraben_free, sulfate_free, silicone_free, has_ingredient, excludes_ingredient, page. To find products by name, use GET /v1/products/search?q=<brand and product name>. Pages are fixed at 20 results; use page=2, page=3, … for more."
}| Status | Bedeutung |
|---|---|
| 400 | Die Anfrage kann nicht verarbeitet werden: nicht unterstützter Parameter, ungültige ID oder Barcode-Form, unbekannter oder entfernter Inhaltsstoff im Filter, Seite über 51, leerer oder zu langer Suchtext oder ungültige Stapelabfrage. Die Meldung nennt das betroffene Feld und bei unbekannten Parametern die erlaubten Parameter. Korrigieren Sie die Anfrage, bevor Sie sie erneut senden. |
| 402 | Testzeitraum abgelaufen oder Zahlung erforderlich. Prüfen Sie Ihren Zahlungsstatus im Dashboard, bevor Sie es erneut versuchen. |
| 403 | API-Schlüssel fehlt, ist ungültig oder deaktiviert, oder die Barcode-Suche ist in Ihrem Tarif nicht enthalten. |
| 404 | Die Anfrage ist gültig, liefert aber keinen Treffer: kein Produkt oder Inhaltsstoff mit dieser ID, kein Produkt zu diesem Barcode oder eine nicht vorhandene Endpunktadresse. Die Meldung nennt die ID oder den Code. |
| 410 | Diese Inhaltsstoff-ID wurde ersatzlos entfernt. Suchen Sie nach einem aktuellen Eintrag im Verzeichnis. |
| 413 | Der Anfragekörper überschreitet 1 MB. Nur der Stapelendpunkt liest einen Anfragekörper. 50 UUIDs benötigen weniger als 3 KB, sodass eine gültige Stapelabfrage diese Grenze nicht erreicht. |
| 415 | Der Stapelabfrage fehlt der Content-Type-Header oder der Inhaltstyp wird nicht unterstützt. Senden Sie Content-Type: application/json. |
| 429 | Testkontingent ausgeschöpft (zum Wechsel auf einen kostenpflichtigen Tarif klicken Sie im Dashboard auf „Convert to paid plan“), Anfragerate überschritten oder monatliche Obergrenze erreicht. Bei kostenpflichtigen Tarifen werden Aufrufe über das enthaltene Kontingent hinaus als Mehrverbrauch berechnet. Erst eine höhere Obergrenze, die dem Schutz vor Missbrauch dient, blockiert weitere Aufrufe. Gateway-Obergrenzen werden am 1. des Monats (UTC) zurückgesetzt; kostenpflichtige Kontingente folgen Ihrem Abrechnungsmonat. Das Testkontingent wird nicht zurückgesetzt. Erfolgreiche Testanfragen enthalten X-Trial-Requests-Remaining. Vergrößern Sie bei einer überschrittenen Anfragerate die Abstände zwischen erneuten Versuchen; nutzen Sie bei ausgeschöpftem Testkontingent das Dashboard. |
| 500 | Interner Fehler auf unserer Seite. Sie können die Anfrage erneut senden. |
| 503 | Die Zugriffsprüfung ist vorübergehend nicht verfügbar. Versuchen Sie es nach einer Pause erneut und verlängern Sie die Wartezeit zwischen weiteren Versuchen. |
| 504 | Der API-Server hat nicht rechtzeitig geantwortet. Sie können die Anfrage mit zunehmenden Wartezeiten erneut senden. |
Anfrageraten und Kontingente
Neue Konten erhalten sieben Testtage mit insgesamt 100 Anfragen, gemeinsam für alle Schlüssel. Sobald die 100 Anfragen verbraucht sind, liefert die API 429, bis Sie auf einen kostenpflichtigen Tarif umstellen oder der Testzeitraum endet. Während des Tests werden keine Mehrverbrauchskosten berechnet. Die monatliche Grundgebühr wird im Voraus erhoben; Aufrufe über das enthaltene Kontingent hinaus kosten jeweils 0,02 $ und werden am Ende des Abrechnungsmonats berechnet. Bei kostenpflichtigen Tarifen zählt jeder angeforderte Eintrag einer Stapelabfrage als ein Aufruf, während im Testzeitraum der gesamte Stapel als eine Anfrage zählt. Das kostenpflichtige Kontingent wird zu Beginn jedes Abrechnungsmonats zurückgesetzt.
| Tarif | Preis | Enthaltene Aufrufe pro Monat | Anfragerate |
|---|---|---|---|
| Starter | 40 $/Monat | 10.000 | 10 Anfragen/s, kurzzeitig 20 |
| Starter + Barcode | 60 $/Monat | 10.000 | 10 Anfragen/s, kurzzeitig 20 |
| Pro | 200 $/Monat | 100.000 | 25 Anfragen/s, kurzzeitig 50 |
| Pro + Barcode | 300 $/Monat | 100.000 | 25 Anfragen/s, kurzzeitig 50 |
Anfragen, die die zulässige Anfragerate überschreiten, erhalten 429. Es werden keine Header zur Anfragerate gesendet. Verlängern Sie die Wartezeit zwischen erneuten Versuchen schrittweise (exponentieller Backoff).
Produktdaten
- Antworten für einzelne Produkte, Stapelabfragen und Barcode-Abfragen enthalten die folgenden Felder. Fehlende Werte sind null.
- Such- und Filterergebnisse enthalten
id,brand,name,categoryundimage_url.
| Feld | Typ | Bedeutung |
|---|---|---|
| product_type | string | null | Produktstruktur, beispielsweise ein Einzelartikel oder ein Set. |
| subcategory | string | null | Genauere Einordnung innerhalb der Kategorie. |
| size | string | null | Angegebene Größe oder Füllmenge mit Einheit oder Beschreibung der Mehrfachpackung. |
| packaging | string | null | Beschreibung der Verpackung, etwa Flasche, Tube oder Tiegel. |
| pack_count | integer | null | Anzahl der Artikel in der Packung, sofern bekannt. |
| shade_name | string | null | Für das Produkt angegebener Farbtonname. |
| benefits | string | null | Angegebene Produktvorteile, sofern verfügbar. |
| directions | string | null | Anwendungshinweise. Der Text kann Zeilenumbrüche enthalten. |
| warnings | string | null | Warnhinweise zum Produkt. Der Text kann Zeilenumbrüche enthalten. |
| ingredients_raw | string | null | Inhaltsstofftext aus dem Produkteintrag; siehe die Inhaltsstoffdaten unten. |
Inhaltsstoffdaten
Inhaltsstoffdaten liegen in drei Strukturen vor:
ingredients: eine einzelne, geordnete Liste.ingredient_sections: benannte Abschnitte mit jeweils einer eigenen Liste.components: die einzelnen Produkte eines Sets, jeweils mit einer Liste oder Abschnitten.- Jedes Produkt verwendet genau eine dieser Strukturen; die übrigen Felder werden weggelassen. Eine nicht verfügbare Liste hat den Wert null. Andere vorhandene Listen bleiben zugänglich.
Felder und Werte
position: beginnt innerhalb jeder Inhaltsstoffliste, jedes Abschnitts und jeder Komponente bei null.label_name: die Schreibweise des Inhaltsstoffs auf dem Etikett mit Rechtschreibkorrekturen; sie kann vom normalisierten Namen abweichen.concentration: angegebener Prozentwert oder null.- Nicht zugeordnete Bezeichnungen behalten ihre Position und ihren Text.
idund die Felder des Inhaltsstoffverzeichnisses sind dann null. Zugeordnete Inhaltsstoffe können ein leeresfunctions-Array haben. - Inhaltsstoff-IDs in der API sind UUIDs. Die Werte von
ingredient_idin der herunterladbaren Datenbank sind Ganzzahlen. contains_*: true, false oder null (unbekannt). Auchheadingin einem Abschnitt undnamein einer Komponente können null sein.- Erkannte Überschriften werden zu Ingredients, Active ingredients, Inactive ingredients, Medicinal ingredients, Non-medicinal ingredients oder May contain normalisiert. Andere Überschriften behalten ihren Wortlaut.
Inhaltsstofftext
ingredients_raw: der Inhaltsstofftext aus dem Produkteintrag, ergänzend zu den strukturierten Listen. Er wird nicht für jeden Abschnitt oder jede Komponente wiederholt.- Der ursprüngliche Text und seine Zeilenumbrüche bleiben erhalten, soweit sie vorliegen. Fehlender Text hat den Wert null.
Beispiele für API-Antworten
Inhaltsstofffelder aus beispielhaften API-Antworten. Wählen Sie unten ein Beispiel aus.
{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Aqua (Water), Glycerin",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [ "solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Active ingredients: Zinc Oxide\nInactive ingredients: Aqua (Water), Glycerin",
"ingredient_sections": [
{
"position": 0,
"heading": "Active ingredients",
"ingredients": [
{
"position": 0,
"label_name": "Zinc Oxide",
"concentration": null,
"id": "d6512677-49b1-5505-982d-6c9635b5f4a7",
"name": "Zinc Oxide", "rating": "supporting actives",
"irritancy": "0",
"comedogenicity": "1",
"functions": [
"bulking",
"cosmetic colorant",
"skin protecting",
"uv absorber",
"uv filter"
],
"cas_number": "1314-13-2",
"ec_number": "215-222-5",
"ph_eur_name": "Zinci Oxidum",
"iupac_name": "Zinc Oxide (Ci 77947)",
"other_names": null,
"category": null
}
]
},
{
"position": 1,
"heading": "Inactive ingredients",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [
"solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
}
]
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Cleanser: Aqua (Water), Glycerin\nSerum: Aqua (Water), Glycerin",
"components": [
{
"position": 0,
"name": "Cleanser",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water", "rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [
"solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
},
{
"position": 1,
"name": "Serum",
"ingredient_sections": [
{
"position": 0,
"heading": "Ingredients",
"ingredients": [
{
"position": 0,
"label_name": "Aqua (Water)",
"concentration": null,
"id": "2ba7df6d-7d8a-5935-af3a-f0bb7f03fb53",
"name": "Water",
"rating": null,
"irritancy": null,
"comedogenicity": null,
"functions": [
"solvent"
],
"cas_number": "7732-18-5",
"ec_number": "231-791-2",
"ph_eur_name": "Aqua",
"iupac_name": null,
"other_names": "Aqua",
"category": null
},
{
"position": 1,
"label_name": "Glycerin",
"concentration": null,
"id": "59bfab3c-aaeb-5b95-8584-bfacb56e0c3a",
"name": "Glycerin",
"rating": "direct actives",
"irritancy": "0",
"comedogenicity": "0",
"functions": [
"denaturant",
"hair conditioning",
"humectant",
"oral care",
"perfuming",
"skin conditioning",
"skin protecting",
"solvent",
"viscosity controlling"
],
"cas_number": "56-81-5",
"ec_number": "200-289-5",
"ph_eur_name": "Glycerolum",
"iupac_name": "Glycerine ;Glycerol (Inn); Glycerol (Rifm); Glycerolum (Ep); Glycyl Alcohol; 1,2,3-Propanetriol; 1,2,3-Trihydroxypropane",
"other_names": "Glycerol",
"category": null
}
]
}
]
}
]
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": "Aqua (Water), Glycerin",
"ingredients": null
}{
"id": "00000000-0000-4000-8000-000000000001",
"ingredients_raw": null,
"ingredients": null
}IDs und Dublettenbereinigung
- Aliasse aus der Dublettenbereinigung verknüpfen frühere Produkt- und Inhaltsstoff-IDs mit den beibehaltenen Datensätzen.
- Produktabfragen, einschließlich Stapelabfragen, geben den beibehaltenen Datensatz und dessen ID zurück. Auch Inhaltsstoffabfragen und -filter akzeptieren frühere IDs und verwenden den beibehaltenen Datensatz.
- Inhaltsstofffilter: Eine unbekannte oder entfernte ID führt für die gesamte Anfrage zu
400. - Inhaltsstoffdetails:
410für eine ersatzlos entfernte ID;404für eine unbekannte ID.
Datenbankdateien
- JSONL: dieselben Inhaltsstoffstrukturen mit numerischen
ingredient_id-Verweisen. - CSV und SQLite:
product_ingredientsenthält einfache Listen,product_ingredient_groupsenthält Abschnitte und Komponenten undproduct_group_ingredientsderen Einträge. - Nicht zugeordnete Bezeichnungen bleiben als Zeile mit einem null-Verweis auf den Inhaltsstoff erhalten.
- Nullwerte: SQL NULL in SQLite, leere Zellen in CSV-Dateien. In Anführungszeichen gesetzte CSV-Felder erhalten die Zeilenumbrüche im Inhaltsstofftext.
Produktbilder
Das Feld image_url verweist auf ein standardisiertes Produktfoto vor weißem Hintergrund, das über images.thebeautyapi.com bereitgestellt wird. Wir hosten 260.000 Bilder, die Sie direkt in Ihrer Oberfläche anzeigen können, ohne sie herunterzuladen oder selbst zu hosten. Für eine kleine Zahl von Produkten liegt kein Foto vor; dort ist image_url null.
Barcodes
Barcodes dienen als Suchschlüssel, nicht als Antwortfeld. Mit einem Barcode-Tarif findet GET /v1/products/barcode/{barcode} das zu einem UPC-A, EAN-13 oder GTIN-8/14 gehörende Produkt und liefert dessen regulären Datensatz. Kein Tarif gibt die Liste der Codes eines Produkts zurück. Einzel-, Stapel-, Such- und Filterabfragen haben mit und ohne Barcode-Zugriff dasselbe Format. Codes für Einzelartikel, Mehrfachpackungen und Varianten (Farbton, Duft oder Größe derselben Produktlinie) werden unterstützt. Ein UPC-A und seine mit einer führenden Null ergänzte EAN-13-Form sind gleichwertig. Rund 61% der Produkte im Katalog haben mindestens einen Code. Wenn Sie die Codes selbst benötigen, enthält die lizenzierte Datenbank eine gtin14-Liste je Produkt.
Versionierung
Die API verwendet den Pfad /v1. Ihre Clients sollten zusätzliche Antwortfelder ignorieren. Produkte können eine einfache Inhaltsstoffliste, Abschnitte oder Komponenten enthalten; Felder können null sein. Der Abschnitt Inhaltsstoffdaten erklärt den Umgang mit diesen Formaten.
Daten- und API-Aktualisierungen finden Sie im Änderungsverlauf.
In Postman ausprobieren
Um die Endpunkte vor der Implementierung auszuprobieren, importieren Sie unsere Postman-Collection, hinterlegen Sie Ihren API-Schlüssel als Variable und senden Sie Anfragen. Die Collection enthält auch einen Ordner mit absichtlich ungültigen Anfragen, an denen Sie die Antworten 400, 403 und 404 sehen können.
Starten Sie Ihre Integration
Starten Sie mit sieben Testtagen und 100 Anfragen. Kostenpflichtige Tarife beginnen bei 40 $/Monat mit 10.000 enthaltenen Aufrufen.