Barcode-Abfrage API

Was eine Abfrage macht

Sende GET /v1/foods/barcode/{code} mit deinem Schlüssel im X-API-Key-Header. Der Code ist GTIN-8 bis GTIN-14, höchstens 20 Zeichen. FoodBase versucht zuerst eine exakte Übereinstimmung mit dem gespeicherten Barcode, dann die Äquivalente derselben Nummer mit führenden Nullen, sodass ein 12-stelliger UPC-A den Datensatz findet, der als 13-stellige EAN gespeichert ist.

Für 5449000000996 kommt der Datensatz mit barcode 5449000000996 und id 62ea12b8-b260-c288-5c38-3a4906f5d6dd zurück. Diese id bleibt über Reimporte hinweg stabil, speichere sie also als Fremdschlüssel statt des Barcode-Strings.

Tragen mehrere Katalogzeilen denselben Barcode, gewinnt die beliebteste Zeile, und die Wahl ist deterministisch: Derselbe Code liefert bei jedem Aufruf dasselbe Produkt.

• Der zurückgegebene barcode ist die gespeicherte Form, nicht unbedingt die Form, die du gesendet hast.

Den Datensatz lesen

Der 200-Body ist derselbe vollständige Lebensmitteldatensatz, den die Lebensmittel-Datenbank-API per id liefert — parse ihn also einmal und verwende den Parser weiter. Für 5449000000996 bedeutet das: source openfoodfacts, name_default Original Taste mit bg- und fr-Einträgen im name-Array, nutriscore e, nova_group 4 und ecoscore_grade not-applicable. Etikettentext wie serving_size_raw (1 can (330 ml)) und quantity (0kg bei diesem Datensatz, ein Fehler der Mitwirkenden) kommt so zurück, wie er auf der Verpackung getippt wurde — behandle ihn also als Hinweis, nicht als Zahl.

• categories_tags ist die maschinenlesbare Taxonomie (en:colas); category ist derselbe Pfad als kommagetrennter Anzeige-String.
• allergens und traces sind null, wenn die Quelle keine nennt — das ist nicht dasselbe wie allergenfrei.
• image_url zeigt auf images.openfoodfacts.org und kann sich ändern, wenn Mitwirkende das Produkt aktualisieren.

Lokalisierung und Nährwerte

Hänge ?lang=bg (oder en, fr, es, de, it) an, um category_localized, category_segments_localized und allergens_localized aus den Übersetzungswörterbüchern zu füllen. Wo es keine Übersetzung gibt, ist das Feld null statt eines englischen Fallbacks — halte category und allergens also in deiner Fallback-Kette. lang betrifft weder name noch ingredients.

nutrition_summary hat sechs Schlüssel: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g, fiber_g. Jeder kann null sein, und das ganze Objekt ist null, wenn die Quelle keine Nährwerte erfasst hat. Für die vollständige Tabelle pro 100 g, 40+ Nährstoffe, wo die Quelle sie hat, rufe die Nährwert-API mit der soeben erhaltenen id auf.

Scanner-Ablauf, Caching und Fehlschläge

Bei 200 rendere die Karte aus name_default, brand, image_url und nutrition_summary und behalte die id. Bei 404 ist der Code nicht im Katalog: Weiche auf die Lebensmittel-Bilderkennung-API mit einem Foto der Packungsvorderseite aus, oder biete eine Textsuche an. Wiederhole kein 404; es ändert sich nicht, bis der Katalog aktualisiert wird.

200-Antworten tragen Cache-Control: public, max-age=300, und 404er sind 60 Sekunden cachebar. Halte dich in jedem Cache zwischen deinen Nutzern und FoodBase daran. Jede Antwort trägt außerdem X-RateLimit-Second-Remaining und die Header für das Tageskontingent; drossle anhand davon, bevor du ein 429 siehst.

Die Abdeckung ist bei europäischen und US-Handelsprodukten am besten, weil der Katalog aus Open Food Facts und USDA FoodData Central aufgebaut ist, ergänzt um GS1 Bulgarien und Metro Bulgarien. Eigenmarken und ganz neue Produkte sind die häufigsten Fehlschläge.