Lebensmittel-Datenbank API

Was eine Anfrage macht

GET /v1/foods/{id} nimmt die UUID, die du aus einer Suche oder Barcode-Abfrage erhalten hast, und liefert den gesamten normalisierten Datensatz. Es gibt keine Feldauswahl und keine Paginierung: Der Datensatz für 62ea12b8-b260-c288-5c38-3a4906f5d6dd (Barcode 5449000000996, source openfoodfacts) kommt mit jedem Schlüssel des 200-Schemas zurück, und was die Quelle nicht hat, ist null statt weggelassen.

Authentifiziere dich mit dem X-API-Key-Header. Die einzige optionale Eingabe ist ?lang=, eines von en, fr, es, de, it oder bg. Es hängt category_localized, category_segments_localized und allergens_localized an und lässt alle anderen Schlüssel unberührt — ein späteres Hinzufügen von lang bricht also keinen bestehenden Parser. Jede Antwort trägt außerdem einen X-Request-Id-Header, den du in Support-Anfragen nennen kannst.

Namen, Zutaten und der Haupteintrag

name und ingredients sind Arrays aus {lang, text}. Der erste Eintrag hat lang main und spiegelt name_default und ingredients_default; product_lang sagt dir, welche echte Sprache das ist. Beim Coca-Cola-Datensatz ist der Hauptname Original Taste, der fr-Eintrag lautet Coca-Cola en canette und der bg-Eintrag Кока-Кола. Wähle den Eintrag passend zu deiner UI-Sprache und falle auf name_default zurück.

Rechne damit, dass ingredients länger ist als die Zahl der Sprachen: Open Food Facts speichert den Zutatentext pro Verpackungsvariante, sodass dieselbe lang mehrmals in einem Datensatz vorkommen kann, oft mit identischem Text, wie hier. Dedupliziere nach lang und behalte das erste Vorkommen. Der Text wird von Mitwirkenden eingegeben und unverändert zurückgegeben; der ar-Eintrag enthält hier Etikettenfragmente, die keine Zutaten sind — validiere also, bevor du ihn in Strukturen parst.

Kategorie, Tags, Allergene und lang

category ist ein einziger kommagetrennter String von breit bis eng: Beverages and beverages preparations,Beverages,Carbonated drinks,Sodas,Colas,pt:bebidas cafeína. Trenne am Komma; die letzte Ebene ist die spezifischste. categories_tags enthält dieselben Ebenen als maschinenlesbare Tags (en:beverages, en:carbonated-drinks, en:colas) und ist der stabile Wert zum Filtern oder Gruppieren, weil sich der Anzeige-String ändert, wenn Mitwirkende das Produkt bearbeiten.

allergens und traces nutzen dieselben Tags im Stil en:milk, ebenso countries (en:albania, en:austria, en:belgium) und labels. null heißt, die Quelle hat nichts angegeben, nicht dass das Produkt allergenfrei ist; dieser Datensatz hat allergens: null und traces: null, ein Allergiehinweis sollte also „unbekannt“ lauten, nicht „keine“.

Mit ?lang=bg ergänzt die API category_localized als einen übersetzten String, category_segments_localized mit einem Eintrag pro Hierarchieebene und allergens_localized parallel zu allergens. Eine Ebene oder ein Tag ohne Wörterbucheintrag ist im Array null; halte den Index also parallel zu categories_tags oder allergens und falle bei null-Plätzen auf das englische Tag zurück.

Bewertungen, Portionsgröße und zusammengefasste Nährwerte

nutriscore ist ein Kleinbuchstabe (hier e), nova_group eine Zahl (4) und ecoscore_grade ein String, der ein Buchstabe oder ein Sentinel wie not-applicable sein kann, was dieses Getränk zurückgibt. Behandle alle drei als nullable und ordne not-applicable keinem Farbband zu.

serving_size_raw und quantity sind Freitext, vom Etikett kopiert. serving_size_raw lautet 1 can (330 ml) und eignet sich für die Anzeige; quantity lautet bei diesem Datensatz 0kg, ein Fehler der Mitwirkenden — berechne das Packungsgewicht daraus also nie ohne Plausibilitätsprüfung.

nutrition_summary liefert sechs Werte pro 100 g: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g und fiber_g. Jeder kann einzeln null sein, und das Objekt kann null sein, wenn die Quelle keine Nährwerttabelle hat. Es deckt eine Listenzeile oder einen schnellen Vergleich ab; die vollständigen 40+ Nährstoffe liegen bei der Nährwert-API unter /v1/foods/{id}/nutrients mit derselben id.

Stabile IDs, Caching und der übliche Ablauf

Die id ist deterministisch und aus der Quelle und der eigenen Produkt-ID der Quelle abgeleitet, sodass dasselbe Produkt bei jedem Reimport dieselbe UUID bekommt. Speichere IDs in deinen eigenen Tabellen und hole sie Monate später erneut, ohne Zuordnungsschritt. barcode ist im Schema nullable, bevorzuge also die id statt des Barcodes als Join-Schlüssel.

Ein 200 trägt Cache-Control: public, max-age=300 und ein 404 max-age=60, sodass ein CDN oder HTTP-Cache vor deinem Dienst sie ohne Konfiguration beachtet. Cachest du in deiner eigenen Datenbank, nimm id plus lang als Schlüssel, da sich die lokalisierten Schlüssel je Sprache unterscheiden.

Der übliche Ablauf: Hole eine id aus der Lebensmittel-Suche-API oder der Barcode-Abfrage-API, speichere sie und rufe diesen Endpunkt auf, wenn eine Detailansicht den vollständigen Datensatz braucht. Um viele gespeicherte IDs auf einmal zu aktualisieren, nimmt die Bulk-Lebensmittelabfrage-API ab Starter eine Liste in einer Anfrage. Bilder sind Fotos von Open-Food-Facts-Mitwirkenden auf images.openfoodfacts.org, und Datensätze aus anderen Quellen haben womöglich keines — zeige also immer einen Platzhalter, wenn image_url null ist.