Lebensmittel-Suche API

Was eine Suchanfrage macht

Eine Suche ist ein einzelnes GET mit dem Text in q. Die Wörter werden gemeinsam gegen Produktname und Marke abgeglichen, sodass q=olympus milk auch Produkte findet, deren Name nie „Olympus“ nennt, und das letzte Wort wird als Präfix behandelt, sodass milk olym schon passt, während die Nutzerin noch tippt. Alle Wörter müssen passen; es gibt kein ODER. q muss 1 bis 200 Zeichen lang sein; ein fehlendes oder leeres q wird abgelehnt, bevor eine Suche läuft — fange das leere Suchfeld also auf deiner Seite ab.

Produkte, die genau so heißen, wie du getippt hast, kommen zuerst, sodass banana erst Bananen und dann Bananenjoghurts listet und greek yogurt zuerst die schlichten griechischen Joghurts. Danach sind die Ergebnisse nach Relevanz sortiert, und bei gleich guter Übereinstimmung steht das beliebtere Produkt vorn. Eine Markensuche wie pringles überspringt den Schritt mit dem exakten Namen und bleibt in der Reihenfolge nach Beliebtheit; ein zweites Wort (eine Marke, eine Geschmacksrichtung) ist der schnellste Weg, ein bestimmtes Produkt nach oben zu holen.

Kategorienamen sind ein Fallback und nicht Teil des Hauptabgleichs: Nur wenn die Suche über Name und Marke nichts findet, sucht die API nach Produkten, deren Kategorie die Wörter enthält — in welcher Sprache die Kategorie auch gespeichert ist. Deshalb liefert eine Anfrage wie Seeds & Related Snacks oder Fruits tropicaux eine nach Beliebtheit sortierte Liste statt eines leeren Arrays.

• Die Reihenfolge ist weder alphabetisch noch nach id. Sortiere das data-Array nicht auf dem Client neu.
• Ist die Eingabe eine reine GTIN aus Ziffern, schick sie stattdessen an die Barcode-Abfrage-API: Sie löst Varianten mit führenden Nullen auf (0000080042556 findet 80042556), was eine Textsuche nicht kann.

Eine Ergebniszeile lesen

Jedes Element in data ist ein FoodListItem, eine schlankere Form als der vollständige Datensatz: id, barcode, source, name_default, brand, category, image_url, nutriscore und nova_group, dazu name_localized (immer vorhanden) und category_localized, wenn eine nicht-englische lang übergeben wird. Nährwerte gibt es hier nicht; die Liste ist zum Rendern von Zeilen gebaut, nicht für Berechnungen.

Mehrere Felder sind nullable, und das Beispiel zeigt es. Das Roshen-Bonbon „Banana land“ (4f995c13-c0df-bfcc-b6ec-449d312def75) hat image_url null und nova_group null; auch brand und barcode können null sein. nutriscore-Werte außerhalb von a bis e, wie das „n“ und das „u“ im Beispiel, bedeuten, dass keine Note berechnet wurde — zeige sie als „nicht bewertet“ an statt als den rohen Buchstaben.

category ist der vollständige Open-Food-Facts-Kategoriepfad, kommagetrennt von allgemein bis speziell („...,Fruits tropicaux,Bananes“ für die Bananen von Bio Village). Zeige das letzte Segment als Label oder das erste für eine grobe Gruppierung, und entferne Sprachpräfixe wie pt: vor der Anzeige. image_url ist ein Foto von Mitwirkenden auf images.openfoodfacts.org, also liefere für den null-Fall einen Platzhalter aus.

Paginierung, total und stabile IDs

limit liegt zwischen 1 und 100 (Standard 20), offset zwischen 0 und 10000. total ist eine gedeckelte Zahl: Die API hört bei 1.000 Treffern auf zu zählen, sodass der total-Wert 1000 im Beispiel für q=banana mit limit=3 bedeutet: mindestens 1.000. Zeige ihn als „1.000+“ und berechne aus ihm keine Nummer der letzten Seite.

Blättere, indem du limit auf offset addierst, bis data weniger als limit Elemente liefert. Weil offset bei 10000 endet, braucht eine Anfrage mit mehr Treffern ein engeres q, keine tiefere Seite.

• IDs bleiben über FoodBase-Reimporte hinweg stabil: Speichere die id aus einer Suchzeile und löse sie später mit der Lebensmittel-Datenbank-API auf, ohne erneut zu suchen.
• Das Ranking wird pro Anfrage berechnet und die Beliebtheit kann sich ändern, daher ist ein offset kein dauerhafter Cursor. Speichere IDs, keine Seitenpositionen.

In einer anderen Sprache suchen

lang ist standardmäßig en. Jede Sprache durchsucht den Eintrag dieser Sprache im name-Array des Produkts, sofern ihn Freiwillige oder die KI-Übersetzung von FoodBase geliefert haben, und fällt für Produkte ohne solchen Eintrag auf name_default zurück, den Namen wie auf dem Etikett gedruckt; die Marke ist immer Teil des Abgleichs. So erreicht lang=bg jedes Produkt, bevorzugt aber bulgarische Namen, wo es sie gibt, und ein kyrillisches Etikett wird unter jeder lang gefunden.

Die übergebene lang prägt auch die Ausgabe. name_localized enthält den übersetzten Namen: Das Beispiel, angefragt mit lang=en, macht aus „Puré de plátano y fresa“ „Banana and Strawberry Puree“ und fällt auf name_default zurück, wenn es nichts zu übersetzen gibt, wie „Banana land“ zeigt. Zeige name_localized, wenn nicht null, sonst name_default. category_localized ist kein Pflichtfeld und fehlt im Beispiel — lies es also defensiv.

Autovervollständigung und die Übergabe an vollständige Datensätze

Die Suche ist der richtige Endpunkt für eine Type-ahead-Box. Entprelle (debounce) die Tastenanschläge, fordere limit=8 bis 10 an und brich die laufende Anfrage ab, wenn die Nutzerin weitertippt, damit eine langsame frühere Antwort keine neuere überschreibt. Jeder Tastenanschlag, der die API erreicht, ist eine Anfrage gegen dein Tageskontingent — Debouncing ist also genauso Kostenkontrolle wie UX-Detail.

Wählt der Nutzer eine Zeile, rufe die Lebensmittel-Datenbank-API mit der id für den vollständigen Datensatz auf, oder die Nährwert-API, wenn du nur die Nährwerttabelle pro 100 g brauchst. Eine Suche plus eine Detailanfrage ist günstiger, als für jeden Vorschlag den vollständigen Datensatz zu holen.

Die aufgezeichnete Suchantwort trägt keinen Cache-Control-Header, anders als Lebensmitteldatensätze, die 300 Sekunden lang cachebar sind. Cache Suchergebnisse selbst, mit dem Schlüssel aus exaktem q, lang, limit und offset; dieselben kurzen Präfixe kommen in einer Type-ahead-Box ständig wieder. X-RateLimit-Second-Remaining zeigt, wie viel Burst übrig ist, und bei einem 429 sagt der Retry-After-Header, wie viele Sekunden du warten sollst.