Search 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.
View input schema
{
"type": "object",
"properties": {
"query": {
"description": "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.",
"type": "string"
},
"categories_tag": {
"description": "Canonical category tag ID. Example: \"en:breakfast-cereals\", \"en:cheeses\". Use off_browse_taxonomy with facet=\"categories\" to discover valid values.",
"type": "string"
},
"brands_tag": {
"description": "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.",
"type": "string"
},
"labels_tag": {
"description": "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\".",
"anyOf": [
{
"type": "string",
"description": "One canonical label tag ID."
},
{
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"description": "One canonical label tag ID."
},
"description": "Up to 10 canonical label tag IDs, all of which must apply."
}
]
},
"allergens_tag": {
"description": "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.",
"type": "string"
},
"traces_tag": {
"description": "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.",
"type": "string"
},
"exclude_allergens": {
"description": "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.",
"maxItems": 14,
"type": "array",
"items": {
"type": "string",
"description": "One canonical allergen tag ID to exclude, e.g. \"en:nuts\"."
}
},
"exclude_traces": {
"description": "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.",
"maxItems": 14,
"type": "array",
"items": {
"type": "string",
"description": "One canonical allergen tag ID to exclude as a trace, e.g. \"en:nuts\"."
}
},
"ingredients_analysis_tag": {
"description": "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.",
"type": "string",
"enum": [
"en:palm-oil",
"en:palm-oil-free",
"en:may-contain-palm-oil",
"en:palm-oil-content-unknown",
"en:vegan",
"en:maybe-vegan",
"en:non-vegan",
"en:vegan-status-unknown",
"en:vegetarian",
"en:maybe-vegetarian",
"en:non-vegetarian",
"en:vegetarian-status-unknown"
]
},
"ingredients_tag": {
"description": "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.",
"anyOf": [
{
"type": "string",
"description": "One canonical ingredient tag ID."
},
{
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"description": "One canonical ingredient tag ID."
},
"description": "Up to 10 canonical ingredient tag IDs, all of which must appear."
}
]
},
"additives_tag": {
"description": "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.",
"type": "string"
},
"nutrition_grade": {
"description": "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.",
"anyOf": [
{
"type": "string",
"enum": [
"a",
"b",
"c",
"d",
"e"
],
"description": "One Nutri-Score grade."
},
{
"maxItems": 5,
"type": "array",
"items": {
"type": "string",
"enum": [
"a",
"b",
"c",
"d",
"e"
],
"description": "One Nutri-Score grade."
},
"description": "Nutri-Score grades, any of which a product may carry."
}
]
},
"nova_group": {
"description": "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.",
"anyOf": [
{
"type": "string",
"enum": [
"1",
"2",
"3",
"4"
],
"description": "One NOVA group."
},
{
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": [
"1",
"2",
"3",
"4"
],
"description": "One NOVA group."
},
"description": "NOVA groups, any of which a product may be in."
}
]
},
"ecoscore_grade": {
"description": "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.",
"anyOf": [
{
"type": "string",
"enum": [
"a-plus",
"a",
"b",
"c",
"d",
"e",
"f"
],
"description": "One Green-Score grade."
},
{
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"a-plus",
"a",
"b",
"c",
"d",
"e",
"f"
],
"description": "One Green-Score grade."
},
"description": "Green-Score grades, any of which a product may carry."
}
]
},
"countries_tag": {
"description": "Canonical country tag ID. Example: \"en:france\", \"en:united-states\". Filters to products sold in that country.",
"type": "string"
},
"nutrient_filters": {
"description": "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.",
"maxItems": 18,
"type": "array",
"items": {
"type": "object",
"properties": {
"nutrient": {
"type": "string",
"enum": [
"energy-kcal",
"fat",
"saturated-fat",
"carbohydrates",
"sugars",
"fiber",
"proteins",
"salt",
"sodium"
],
"description": "Nutrient to constrain, measured per 100 g, or per 100 ml for liquids. Energy is kilocalories; every other value is grams."
},
"operator": {
"type": "string",
"enum": [
"lt",
"lte",
"gt",
"gte"
],
"description": "Comparison against value: \"lt\" below, \"lte\" at or below, \"gt\" above, \"gte\" at or above."
},
"value": {
"type": "number",
"minimum": 0,
"description": "Threshold to compare against: kilocalories for energy, grams for every other nutrient, per 100 g, or per 100 ml for liquids."
}
},
"required": [
"nutrient",
"operator",
"value"
],
"description": "One numeric constraint on a nutrient value per 100 g, or per 100 ml for liquids."
}
},
"sort_by": {
"description": "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.",
"type": "string",
"enum": [
"last_modified_t",
"unique_scans_n",
"created_t",
"popularity_key"
]
},
"page": {
"default": 1,
"description": "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.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"page_size": {
"default": 20,
"description": "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.",
"type": "number",
"minimum": 1,
"multipleOf": 1
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}