Nährwert-API

Eine Anfrage, fünf Gruppen, pro 100 g

GET /v1/foods/{id}/nutrients nimmt die UUID des Lebensmittels im Pfad und sonst nichts: keine Query-Parameter, keinen Body, kein lang. Die id ist dieselbe, die jeder andere Endpunkt liefert, sodass ein Treffer aus der Lebensmittel-Suche-API oder der Barcode-Abfrage-API mit einem weiteren Aufruf zur vollständigen Aufschlüsselung wird. IDs sind über Reimporte hinweg deterministisch, du kannst sie also speichern und diese URL weiter aufrufen.

Die Antwort ist ein flaches Objekt mit food_id und fünf festen Gruppen: macros, fats, minerals, vitamins und other. Jeder Schlüssel ist immer vorhanden, und jeder Wert ist entweder eine Zahl oder null. Zählt man die Schlüssel im aktuellen Schema, ergeben sich 41 Nährstofffelder — daher die Angabe 40+. Einheiten stehen im Schlüsselnamen (energy_kcal, sodium_mg, selenium_mcg, vitamin_a_iu), du brauchst also keine separate Einheitentabelle.

Alle Werte beziehen sich auf 100 g des Produkts, wie es verkauft wird. Für eine Portion multipliziere mit Gramm geteilt durch 100. Das serving_size_raw des Lebensmitteldatensatzes ist Etikettentext (beim Beispiel-Datensatz von Coca-Cola ist es „1 can (330 ml)“), die Umrechnung dieses Textes in Gramm ist also deine Aufgabe.

• macros (10 Schlüssel) umfasst Energie in kcal und kJ, Eiweiß, Kohlenhydrate, Fett, Zucker, Ballaststoffe, Alkohol, Stärke und Polyole; fats (7) ergänzt gesättigte, Trans-, einfach und mehrfach ungesättigte Fette, omega3, omega6 und cholesterol_mg
• minerals (12) reicht von sodium_mg und salt_g bis selenium_mcg und iodine_mcg; vitamins (11) gibt A und D in IU an, B9 und B12 in mcg, den Rest in mg; other enthält added_sugars_g

Nullwerte und Nullen richtig lesen

Die Beispielantwort für das Lebensmittel 62ea12b8-b260-c288-5c38-3a4906f5d6dd zeigt das typische Open-Food-Facts-Muster: energy_kcal 42, energy_kj 180.2, carbs_g 10.6, sugars_g 10.6, added_sugars_g 5.3, explizite Nullen für proteins_g, fat_g, saturated_fat_g, sodium_mg und salt_g, und null für alles andere, von fiber_g bis zur gesamten vitamins-Gruppe.

Behandle die beiden Zustände unterschiedlich. Eine 0 ist ein Wert, den die Quelle gemeldet hat; null heißt, dass der Nährstoff nicht auf dem Etikett oder nicht in der Quelle steht. Wandle null nie in 0 um, bevor du die Tagesaufnahme addierst, sonst weist eine Mahlzeit aus teilweise gekennzeichneten Produkten stillschweigend zu wenig Vitamine und Mineralstoffe aus. Zeige stattdessen einen Strich oder „nicht angegeben“.

Die Abdeckung folgt der Herkunft. Zeilen mit source usda_foundation oder usda_sr_legacy sind Laboranalysen der USDA und füllen die Vitamin- und Mineralstoffgruppen, sodass die meisten Schlüssel Zahlen sind. Zeilen mit source usda (USDA Branded Foods) und Zeilen aus Open Food Facts sind von der Verpackung abgetippt; sie sind für die verpflichtenden Etikettennährwerte zuverlässig und darüber hinaus oft null. Das source-Feld des Lebensmitteldatensatzes sagt dir, in welchem Fall du bist, bevor du die Tabelle renderst.

• Rendere null als unbekannt, nicht als null; aggregiere nur Schlüssel, die über jedes Element der Mahlzeit hinweg nicht null sind.
• sodium_mg und salt_g existieren beide, weil sich Etiketten je nach Region unterscheiden; nimm das, was deine Zielgruppe erwartet, und falle auf das andere zurück.

Wann du diesen Aufruf wirklich brauchst

Jeder Lebensmitteldatensatz aus der Lebensmittel-Datenbank-API und jeder Barcode-Treffer enthält bereits nutrition_summary mit sechs Eckwerten: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g und fiber_g. Suchtreffer sind schlankere Zeilen ohne dieses Objekt. Für ein Scan-Ergebnis, eine Detailkarte oder ein schnelles Kalorienprotokoll genügt dieses Objekt meist und kostet keine Nährwert-Aufschlüsselung.

Spare dir /nutrients für den Detailbildschirm oder den Moment, in dem jemand nach Natrium, gesättigten Fetten, Cholesterin oder einem bestimmten Vitamin fragt. Suchen oder scannen, die Zusammenfassung zeigen, die Aufschlüsselung beim Antippen holen. Im Free-Tarif hält dich das während der Entwicklung auch innerhalb des Limits von 25 pro Tag.

Die aufgezeichneten Antwort-Header tragen kein Cache-Control, das Caching ist also deine Aufgabe. IDs sind stabil und Werte ändern sich nur, wenn ein Produkt neu importiert wird, sodass ein Cache mit food_id als Schlüssel und einer Haltedauer von Stunden oder Tagen sicher ist.

Das Free-Kontingent, Header für Header

Im Free-Tarif zieht jede erfolgreiche Aufschlüsselung von einem separaten Tageszähler mit 25 ab, der in jeder Antwort als X-RateLimit-Nutrients-Limit, X-RateLimit-Nutrients-Remaining und X-RateLimit-Nutrients-Reset gemeldet wird. Lies Remaining vor einer Serie von Detailabrufen, dann kannst du auf nutrition_summary ausweichen, statt mitten in der Sitzung gegen die Wand zu laufen.

Bei null liefert der Endpunkt 429 mit dem Fehler „Nutrients daily allowance exceeded“, einer upgrade_url im Body und Retry-After mit den Sekunden bis Mitternacht UTC. Ein abgelehnter Aufruf verbraucht weder eine Aufschlüsselung noch eine Tagesanfrage und verschiebt den Reset nicht. Bezahlte Tarife haben keinen solchen Zähler; ihre Nährwert-Aufrufe sind nur durch das tägliche Anfragekontingent des Tarifs (geteilt über alle Schlüssel des Kontos) und das Sekundenlimit pro Schlüssel begrenzt.

Bist du bei Starter oder darüber und arbeitest einen großen Katalog ab, hole zuerst die Basisdatensätze über die Bulk-Lebensmittelabfrage-API und rufe /nutrients nur für die IDs auf, bei denen die Zusammenfassung nicht reicht.