Food Search API

What one search request does

A search is a single GET with the text in q. The words are matched against the product name and the brand together, so q=olympus milk finds products whose name never says Olympus, and the last word is treated as a prefix, so milk olym already matches while the user is still typing. All words must match; there is no OR. q must be 1 to 200 characters; a missing or empty q is rejected before any search runs, so guard the empty search box on your side.

Results are relevance-ranked, and when two products match equally well the more popular one is listed first. That is why a one-word query such as banana puts store-brand fruit and a baby-food puree at the top of the sample, and why adding a second word (a brand, a flavor) is the quickest way to move a specific product up.

Category names are a fallback, not part of the main match: only when the name-and-brand search finds nothing does the API look for products whose category contains the words, in whatever language the category is stored. That is what makes a query such as Seeds & Related Snacks or Fruits tropicaux return a list, ordered by popularity, instead of an empty array.

• The order is neither alphabetical nor by id. Do not re-sort the data array on the client.
• If the input is a digits-only GTIN, send it to the Barcode Lookup API instead: it resolves zero-padding variants (0000080042556 finds 80042556), which a text search will not.

Reading a result row

Each item in data is a FoodListItem, a lighter shape than the full record: id, barcode, source, name_default, brand, category, image_url, nutriscore and nova_group, plus name_localized (always present) and category_localized when a non-English lang is passed. There are no nutrients here; the list is built for rendering rows, not for calculations.

Several fields are nullable and the sample shows it. The Roshen 'Banana land' candy (4f995c13-c0df-bfcc-b6ec-449d312def75) has image_url null and nova_group null; brand and barcode can be null as well. nutriscore values outside a to e, like the 'n' and 'u' in the sample, mean no grade was computed, so render them as 'not rated' instead of the raw letter.

category is the full Open Food Facts category path, comma-separated from broad to specific ('...,Fruits tropicaux,Bananes' for the Bio Village bananas). Show the last segment as the label, or the first for a coarse grouping, and strip language prefixes such as pt: before display. image_url is a contributor photo on images.openfoodfacts.org, so ship a placeholder for the null case.

Pagination, total and stable ids

limit is 1 to 100 (default 20) and offset is 0 to 10000. total is a capped count: the API stops counting at 1,000 matches, so the sample's total of 1000 for q=banana with limit=3 means at least 1,000. Render it as '1,000+' and do not compute a last-page number from it.

Page by adding limit to offset until data comes back with fewer than limit items. Because offset tops out at 10000, a query with more matches than that needs a narrower q, not a deeper page.

• Ids are stable across FoodBase re-imports, so store the id from a search row and resolve it later with the Food Database API without searching again.
• Ranking is computed per request and popularity can change, so an offset is not a durable cursor. Persist ids, not page positions.

Searching in another language

lang defaults to en. Every language searches that language's entry in the product's name array where a volunteer or FoodBase's AI translation has provided one, and falls back to name_default, the name as printed on the label, for products that have no such entry; the brand is always part of the match. So lang=bg reaches every product, but prefers Bulgarian names where they exist, and a Cyrillic label is found under any lang.

The lang you pass also shapes the output. name_localized holds the translated name: the sample, requested with lang=en, turns 'Puré de plátano y fresa' into 'Banana and Strawberry Puree', and falls back to name_default when there is nothing to translate, as 'Banana land' shows. Display name_localized when non-null and name_default otherwise. category_localized is not a required field and is absent from the sample, so read it defensively.

Autocomplete and the hand-off to full records

Search is the right endpoint for a type-ahead box. Debounce keystrokes, request limit=8 to 10, and cancel the in-flight request when the user types again so a slow earlier response cannot overwrite a newer one. Every keystroke that reaches the API is one request against your daily quota, so debouncing is a cost control as much as a UX detail.

When the user picks a row, call the Food Database API with the id for the complete record, or the Nutrition API when you only need the per-100 g nutrient table. One search plus one detail request is cheaper than fetching full records for every suggestion.

The captured search response carries no Cache-Control header, unlike food records, which are cacheable for 300 seconds. Cache search results yourself, keyed by the exact q, lang, limit and offset; the same short prefixes recur constantly in a type-ahead box. X-RateLimit-Second-Remaining shows how much burst is left, and on a 429 the Retry-After header says how many seconds to wait.