Lebensmittel-Kategorien API

Was eine Anfrage liefert

GET /v1/categories liest eine vorberechnete Tabelle mit jedem unterschiedlichen Kategorie-String im Katalog samt der Zahl der Produkte, die ihn tragen; Produkte ohne Kategorie sind ausgeschlossen. Die Zeilen sind nach product_count absteigend sortiert, ohne zweite Sortierung — verlass dich also nicht auf die Reihenfolge von Zeilen mit gleicher Zahl.

q ist ein Teilstring-Filter ohne Beachtung der Groß-/Kleinschreibung, kein Präfix: q=chocolate trifft „Chocolate“, „en:chocolates“ und „Beverages, Dairies, Dairy drinks, Flavoured milks, Chocolate milks“ gleichermaßen und engt die aufgezeichnete Antwort auf ein total von 11303 unterschiedlichen Strings ein. Leerraum wird getrimmt, % und _ sind wörtlich, und q ist auf 200 Zeichen begrenzt.

limit reicht von 1–100 (Standard 20) und offset von 0–10000, sodass du mit limit=100 höchstens die ersten 10.100 Zeilen erreichst; grenze lieber mit q ein, statt tiefer zu blättern. Antworten tragen Cache-Control: public, max-age=600, der Server cacht eine Stunde, und die Tabelle wird nur bei einem Bulk-Reimport neu aufgebaut — hole sie also einmal beim Start oder in einem Build-Schritt und speichere das Ergebnis.

Zwei Formen von Kategorie-Strings

Open-Food-Facts-Produkte tragen eine kommagetrennte Hierarchie, von allgemein bis spezifisch: „Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates“. Segmente können rohe Taxonomie-Tags mit einem zweistelligen Sprachpräfix sein („en:chocolate-candies“), in der Sprache des Etiketts stehen („Botanas, Snacks dulces, Cacao y sus productos, Chocolates, Chocolates negros“) und enden oft in einem Sammelbegriff wie en:groceries, der nicht die spezifischste Ebene ist.

USDA-Produkte tragen eine flache Handelskategorie, deren Name selbst Kommas enthalten kann („Chips, Pretzels & Snacks“); trenne sie nie. Zeilen enthalten hier keine source — brauchst du sie, hole mit der Lebensmittel-Datenbank-API ein Produkt aus der Kategorie und lies source neben category und categories_tags.

Eine Hierarchie kann als mehrere Zeilen erscheinen: Die aufgezeichnete Antwort listet „Snacks, Sweet snacks, Cocoa and its products, Chocolates, Dark chocolates“ (497 Produkte) und denselben Pfad ohne Leerzeichen nach den Kommas (339) getrennt. Führe über bereinigte Segmente zusammen, nicht über den rohen String.

Einen Browse-Baum oder eine Filter-UI bauen

Wende die Bereinigung an, die die Website nutzt: am Komma trennen, trimmen, ein führendes xx:-Tag entfernen, Bindestriche durch Leerzeichen ersetzen, den ersten Buchstaben großschreiben und wiederholte Segmente ohne Beachtung der Groß-/Kleinschreibung verwerfen. Das erste bereinigte Segment ist die Wurzel; das letzte, das kein Sammelbegriff ist (groceries, food, foods, products, unknown, none), ist das Blatt. Die Zahl eines Knotens ist die Summe von product_count über alle rohen Strings, die auf ihn abgebildet werden.

• Wurzelknoten: nach erstem bereinigten Segment gruppieren („Snacks“, „Beverages“, „Botanas“).
• Blatt-Chips: das letzte Segment, das kein Sammelbegriff ist („Dark chocolates“, „Chocolate milks“).
• Flache USDA-Namen: der ganze String ist zugleich Wurzel und Blatt.
• Sprache: Hierarchien in verschiedenen Sprachen bleiben getrennte Knoten; für Übersetzungen pro Produkt übergib lang= an die Lebensmittel-Suche-API und lies category_localized und category_segments_localized.
• Der Browse-Baum der Website unter /categories/ wendet dieselben Bereinigungsregeln auf diese Daten an (und behält nur die größeren Blätter); nutze ihn, um deine Ausgabe zu prüfen.

Von einer Kategorie zu ihren Produkten

Die Suche hat keinen Kategorie-Parameter. Die Lebensmittel-Suche-API gleicht zuerst Produktnamen und Marken ab und gleicht erst dann, wenn das nichts findet, die Wörter deiner Anfrage mit Kategorie-Strings ab. Sende ein vollständiges bereinigtes Segment, das selbst kein Produktname ist, als q, etwa „Seeds & Related Snacks“, und du erhältst die Produkte dieser Kategorie nach Beliebtheit sortiert.

Der Fallback arbeitet wortbasiert, sodass „Seeds & Related Snacks“ jeden Kategorie-String trifft, der diese Wörter in irgendeiner Sprache enthält, und ein Segment, das zugleich ein gängiges Produktwort ist („Chocolate“ oder „Dark chocolates“), ihn nie erreicht, weil Produktnamen zuerst treffen. Für eine strikte Auflistung filtere jedes Ergebnis nach seinem category-Feld, dem rohen String, den dieser Endpunkt zurückgegeben hat.