Search Food Products
off_search_productsSearch Open Food Facts by full-text query, structured tag filters, or both at once. Returns a summary list with barcodes, product names, brands, Nutri-Score, NOVA group, Green-Score, and categories — enough for triage and selection, not full label data. Use off_get_product on the returned barcodes for complete details. A text query and tag filters combine: every word of the query must match the product name, generic name, categories, labels, or brand, and every filter provided must hold (e.g. query "dark chocolate" with labels_tag "en:organic" and countries_tag "en:france" returns organic chocolate sold in France); numeric nutrient_filters express thresholds per 100 g, or per 100 ml for liquids, such as sugars below 8 g, and combine the same way, and each row then carries the indexed values the thresholds were checked against; ingredients_tag takes canonical ingredient IDs (e.g. "en:inulin") that must all appear among the ingredients Open Food Facts parsed from the label, and combines the same way; additives_tag is the one exception, filtering only on searches carrying none of query, nutrient_filters, or ingredients_tag. nutrition_grade, nova_group, and ecoscore_grade (Green-Score) each take one grade or an array matching any of them. Tag filter values are canonical tag IDs (e.g. "en:organic", "en:no-gluten") — use off_browse_taxonomy to resolve human terms to tag IDs. A case variant, synonym, or singular of a tag is resolved to its canonical ID where Open Food Facts recognizes it; anything else is matched exactly. exclude_allergens and exclude_traces drop products that declare an allergen or a "may contain" trace, but a product with no allergen or trace data entered passes them, so confirm a candidate with off_get_product before relying on it. At least one search parameter is required. The two paths read different indexes: a search carrying query, nutrient_filters, or ingredients_tag is answered by the text index, a snapshot that lags the live database, while a tag-only search reads the live database and is current, or, where this server keeps a local copy of the Open Food Facts export, can be served from that copy, which source and mirror_as_of then report and whose default order and popularity_key or unique_scans_n sort follow the values stored with each record, so they can differ from a live search, which ranks by its current scan counts — so a recently contributed product can be missing from a text search and present in the same search without query. Data is crowd-sourced; result count reflects contributed products, not all products in the market. Data under ODbL 1.0 — cite Open Food Facts in downstream use.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "off_search_products"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Use with page_size to paginate results. Pages are counted at the page_size served, which is at most 100, so repeating one larger page_size pages contiguously (page 2 at page_size 200 is results 101–200). A search by tag filters alone that reads the live database is served through page 10 only, so at page_size 100 it reaches the first 1000 matches; where this server keeps a local copy of the export, a tag-only search whose every value it confirms (canonical IDs from off_browse_taxonomy, or a brand slug) is served from that copy through its first 10000 results, so page * page_size (as served) must stay at or below 10000 there. One carrying ecoscore_grade is served from that copy only once a full reload of it has indexed Green-Score. A search carrying query, nutrient_filters, or ingredients_tag serves only the first 10000 results, so page * page_size (as served) must stay at or below 10000. A request past any of these bounds is rejected rather than sent; narrow the filters or change sort_by to bring other products forward. | |
| query | No | Words to find. Every word must match the product name, generic name, categories, labels, or brand — ingredients and quantity are not searched — so put only words the product itself would carry. Punctuation separates words — except an underscore, an apostrophe or period inside a word, and a decimal comma inside a number — so each part of "milk-chocolate" or "salt/pepper" must match, while "l'eau" and "1,5" stay one word. Stop words of English, French, Spanish, German, and Italian ("with", "the", "de", "mit", …) are not required, and neither is a content word that is a stop word in one of them (such as Spanish "soy"), though it still ranks the results. Names are matched in the 31 languages the text index analyzes, so a product named only in French is found by its French name. At most 24 words, counted as runs of letters and digits, so each part of a hyphenated or apostrophe-joined word counts. Example: "dark chocolate 70%". Supplying it routes the search to the text index, a snapshot that lags the live Open Food Facts database; drop it, and nutrient_filters and ingredients_tag, which route there too, to run the same tag filters against the live database or, where this server keeps one, its local copy of the export. | |
| sort_by | No | Sort order, applied on every search. Each value orders newest or highest first: "unique_scans_n" surfaces the most-scanned products, "last_modified_t" and "created_t" the most recently updated and newest records, "popularity_key" the most popular. Omitting it leaves text searches relevance-ranked and tag-only searches in the default order. Where this server serves a tag-only search from its local copy of the export (source "off_mirror"), the default order and "popularity_key" and "unique_scans_n" follow the values stored with each record, so they can differ from a live search, which ranks by its current scan counts; "last_modified_t" and "created_t" sort alike. | |
| page_size | No | Results per page (default 20). One call returns at most 100: a larger value is served at 100, reported in page_size and page_size_capped, and page then counts pages of 100. Keep low for initial exploration; increase for comparison workflows. | |
| brands_tag | No | Brand slug (lowercased, hyphenated). Example: "nutella", "kelloggs". A brand name is slugged the way Open Food Facts slugs it ("Ben & Jerry's" → "ben-jerry-s") and then matched exactly — a partial or misspelled slug matches nothing rather than falling back to a near match, so put open-ended brand wording in query instead. | |
| labels_tag | No | Canonical label/certification tag ID, or an array of up to 10 that must all apply. Example: "en:organic", or ["en:organic", "en:fair-trade"] for products carrying both. Use off_browse_taxonomy with facet="labels". | |
| nova_group | No | Filter by NOVA food processing class, or an array of classes matching any of them. "1"=unprocessed/minimally processed, "4"=ultra-processed. Example: "1", or ["1", "2"]. A product is in one class, so an array matches products in any of its classes, unlike labels_tag, whose values must all apply. Products without a NOVA score are excluded. | |
| traces_tag | No | Canonical allergen tag ID the label warns the product may contain as a trace ("may contain nuts"). Example: "en:nuts". Trace tags are allergen tags, so off_browse_taxonomy with facet="allergens" resolves them. Selects products carrying the warning; to leave them out, use exclude_traces. | |
| additives_tag | No | Canonical additive (E-number) tag ID. Example: "en:e322", "en:e330". Use off_browse_taxonomy with facet="additives". Available only on searches carrying none of query, nutrient_filters, or ingredients_tag — each routes to a backend with no additives field, so combining them is rejected instead of silently returning nothing. | |
| allergens_tag | No | Canonical allergen tag ID. Example: "en:milk", "en:gluten". Use off_browse_taxonomy with facet="allergens". Selects products that declare this allergen; it cannot select allergen-free products, because a product with no allergen tags may simply have none entered yet. To leave an allergen out, use exclude_allergens. | |
| countries_tag | No | Canonical country tag ID. Example: "en:france", "en:united-states". Filters to products sold in that country. | |
| categories_tag | No | Canonical category tag ID. Example: "en:breakfast-cereals", "en:cheeses". Use off_browse_taxonomy with facet="categories" to discover valid values. | |
| ecoscore_grade | No | Filter by Green-Score (environmental impact) grade, or an array of grades matching any of them: "a-plus" is the lowest impact, then "a" through "f". "a" does not include "a-plus", so ask for ["a-plus", "a"] for A or better. A product carries one grade, so an array matches products graded any of its values, unlike labels_tag, whose values must all apply. A search by tag filters alone, without ingredients_tag, matches the grade Open Food Facts files for France, while each row shows the world grade, so a row can show a different letter than the one it matched. Products without a Green-Score are excluded. | |
| exclude_traces | No | Allergen tag IDs a product's label must not warn it may contain as traces, all applied. Example: ["en:nuts"]. Values are validated like exclude_allergens. A product with no trace data entered passes, so check a candidate with off_get_product before relying on it. | |
| ingredients_tag | No | Canonical ingredient tag ID, or an array of up to 10 that must all appear among the ingredients Open Food Facts parsed from the label. Example: "en:inulin", or ["en:inulin", "en:oat"] for products listing both. IDs are singular ("en:oat", not "en:oats"); use off_browse_taxonomy with facet="ingredients" to resolve them, and use ingredients_analysis_tag instead for a vegan, vegetarian, or palm-oil verdict. Each parsed ingredient also carries its taxonomy parents, so "en:vegetable" matches a product listing carrot. Served only by the text index, so supplying one routes the search there even without query — it then reads the lagging text index and is subject to the 10000-result page window, and additives_tag cannot be combined with it. | |
| nutrition_grade | No | Filter by Nutri-Score grade, or an array of grades matching any of them. "a" is highest nutritional quality, "e" is lowest. Example: "a", or ["a", "b"] for B or better. A product carries one grade, so an array matches products graded any of its values, unlike labels_tag, whose values must all apply. Products without a score are excluded. | |
| nutrient_filters | No | Numeric constraints on nutrient values per 100 g, or per 100 ml for liquids, combined as AND with each other and with every other filter. Pair two entries on the same nutrient to express a range (e.g. sugars gte 2 and sugars lte 8). Served only by the text backend, so supplying one routes the search there even without query — it then reads the lagging text index and is subject to the 10,000-result page window, and additives_tag cannot be combined with it. The text index compares energy-kcal, fat, saturated-fat, carbohydrates, sugars as whole numbers, so every returned row is checked against these constraints: a row outside them leaves the page and counts in outside_constraints, and a nutrient the index holds no value for does not count against a row. A page can come back short or empty while later pages hold matches, and a range inside one whole number (sugars gt 3.9 and lt 4) can pass few rows of the 10,000 reachable, so add query or tag filters to narrow it. Per-serving and prepared-product values are not searchable. | |
| exclude_allergens | No | Allergen tag IDs a product must not declare, all applied. Example: ["en:nuts", "en:peanuts"]. Each value must be an allergen tag Open Food Facts recognizes — resolve it with off_browse_taxonomy facet="allergens" — and one it does not recognize is rejected rather than sent, because it would exclude nothing. A product with no allergen data entered passes an exclusion, so check a candidate with off_get_product before relying on it. | |
| ingredients_analysis_tag | No | Vegan, vegetarian, or palm-oil verdict Open Food Facts computes from the parsed ingredients. Example: "en:vegan", "en:palm-oil-free". "en:maybe-vegan" and "en:may-contain-palm-oil" mean the ingredients could not settle it, and the "-unknown" values mean no verdict could be computed. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The page_size that was applied. | |
| page | No | Current page number (1-based). | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of products returned on this page. | |
| total | No | Matching products in the database for this search. Exact unless total_is_lower_bound is true, in which case at least this many match and the real figure is unknown. On a search constraining a nutrient the text index compares as a whole number (see nutrient_filters) this is its whole-number answer, which can include rows those constraints rule out. | |
| notice | No | Guidance about this result set — echoes the filters and suggests how to broaden when nothing matched, names the current page and how far the backend will actually paginate when more results exist, or, on a page that returned no rows because it lies past the last match or every row was left off, says which page to request instead. When rows outside nutrient_filters emptied the page and more rows can be reached or lie past the window, it also suggests adding query or tag filters. | |
| source | No | Where this answer was read: "off_api", Open Food Facts itself, or "off_mirror", this server's local copy of the Open Food Facts export, which serves a search by tag filters alone on a deployment that keeps one. | |
| omitted | No | Matches on this page left off because Open Food Facts stores them under a code it cannot serve (not 4–40 digits once leading zeros are stripped), so off_get_product could not look them up either. Absent when none was. total still counts them. | |
| products | No | Matching products. Use barcodes with off_get_product for full label data. | |
| last_page | No | Deepest page of this result set that holds products and can be requested, at the page_size served — capped at page 10 on a search by tag filters alone that read the live database, by the 10000-result window on a search the text index answers, and by the local copy's 10000-result window when source is "off_mirror". Absent when total_is_lower_bound is true — the total it would divide is the ceiling the backend stopped counting at, so no exact last page exists — and when nothing matched at all. On a search constraining a whole-number nutrient it counts pages of the whole-number answer, so a page up to it can list few products or none. | |
| page_size | No | The page_size served: the one requested, or 100 when a larger one was requested. page and last_page count pages of this size. | |
| truncated | No | True when more results exist beyond this page. Absent on the final page of a result set. | |
| page_count | No | Products returned on this page — page_size except on the last page, or when a match stored under a code Open Food Facts cannot serve or a row outside nutrient_filters was left off. Not the total number of pages. | |
| mirror_as_of | No | ISO 8601 time up to which the local copy reflects every product contributed or edited on Open Food Facts. Present only when source is "off_mirror". | |
| mirror_snapshot | No | Present only when source is "off_mirror". States that the results come from the local copy as of mirror_as_of, so a product contributed or edited since is missing or shown as it was, and, under the default order or a popularity_key or unique_scans_n sort, that the order follows the values stored with each record and can differ from a live search. | |
| page_size_capped | No | Present only when page_size was above 100: names the page_size requested and the 100 served, and, when a further page holds matches and can be requested, the page to request next and the results it holds. | |
| exclusion_coverage | No | Present only on searches carrying exclude_allergens or exclude_traces. States that products with no allergen or trace data entered pass an exclusion, so a result is not confirmed free of the excluded allergens, and names the off_get_product fields to check. | |
| outside_constraints | No | Rows the text index returned on this page that fail nutrient_filters on their indexed values, compared at the 32-bit precision the index uses, and so left off. The index returns them because it compares some nutrients as whole numbers. Separate from omitted, whose rows are matches; a row both unservable and outside counts only in omitted. total, total_is_lower_bound, and last_page still count these rows, and each page keeps its place in the result set. Absent when none was. | |
| text_index_snapshot | No | Present only on searches the text backend answered. States that those results come from an index snapshot that lags the live Open Food Facts database, so a recently contributed product can be missing from them while the tag-only path still returns it. On a search carrying nutrition_grade, nova_group, or ecoscore_grade it also says those filters were matched against the grades the index holds, which each row shows and which can differ from what off_get_product returns. On a search carrying nutrient_filters it also echoes the constraints and says they were checked against the index values each row carries as indexed_nutriments, which can differ from what off_get_product returns. When a constraint falls on a whole-number nutrient (see nutrient_filters) it also says that total, total_is_lower_bound, and last_page describe the whole-number answer and that rows outside the constraints count in outside_constraints. Absent on tag-only searches, which read the live database or, when source is "off_mirror", the local copy mirror_snapshot describes. | |
| total_is_lower_bound | No | True when the backend stopped counting at its ceiling and total is a floor, not the match total. Only text searches can hit it; add filters to bring the result set under the ceiling and get an exact count. On a search constraining a whole-number nutrient the floor is on the whole-number answer, not on the products that meet the constraints. |