Bulk-Lebensmittelabfrage API

Die Anfrage, Schritt für Schritt

POST /v1/foods/bulk mit Content-Type: application/json, deinem X-API-Key-Header und einem Body der Form {"ids": [...]} oder {"barcodes": [...]} – genau eines von beiden, 1 bis 100 Einträge. ids sind UUID-Strings (die in den Codebeispielen oben sind echte Datensätze zum Testen); Barcodes werden genau wie bei GET /v1/foods/barcode/{code} aufgelöst, sodass ein EAN-13 auch ein Produkt findet, das in seiner UPC-12- oder GTIN-14-Form gespeichert ist, und das Feld barcode des Datensatzes zeigt die gespeicherte Form neben requested_barcode.

Die Validierung läuft, bevor die Datenbank berührt wird, und gilt ganz oder gar nicht. Ein Barcode in ids, beide Felder oder keines, ein leeres Array oder 101 Einträge lehnen den ganzen Batch mit 422 {"error": "Validation Error", "details": [{"field": "ids.3", "message": ...}]} ab. Ein optionales ?lang= (en, fr, es, de, it, bg) lokalisiert Kategorie- und Allergenbezeichnungen wie bei den Einzelabfragen; Namen und Zutaten in anderen Sprachen stehen in den Arrays name und ingredients.

Die Antwort lesen

data ist ein Array von FoodItem-Objekten, aufgebaut vom selben Formatter wie die Lebensmittel-Datenbank-API, sodass ein für den Einzeldatensatz geschriebener Parser unverändert funktioniert — von id, barcode und source bis categories_tags, image_url und allergens. Fehlende Quelldaten sind null, nie ein fehlender Schlüssel.

nutrition_summary enthält energy_kcal, proteins_g, carbs_g, fat_g, sugars_g und fiber_g pro 100 g. Es ist nur dann als Ganzes null, wenn das Produkt gar keine Nährwertzeile hat; fehlt einer Zeile ein Wert, zeigt nur dieser Schlüssel null. Etikettentext wie quantity und serving_size_raw kommt genau so an, wie Mitwirkende ihn getippt haben — parse also defensiv.

Fehlende Einträge, Duplikate und Drift

Die Antwort kann kürzer sein als die Anfrage: Es gibt kein 404 pro Eintrag, aber jede ID und jeder Barcode ohne Produkt steht in not_found, in der Reihenfolge der Anfrage – du musst also nie selbst abgleichen. Eine doppelt gesendete ID oder ein doppelter Barcode kommt als ein Datensatz zurück; dedupliziere vor dem Senden, damit jeder der 100 Plätze zählt.

IDs sind deterministisch, aus der Quelle und deren eigener Produktkennung abgeleitet, sodass ein Produkt über Reimporte hinweg seine id behält. Löst sich eine gespeicherte id nicht mehr auf, ist das Produkt unter dieser Identität nicht mehr im Katalog: Markiere die Zeile als veraltet und löse sie über die Barcode-Abfrage-API oder die Lebensmittel-Suche-API neu auf, statt sie zu löschen.

Kontingent und Rate-Limit-Rechnung

Ein Bulk-Aufruf ist eine Anfrage gegen das Tageskontingent und ein Token aus dem Sekunden-Bucket, egal wie viele IDs. Die Reihenfolge der Middleware ist Authentifizierung, Sekundenlimit, Tarif-Schranke, dann Tageskontingent, sodass ein 401, ein Rate-Limit-429 oder das Starter-403 nie eine Tagesanfrage verbraucht. Ein 422 schon, weil die Validierung nach der Zählung des Kontingents läuft; prüfe UUIDs also auf dem Client.

Lies die Header bei jedem 200: X-RateLimit-Second-Limit, X-RateLimit-Burst-Capacity und X-RateLimit-Second-Remaining für den Bucket pro Schlüssel, X-RateLimit-Account-Limit und X-RateLimit-Account-Remaining für das Sekunden-Aggregat über alle Schlüssel des Kontos sowie X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining und X-RateLimit-Daily-Reset (bei normalen Konten) für das gemeinsame Tagesbudget und seinen Reset um Mitternacht UTC. Das POST trägt keinen Cache-Control-Header, am Edge wird also nichts für dich gecacht: Speichere, was du abrufst.

Einen Katalog nachts synchronisieren

Für das Sortiment eines Händlers sende die Barcodes direkt, 100 pro Aufruf, oder speichere die zurückgegebene ID neben deiner SKU und synchronisiere danach per ID. So oder so sucht der nächtliche Job nie: Er liest die gespeicherten Codes, dedupliziert sie, teilt sie in Gruppen zu 100, sendet jede Gruppe hierher und setzt nach jeder fertigen Gruppe einen Checkpoint, damit ein Katalog, der größer ist als das Budget einer Nacht, dort weitermacht, wo er aufgehört hat. Vergleiche updated_at mit deiner Kopie, um zu sehen, was sich geändert hat.

Takte anhand der Header statt mit einem festen Sleep und beobachte X-RateLimit-Daily-Remaining, damit der Sync nicht den Tagesverkehr desselben Kontos aushungert. Braucht eine Ansicht die 40+ Nährstoffe, rufe die Nährwert-API für diese id bei Bedarf auf; sie nimmt eine id pro Anfrage und zählt ebenfalls als Anfrage.

• IDs deduplizieren, in 100er-Blöcke teilen, pro Block einen Checkpoint setzen.
• Alles in not_found als veraltet markieren; später erneut prüfen.
• /nutrients lazy abrufen, pro Produkt, nicht im Sync.