Browse Food Facts Taxonomy
off_browse_taxonomyResolve a human term to the canonical Open Food Facts tag ID that off_search_products filters on. Covers categories, labels/certifications, allergens, additives, countries, ingredients, NOVA groups, and Nutri-Score grades. Pass a search term to resolve against the Open Food Facts vocabulary, which holds tens of thousands of tags; omitting it returns only a small reference list for each facet except NOVA groups and Nutri-Score grades, which are complete, and ingredients, which has no reference list and returns nothing. Most tag IDs use the "en:" prefix (e.g. "en:organic", "en:no-gluten", "en:crustaceans"); NOVA groups return bare digits "1"-"4" and Nutri-Score grades bare letters "a"-"e". Pass the id through to off_search_products exactly as returned. Category tags are frequently plural ("kombucha" resolves to "en:kombuchas") and ingredient tags singular ("oat" resolves to "en:oat", "oats" to nothing), so use the returned id rather than constructing one.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"facet": "<facet>"
},
"name": "off_browse_taxonomy"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| facet | Yes | "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). "ingredients" covers the ingredients Open Food Facts parses from ingredient lists (en:inulin, en:oat); it has no reference list, so pass a search term. "nova_groups" and "nutrition_grades" are closed vocabularies returned complete; the other six are resolved against the Open Food Facts taxonomy. | |
| limit | No | Maximum entries to return (default 20). One call returns at most 200: a larger value returns the first 200 and, when more matched, says how many did. 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 the term itself names (e.g. "lentil" → en:lentils, "US" → en:united-states) is listed first, so it is not the one a small limit cuts. | |
| search | No | 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); the tag the term itself names leads the list even when neither its ID nor its name contains the term as typed ("plant based milk alternatives" → en:plant-based-milk-alternatives). A single word works best ("hummus", not "hummus dip"). Omit only to see a small reference list (none for ingredients) — Open Food Facts cannot list the full vocabulary without a term, so an unfiltered call is not a view of the full facet. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The limit that was applied — at most 200. | |
| tags | No | Matching tag entries. | |
| error | No | Present when the call failed. Absent on success. | |
| facet | No | The facet name that was queried (echoes the input). | |
| shown | No | Number of tags returned. | |
| notice | No | Caveat about the answer — that the listing is a limited reference list rather than the full vocabulary, or that ingredients, which has none, needs a search term, that the live vocabulary went unchecked and why (unreachable or no usable answer, Open Food Facts rate-limiting this server, or this server's own taxonomy budget spent, with the wait in seconds when one is known), that nothing matched and why, or that the limit cut matches, naming how many matched and the next call: a larger limit while one would list more, otherwise a narrower term, which is the only route past the first 200 (a limit above 200 is named too). | |
| truncated | No | True when more tags exist beyond the limit. | |
| total_in_facet | No | 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. |