openfoodfacts-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['facet'], 'properties': {'facet': {'enum': ['categories', 'labels', 'allergens', 'additives', 'countries', 'nova_groups', 'nutrition_grades'], 'type': 'string', 'description': '"categories" covers food categories (en:cheeses, en:breakfast-cereals). "labels" covers certifications (en:organic, en:fair-trade). "allergens" covers declared allergens (en:milk, en:gluten). "additives" covers E-numbers (en:e322). "countries" covers country-of-sale tags (en:france). "nova_groups" and "nutrition_grades" are closed vocabularies returned complete; the other five are resolved against the Open Food Facts taxonomy.'}, 'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Maximum entries to return (1â\x80\x93100, default 20). There is no offset or page input: Open Food Facts offers no cursor for this lookup, so narrow the search term rather than paging. The tag spelling the term itself (e.g. "lentil" â\x86\x92 en:lentils) is listed first among the live matches, so it is not the one a small limit cuts.'}, 'search': {'type': 'string', 'description': 'Term to resolve. Matched case-insensitively as a substring of the tag ID, the display name, or a common synonym of either ("shellfish" resolves to en:crustaceans, "gluten free" to en:no-gluten). A single word works best ("hummus", not "hummus dip"). Omit only to see a small reference list â\x80\x94 Open Food Facts cannot list the full vocabulary without a term, so an unfiltered call is not a view of the full facet.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['facet', 'tags']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The limit that was applied.'}, 'tags': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'name'], 'properties': {'id': {'type': 'string', 'description': 'Canonical tag ID (e.g. "en:organic"; bare "1"â\x80\x93"4" for NOVA groups, bare "a"â\x80\x93"e" for Nutri-Score grades). Pass this value through to the matching off_search_products filter parameter unchanged.'}, 'name': {'type': 'string', 'description': 'Human-readable display name (e.g. "Organic").'}}, 'description': 'A single taxonomy tag entry with its canonical ID and display name.', 'additionalProperties': False}, 'description': 'Matching tag entries.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': 'Machine-readable failure mode.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'facet': {'type': 'string', 'description': 'The facet name that was queried (echoes the input).'}, 'shown': {'type': 'number', 'description': 'Number of tags returned.'}, 'notice': {'type': 'string', 'description': 'Caveat about the answer â\x80\x94 that the listing is a limited reference list rather than the full vocabulary, that Open Food Facts was unreachable, or that nothing matched and why.'}, 'truncated': {'type': 'boolean', 'description': 'True when more tags exist beyond the limit.'}, 'total_in_facet': {'type': 'number', 'description': 'Total entries in this facet. Present only for nova_groups and nutrition_grades, whose vocabularies are closed and complete. Absent for the other facets: Open Food Facts reports no match total and cannot enumerate them, so no figure would be a real one.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['barcodes'], 'properties': {'barcodes': {'type': 'array', 'items': {'type': 'string', 'pattern': '^0*[1-9]\\d{3,39}$', 'description': 'Product barcode, digits only: 4â\x80\x9340 digits after any leading zeros.'}, 'maxItems': 10, 'minItems': 2, 'description': '2â\x80\x9310 barcodes to compare, returned as one row each in input order. Example: ["3017620422003", "7622210100146"].'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['products', 'succeeded', 'not_found']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['upstream_error', 'upstream_timeout', 'upstream_rejected', 'rate_limited'], 'description': "Machine-readable failure mode. Declared by this tool: `upstream_error`: Open Food Facts returns a 5xx other than 501, serves an HTML error page with a 2xx or 5xx status, or is unreachable â\x80\x94 surfaced per barcode in failed[]. `upstream_timeout`: Open Food Facts did not answer within the request deadline â\x80\x94 surfaced per barcode in failed[]. `upstream_rejected`: Open Food Facts answers 4xx or 501 Not Implemented for a barcode â\x80\x94 surfaced per barcode in failed[]. `rate_limited`: This server's own per-minute request budget is spent, or Open Food Facts answers 429 â\x80\x94 surfaced per barcode in failed[]. Other values are possible when a failure originates below the handler."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'failed': {'type': 'array', 'items': {'type': 'object', 'required': ['barcode', 'reason', 'error'], 'properties': {'error': {'type': 'string', 'description': 'What went wrong for this barcode and what to do about it.'}, 'reason': {'type': 'string', 'description': 'Declared failure reason â\x80\x94 one of upstream_error, upstream_timeout, upstream_rejected, rate_limited.'}, 'barcode': {'type': 'string', 'description': 'Barcode whose fetch failed, as provided in input.'}}, 'description': 'A single barcode whose fetch failed.', 'additionalProperties': False}, 'description': 'Barcodes whose fetch failed, with the per-barcode reason. Absent when every fetch completed. A barcode listed here is unknown, not absent from Open Food Facts â\x80\x94 retry it with off_get_product before concluding anything about the product.'}, 'products': {'type': 'array', 'items': {'type': 'object', 'required': ['barcode', 'found'], 'properties': {'found': {'type': 'boolean', 'description': 'False if the barcode has no contributor record.'}, 'brands': {'type': 'string', 'description': 'Brand name(s), comma-separated. Absent when not yet entered.'}, 'barcode': {'type': 'string', 'description': 'Barcode, echoed exactly as provided in input.'}, 'fat_100g': {'type': 'number', 'description': 'Total fat per 100g in grams. Absent when not entered.'}, 'salt_100g': {'type': 'number', 'description': 'Salt per 100g in grams. Absent when not entered.'}, 'fiber_100g': {'type': 'number', 'description': 'Dietary fiber per 100g in grams. Often absent.'}, 'nova_group': {'type': 'number', 'description': 'NOVA processing class (1â\x80\x934). Absent when not assigned.'}, 'sugars_100g': {'type': 'number', 'description': 'Total sugars per 100g in grams. Absent when not entered.'}, 'completeness': {'type': 'number', 'description': 'Data completeness 0â\x80\x931. Low values mean many fields are missing.'}, 'product_name': {'type': 'string', 'description': 'Product name. Absent when not yet entered by contributors.'}, 'proteins_100g': {'type': 'number', 'description': 'Protein per 100g in grams. Absent when not entered.'}, 'ecoscore_grade': {'type': 'string', 'description': 'Green-Score (formerly Eco-Score) environmental impact grade: "a-plus" (lowest impact), then "a" through "f"; "unknown" when the data it needs is missing, or "not-applicable" for product categories the score does not cover. Often absent.'}, 'energy_kcal_100g': {'type': 'number', 'description': 'Energy per 100g in kcal. Absent when not entered.'}, 'nutriscore_grade': {'type': 'string', 'description': 'Nutri-Score grade: "a" through "e", "unknown" when the nutrition data entered is not enough to compute it, or "not-applicable" for product categories the score does not cover. Absent when Open Food Facts sent none.'}, 'saturated_fat_100g': {'type': 'number', 'description': 'Saturated fat per 100g in grams. Absent when not entered.'}}, 'description': 'A single product comparison row.', 'additionalProperties': False}, 'description': 'Comparison rows in input order â\x80\x94 one per barcode whose fetch completed, whether or not a record exists. Barcodes whose fetch failed have no row here; they appear in failed.'}, 'not_found': {'type': 'array', 'items': {'type': 'string', 'description': 'Barcode with no contributor record, as provided in input.'}, 'description': 'Barcodes Open Food Facts answered for, confirming no contributor record exists. Not an error â\x80\x94 the product may exist but not yet be entered. Never used for a fetch that failed.'}, 'succeeded': {'type': 'number', 'description': 'Number of barcodes that resolved to a found product.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['barcode'], 'properties': {'fields': {'type': 'array', 'items': {'enum': ['product_name', 'brands', 'quantity', 'ingredients_text', 'ingredients', 'allergens_tags', 'traces_tags', 'additives_tags', 'ingredients_analysis_tags', 'nutriscore_grade', 'nova_group', 'ecoscore_grade', 'nutriments', 'serving_size', 'serving_quantity', 'serving_quantity_unit', 'categories_tags', 'labels_tags', 'packaging_tags', 'origins_tags', 'countries_tags', 'image_url', 'completeness', 'data_quality_tags'], 'type': 'string', 'description': 'A specific product field to include in the response.'}, 'description': 'Subset of fields to return. Omitting returns all standard fields. Use to reduce payload when only scores or ingredients are needed. A field that cannot be read on its own arrives with what it depends on: nutriments brings serving_size, serving_quantity, and serving_quantity_unit so per-serving figures carry their denominator, and serving_quantity_unit brings the quantity it describes. requested_fields echoes the full set that was fetched.'}, 'barcode': {'type': 'string', 'pattern': '^0*[1-9]\\d{3,39}$', 'description': 'Product barcode, digits only: 4â\x80\x9340 digits after any leading zeros. The primary key for Open Food Facts â\x80\x94 the barcode of an off_search_products row works as is. Example: "3017620422003" (Nutella FR).'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['barcode', 'product']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['not_found', 'upstream_error', 'upstream_timeout', 'upstream_rejected', 'rate_limited'], 'description': "Machine-readable failure mode. Declared by this tool: `not_found`: Barcode status:0 â\x80\x94 not present in any contributor record. `upstream_error`: Open Food Facts returns a 5xx other than 501, serves an HTML error page with a 2xx or 5xx status, or is unreachable. `upstream_timeout`: Open Food Facts did not answer within the request deadline. `upstream_rejected`: Open Food Facts answers 4xx for something other than a missing barcode, or 501 Not Implemented. `rate_limited`: This server's own per-minute request budget is spent, or Open Food Facts answers 429. Other values are possible when a failure originates below the handler."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'barcode': {'type': 'string', 'description': 'The input barcode, echoed back unchanged. Open Food Facts can hold the record under another form of the same code (030000010402 resolves to the record stored as 0030000010402); that stored form is not reported.'}, 'product': {'type': 'object', 'properties': {'brands': {'type': 'string', 'description': 'Brand name(s), comma-separated.'}, 'quantity': {'type': 'string', 'description': 'Net quantity as printed on packaging (e.g. "400g").'}, 'image_url': {'type': 'string', 'description': 'Front image URL (CDN-hosted JPEG).'}, 'nova_group': {'type': 'number', 'description': 'NOVA food processing class (1=unprocessed, 2=culinary ingredients, 3=processed, 4=ultra-processed). Absent when not enough data.'}, 'nutriments': {'type': 'object', 'properties': {'fat_100g': {'type': 'number', 'description': 'Total fat per 100g in grams.'}, 'salt_100g': {'type': 'number', 'description': 'Salt per 100g in grams.'}, 'fiber_100g': {'type': 'number', 'description': 'Dietary fiber per 100g in grams. Often absent.'}, 'fat_serving': {'type': 'number', 'description': 'Total fat per serving in grams. Absent when serving size not defined.'}, 'sodium_100g': {'type': 'number', 'description': 'Sodium per 100g in grams.'}, 'sugars_100g': {'type': 'number', 'description': 'Total sugars per 100g in grams.'}, 'proteins_100g': {'type': 'number', 'description': 'Protein per 100g in grams.'}, 'sugars_serving': {'type': 'number', 'description': 'Sugars per serving in grams. Absent when serving size not defined.'}, 'additional_100g': {'type': 'object', 'description': 'Every other per-100g nutrient Open Food Facts holds, keyed by normalized name (calcium, iron, vitamin_c, trans_fat, added_sugars, cholesterol, energy in kJ, â\x80¦). Excludes the named fields above, so a nutrient appears in exactly one place. Micronutrients are usually reported in grams, so calcium 0.071 g is 71 mg â\x80\x94 read the unit rather than assuming.', 'propertyNames': {'type': 'string', 'description': 'Nutrient name, hyphens normalized to underscores.'}, 'additionalProperties': {'type': 'object', 'required': ['value'], 'properties': {'unit': {'type': 'string', 'description': 'Unit the figure is expressed in ("g", "kcal", "kJ"). Absent when Open Food Facts records no unit for this nutrient.'}, 'value': {'type': 'number', 'description': 'The figure Open Food Facts reported per 100g.'}}, 'description': 'One nutrient figure with the unit it is expressed in.', 'additionalProperties': False}}, 'energy_kcal_100g': {'type': 'number', 'description': 'Energy per 100g in kcal.'}, 'additional_serving': {'type': 'object', 'description': 'The same nutrients per serving. Also carries the per-serving figures for macros that have a named per-100g field but no named per-serving one (saturated_fat, carbohydrates, fiber, proteins, salt, sodium). Check serving_size for the denominator these figures are measured against.', 'propertyNames': {'type': 'string', 'description': 'Nutrient name, hyphens normalized to underscores.'}, 'additionalProperties': {'type': 'object', 'required': ['value'], 'properties': {'unit': {'type': 'string', 'description': 'Unit the figure is expressed in ("g", "kcal", "kJ"). Absent when Open Food Facts records no unit for this nutrient.'}, 'value': {'type': 'number', 'description': 'The figure Open Food Facts reported per serving.'}}, 'description': 'One nutrient figure with the unit it is expressed in.', 'additionalProperties': False}}, 'carbohydrates_100g': {'type': 'number', 'description': 'Total carbohydrates per 100g in grams.'}, 'saturated_fat_100g': {'type': 'number', 'description': 'Saturated fat per 100g in grams.'}, 'energy_kcal_serving': {'type': 'number', 'description': 'Energy per serving in kcal. Absent when serving size not defined.'}}, 'description': 'Nutrition figures normalized to underscore keys. All values may be absent when nutrition data not yet entered.', 'additionalProperties': False}, 'ingredients': {'type': 'array', 'items': {'type': 'object', 'required': ['text'], 'properties': {'id': {'type': 'string', 'description': 'Canonical ingredient ID (e.g. "en:sugar", "en:salt").'}, 'text': {'type': 'string', 'description': 'Ingredient name as it appears in the list.'}, 'vegan': {'type': 'string', 'description': '"yes", "no", or "maybe" â\x80\x94 absent when unknown.'}, 'vegetarian': {'type': 'string', 'description': '"yes", "no", or "maybe" â\x80\x94 absent when unknown.'}, 'ingredients': {'type': 'array', 'items': {'type': 'object', 'required': ['text'], 'properties': {'id': {'type': 'string', 'description': 'Canonical ingredient ID (e.g. "en:sugar", "en:salt").'}, 'text': {'type': 'string', 'description': 'Ingredient name as it appears in the list.'}, 'vegan': {'type': 'string', 'description': '"yes", "no", or "maybe" â\x80\x94 absent when unknown.'}, 'vegetarian': {'type': 'string', 'description': '"yes", "no", or "maybe" â\x80\x94 absent when unknown.'}, 'ingredients': {'type': 'array', 'items': {'type': 'object', 'required': ['text'], 'properties': {'id': {'type': 'string', 'description': 'Canonical ingredient ID (e.g. "en:sugar", "en:salt").'}, 'text': {'type': 'string', 'description': 'Ingredient name as it appears in the list.'}, 'vegan': {'type': 'string', 'description': '"yes", "no", or "maybe" â\x80\x94 absent when unknown.'}, 'vegetarian': {'type': 'string', 'description': '"yes", "no", or "maybe" â\x80\x94 absent when unknown.'}, 'percent_estimate': {'type': 'number', 'description': "Estimated share of the whole product, in percent. On a sub-ingredient it is still a share of the whole product, not of its parent â\x80\x94 a parent's estimate already includes its sub-ingredients, so summing across levels double-counts."}}, 'description': 'A sub-ingredient at the third level. An entry nested deeper upstream is listed at this level too, directly after the entry it belongs under.', 'additionalProperties': False}, 'description': 'Sub-ingredients of this entry. Anything nested deeper upstream is listed here as well, right after the entry it belongs under, so no entry is dropped. Absent when the entry has none.'}, 'percent_estimate': {'type': 'number', 'description': "Estimated share of the whole product, in percent. On a sub-ingredient it is still a share of the whole product, not of its parent â\x80\x94 a parent's estimate already includes its sub-ingredients, so summing across levels double-counts."}}, 'description': 'A sub-ingredient of a top-level entry.', 'additionalProperties': False}, 'description': 'Sub-ingredients of this entry (e.g. the flours under "cereal"), in the same entry shape and nested up to two more levels. Absent when the entry has none.'}, 'percent_estimate': {'type': 'number', 'description': "Estimated share of the whole product, in percent. On a sub-ingredient it is still a share of the whole product, not of its parent â\x80\x94 a parent's estimate already includes its sub-ingredients, so summing across levels double-counts."}}, 'description': 'A single top-level parsed ingredient entry.', 'additionalProperties': False}, 'description': 'Parsed ingredient list, top level in label order, each entry carrying its sub-ingredients. Absent when not yet parsed by contributors.'}, 'labels_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Canonical label/certification tag ID (e.g. "en:organic").'}, 'description': 'Label/certification tag IDs. Absence means not yet entered.'}, 'traces_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Canonical allergen tag ID (e.g. "en:nuts").'}, 'description': 'Allergens the label says the product may contain as traces, from cross-contamination warnings. Distinct from allergens_tags, which carries allergens declared in the ingredients. ["en:none"] means the label states no traces; an empty array or an absent field means not yet entered, not trace-free. Values resolve through off_browse_taxonomy\'s allergens facet.'}, 'completeness': {'type': 'number', 'description': 'Data completeness score from 0â\x80\x931. Below 0.5 indicates many fields are missing.'}, 'origins_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Ingredient origin tag ID (e.g. "en:france").'}, 'description': 'Ingredient origin tag IDs. Frequently empty.'}, 'product_name': {'type': 'string', 'description': 'Product name. May be absent if not yet entered by contributors.'}, 'serving_size': {'type': 'string', 'description': 'Serving size as printed on the label (e.g. "28 g", "1 can (12 fl oz)"). The denominator for every per-serving figure. Absent when contributors have not entered one, in which case per-serving values cannot be converted to or from the per-100g values.'}, 'additives_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'E-number additive tag ID (e.g. "en:e322", "en:e322i").'}, 'description': 'E-number additive tag IDs. Absence means not yet entered.'}, 'allergens_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Canonical allergen tag ID (e.g. "en:milk", "en:gluten").'}, 'description': 'Canonical allergen tag IDs. Absence means not yet entered â\x80\x94 not that the product is allergen-free.'}, 'countries_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Canonical country tag ID (e.g. "en:france").'}, 'description': 'Countries where the product is sold â\x80\x94 the same values off_search_products accepts as countries_tag. Distinct from origins_tags, which is where the ingredients come from.'}, 'ecoscore_grade': {'type': 'string', 'description': 'Green-Score (formerly Eco-Score) environmental impact grade: "a-plus" (lowest impact), then "a" through "f"; "unknown" when the data it needs is missing, or "not-applicable" for product categories the score does not cover. Highly variable â\x80\x94 depends on packaging, origins, and transport data completeness.'}, 'packaging_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Packaging material tag ID (e.g. "en:cardboard").'}, 'description': 'Packaging material tag IDs. Often absent.'}, 'categories_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Canonical category tag ID (e.g. "en:spreads").'}, 'description': 'Category tag IDs in canonical form. Use as filter values for off_search_products.'}, 'ingredients_text': {'type': 'string', 'description': 'Raw ingredients text from the label, in the source language.'}, 'nutriscore_grade': {'type': 'string', 'description': 'Nutri-Score grade, lowercase: "a" (highest nutritional quality) through "e", "unknown" when the nutrition data entered is not enough to compute it, or "not-applicable" for product categories the score does not cover. Absent when Open Food Facts sent none. Regional formula variants exist.'}, 'serving_quantity': {'type': 'number', 'description': 'Serving size parsed to a number, in serving_quantity_unit. Absent when Open Food Facts could not parse the printed serving size.'}, 'data_quality_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Crowd-sourced data quality flag (e.g. "en:nutrition-completed", "en:ingredients-completed-at-least-for-one-language").'}, 'description': 'Crowd-sourced data quality flags. Absence means not yet checked.'}, 'serving_quantity_unit': {'type': 'string', 'description': 'Unit of serving_quantity â\x80\x94 usually "g" but "ml" for liquids, so it is not safe to assume grams. Absent when serving_quantity is absent or Open Food Facts records no unit.'}, 'ingredients_analysis_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Analysis verdict tag (e.g. "en:non-vegan", "en:palm-oil-free").'}, 'description': 'Product-level vegan, vegetarian, and palm-oil verdicts computed by Open Food Facts from the parsed ingredients. "maybe-" and "-status-unknown" values mean the ingredients could not settle it (e.g. "en:maybe-vegan").'}}, 'description': 'Product data. Always present on a successful call â\x80\x94 a barcode with no contributor record raises the not_found error instead of returning an empty result.', 'additionalProperties': False}, 'requested_fields': {'type': 'array', 'items': {'type': 'string', 'description': 'A field name from the requested subset.'}, 'description': 'The field subset that was fetched, when the caller passed `fields` â\x80\x94 the requested fields plus the ones they depend on, so every field that can appear in `product` is named here. Absent means all standard fields were requested. Sections outside this subset are omitted because they were not requested â\x80\x94 not because Open Food Facts lacks the data.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'page': {'type': 'integer', 'default': 1, 'maximum': 9007199254740991, 'minimum': 1, 'description': 'Page number (1-based). Use with page_size to paginate results. A search by tag filters alone is served through page 10 only, so at page_size 50 it reaches the first 500 matches. A search carrying query or nutrient_filters serves only the first 10000 results, so page * page_size must stay at or below 10000. A request past either bound is rejected rather than sent; narrow the filters or change sort_by to bring other products forward.'}, 'query': {'type': 'string', 'description': 'Words to find. Every word must match the product name, generic name, categories, labels, or brand â\x80\x94 ingredients and quantity are not searched â\x80\x94 so put only words the product itself would carry. Stop words of English, French, Spanish, German, and Italian ("with", "the", "de", "mit", â\x80¦) 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, counting each part of a hyphenated word. 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 to run the same tag filters against the current data.'}, 'sort_by': {'enum': ['last_modified_t', 'unique_scans_n', 'created_t', 'popularity_key'], 'type': 'string', '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.'}, 'page_size': {'type': 'integer', 'default': 20, 'maximum': 50, 'minimum': 1, 'description': 'Results per page (1â\x80\x9350, default 20). Keep low for initial exploration; increase for comparison workflows.'}, 'brands_tag': {'type': 'string', 'description': 'Brand slug (lowercased, hyphenated). Example: "nutella", "kelloggs". A brand name is slugged the way Open Food Facts slugs it ("Ben & Jerry\'s" â\x86\x92 "ben-jerry-s") and then matched exactly â\x80\x94 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': {'anyOf': [{'type': 'string', 'description': 'One canonical label tag ID.'}, {'type': 'array', 'items': {'type': 'string', 'description': 'One canonical label tag ID.'}, 'maxItems': 10, 'description': 'Up to 10 canonical label tag IDs, all of which must apply.'}], '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".'}, 'nova_group': {'enum': ['1', '2', '3', '4'], 'type': 'string', 'description': 'Filter by NOVA food processing class. "1"=unprocessed/minimally processed, "4"=ultra-processed. Products without a NOVA score are excluded.'}, 'traces_tag': {'type': 'string', '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.'}, 'additives_tag': {'type': 'string', 'description': 'Canonical additive (E-number) tag ID. Example: "en:e322", "en:e330". Use off_browse_taxonomy with facet="additives". Available only on searches carrying neither query nor nutrient_filters â\x80\x94 both route to a backend with no additives field, so combining them is rejected instead of silently returning nothing.'}, 'allergens_tag': {'type': 'string', '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.'}, 'countries_tag': {'type': 'string', 'description': 'Canonical country tag ID. Example: "en:france", "en:united-states". Filters to products sold in that country.'}, 'categories_tag': {'type': 'string', 'description': 'Canonical category tag ID. Example: "en:breakfast-cereals", "en:cheeses". Use off_browse_taxonomy with facet="categories" to discover valid values.'}, 'exclude_traces': {'type': 'array', 'items': {'type': 'string', 'description': 'One canonical allergen tag ID to exclude as a trace, e.g. "en:nuts".'}, 'maxItems': 14, '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.'}, 'nutrition_grade': {'enum': ['a', 'b', 'c', 'd', 'e'], 'type': 'string', 'description': 'Filter by Nutri-Score grade. "a" is highest nutritional quality, "e" is lowest. Products without a score are excluded.'}, 'nutrient_filters': {'type': 'array', 'items': {'type': 'object', 'required': ['nutrient', 'operator', 'value'], 'properties': {'value': {'type': 'number', 'minimum': 0, 'description': "Threshold to compare against, in the nutrient's per-100 g unit."}, 'nutrient': {'enum': ['energy-kcal', 'fat', 'saturated-fat', 'carbohydrates', 'sugars', 'fiber', 'proteins', 'salt', 'sodium'], 'type': 'string', 'description': 'Nutrient to constrain, measured per 100 g. Energy is kilocalories; every other value is grams per 100 g.'}, 'operator': {'enum': ['lt', 'lte', 'gt', 'gte'], 'type': 'string', 'description': 'Comparison against value: "lt" below, "lte" at or below, "gt" above, "gte" at or above.'}}, 'description': 'One numeric constraint on a per-100 g nutrient value.'}, 'maxItems': 18, 'description': 'Numeric constraints on nutrient values per 100 g, 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 â\x80\x94 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. Per-serving and prepared-product values are not searchable.'}, 'exclude_allergens': {'type': 'array', 'items': {'type': 'string', 'description': 'One canonical allergen tag ID to exclude, e.g. "en:nuts".'}, 'maxItems': 14, '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 â\x80\x94 resolve it with off_browse_taxonomy facet="allergens" â\x80\x94 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': {'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'], 'type': 'string', '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.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['total', 'total_is_lower_bound', 'page', 'page_count', 'products']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'cap': {'type': 'number', 'description': 'The page_size that was applied.'}, 'page': {'type': 'number', 'description': 'Current page number (1-based).'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['no_filters', 'unrecognized_exclusion', 'additives_filter_needs_tag_search', 'query_too_long', 'page_out_of_range', 'upstream_error', 'upstream_timeout', 'upstream_rejected', 'rate_limited'], 'description': "Machine-readable failure mode. Declared by this tool: `no_filters`: No search query or filter was provided. `unrecognized_exclusion`: An exclude_allergens or exclude_traces value is not an allergen tag the Open Food Facts vocabulary confirms, or the vocabulary could not be reached to check it â\x80\x94 an unrecognized exclusion would exclude nothing. `additives_filter_needs_tag_search`: additives_tag was combined with a query or nutrient_filters, which route to a backend that cannot filter by additive. `query_too_long`: query carries more than 24 words, more than the text backend can require at once. `page_out_of_range`: A search by tag filters alone asks for a page past 10, or a search the text backend serves asks for page * page_size beyond its 10000-result window. `upstream_error`: Open Food Facts returns a 5xx other than 501, serves an HTML error page with a 2xx or 5xx status, reports a search-engine failure inside an HTTP 200, or is unreachable. `upstream_timeout`: Open Food Facts did not answer within the request deadline. `upstream_rejected`: Open Food Facts answers 4xx or 501 Not Implemented â\x80\x94 the request as formed will be refused again. `rate_limited`: This server's own per-minute search budget is spent, or Open Food Facts answers 429. Other values are possible when a failure originates below the handler."}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'shown': {'type': 'number', 'description': 'Number of products returned on this page.'}, 'total': {'type': 'number', 'description': '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.'}, 'notice': {'type': 'string', 'description': 'Guidance about this result set â\x80\x94 echoes the filters and suggests how to broaden when nothing matched, or names the current page and how far the backend will actually paginate when more results exist.'}, 'omitted': {'type': 'number', 'description': 'Matches on this page left off because Open Food Facts stores them under a code it cannot serve (not 4â\x80\x9340 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': {'type': 'array', 'items': {'type': 'object', 'required': ['barcode'], 'properties': {'brands': {'type': 'string', 'description': 'Brand name(s), comma-separated. Absent when not yet entered.'}, 'barcode': {'type': 'string', 'description': 'Product barcode, 4â\x80\x9340 digits after any leading zeros â\x80\x94 a code off_get_product accepts as is, so pass it there for full details. A match stored under a code Open Food Facts cannot serve is left off the page.'}, 'nova_group': {'type': 'number', 'description': 'NOVA processing class (1â\x80\x934). Absent when not assigned.'}, 'product_name': {'type': 'string', 'description': 'Product name. May be absent for incompletely entered products.'}, 'ecoscore_grade': {'type': 'string', 'description': 'Green-Score environmental impact grade: "a-plus" (lowest impact), then "a" through "f"; "unknown" when the data it needs is missing, or "not-applicable" for product categories the score does not cover. Absent when Open Food Facts sent none.'}, 'categories_tags': {'type': 'array', 'items': {'type': 'string', 'description': 'Canonical category tag ID (e.g. "en:cheeses").'}, 'description': 'Category tag IDs in canonical form. Use as filter values for off_search_products.'}, 'nutriscore_grade': {'type': 'string', 'description': 'Nutri-Score grade: "a" through "e", "unknown" when the nutrition data entered is not enough to compute it, or "not-applicable" for product categories the score does not cover. Absent when Open Food Facts sent none.'}}, 'description': 'A single matching product summary row.', 'additionalProperties': False}, 'description': 'Matching products. Use barcodes with off_get_product for full label data.'}, 'last_page': {'type': 'number', 'description': 'Deepest page of this result set that holds products and can be requested, at the page_size used â\x80\x94 capped at page 10 on a search by tag filters alone and by the 10000-result window on a search the text index answers. Absent when total_is_lower_bound is true â\x80\x94 the total it would divide is the ceiling the backend stopped counting at, so no exact last page exists â\x80\x94 and when nothing matched at all.'}, 'truncated': {'type': 'boolean', 'description': 'True when more results exist beyond this page.'}, 'page_count': {'type': 'number', 'description': 'Products returned on this page â\x80\x94 page_size except on the last page, or when a match stored under a code Open Food Facts cannot serve was left off. Not the total number of pages.'}, 'exclusion_coverage': {'type': 'string', 'description': '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.'}, 'text_index_snapshot': {'type': 'string', 'description': '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. Absent on tag-only searches, which read the live database.'}, 'total_is_lower_bound': {'type': 'boolean', 'description': '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.'}}, 'additionalProperties': False}