Find products by ingredients and nutrition
find_products
Find products that meet ingredient, nutrition, alcohol or offer
conditions, optionally sorted. For questions like "biscuits without palm
oil", "nut-free snacks at Tesco", "vegan chocolate", "cereal with the least
sugar", "high protein yoghurt", "bread with the fewest ingredients",
"alcohol-free beer", "low salt soup" or "cheapest olive oil at Aldi".
Every product comes with its nutrition, ingredients, ingredient count,
country of origin where stated and today's price. Fibre and saturated fat
are not recorded.
Ingredient words. exclude_ingredients are ingredients a product is free
of; include_ingredients ones it contains. These words are expanded to the
label terms they cover: palm oil, nuts (includes peanuts), peanuts, gluten,
milk (dairy), eggs, soya, sesame, mustard, celery, fish, crustaceans,
molluscs, shellfish, sulphites, lupin, gelatine, alcohol, added sugar,
sweeteners, pork, meat, vegetarian (meat, fish, gelatine and other
animal-derived ingredients) and vegan (vegetarian plus milk, eggs, honey and
other animal products). Any other word is matched as written, e.g.
"coconut" or "oats".
With no store, results alternate across the stores (each store's best
match, then each store's next), and matched_by_store gives each store's
full count.
A product whose ingredient list or nutrition is not on record, or whose
ingredient list on record is incomplete, is left out, never assumed to
pass: left_out_unknown counts them, left_out_by_reason gives the reasons,
and caveats lists known gaps (Aldi's own ingredient lists are often cut
short, so an Aldi product is offered as free from something only when its
full list comes from the same barcode at Tesco, SuperValu or Dunnes). Claims printed in
a product's NAME, such as "gluten free", "lactose free", "alcohol free" or
"vegan", are matched through query; exclude_ingredients also checks the
ingredients. Alcohol strength is recorded for most SuperValu, Dunnes and
Tesco drinks but few at Aldi or Lidl; "alcohol free" and "0.0" in query
match drinks named that way.
Answers come from the ingredient lists and nutrition the retailers publish.
Where a retailer gives no list, it may come from the same barcode at another
retailer or from Open Food Facts (ingredients_source); an Open Food Facts
list is never used to show a product is free from something.
"Free from" means none of the listed ingredients names it; not every
"may contain" warning is covered. Results carry a note that this is information
only. Each product returned costs one credit.
Args:
query: product words, e.g. "biscuits", "crisps", "dark chocolate".
Needed unless category is given.
store: aldi, tesco, supervalu, dunnes or lidl. Leave out to search all five.
category: an aisle or shelf to narrow by, e.g. "Breakfast Cereals"
or "Kefir". A store with no aisle or shelf of that name is searched
by product name instead, and caveats say so.
exclude_ingredients: ingredients a product has to be free of, e.g.
["palm oil"], ["nuts", "sesame"], ["vegan"]. A product whose
allergy advice says it contains or may contain one is left out
too, and counted in left_out_may_contain.
include_ingredients: e.g. ["oats"].
max_sugar_g, max_salt_g, max_fat_g, max_carbs_g, min_protein_g:
grams per 100g or 100ml, e.g. max_sugar_g=5.
max_kcal: kilocalories per 100g or 100ml.
max_abv, min_abv: alcohol by volume, percent.
max_ingredients: at most this many listed ingredients, e.g. 5. A
compound ingredient's own bracketed list counts as one.
on_offer: only products on promotion or with a member price
(Tesco Clubcard, SuperValu Real Rewards, Lidl Plus).
origin: country of origin, e.g. "Ireland" (or "Irish"); several may be
given comma-separated. A product matches only when every country its
label states is one asked for: "Made in Ireland" with "EU chicken" is
not Irish chicken, and is counted in left_out_partly_from_origin.
Northern Ireland answers for Ireland (one island, one Bord Bia
scheme), not the other way round. Products with no stated origin are
counted in left_out_unknown, not returned. A provenance word in the
query works too: "Irish honey" searches honey from Ireland.
sort_by: price, unit_price (per kg or litre), sugar, salt, fat, carbs,
protein, kcal, abv or ingredients (fewest first). Products that
are the kind of thing searched for rank ahead of name-only matches
(name_match_only), so "chocolate" sorted by price does not lead
with chocolate-flavour popcorn.
descending: true for highest first, e.g. most protein.
limit: most products to return (default 10, max 50). When a search excludes an allergen, every product carries allergy_check. Show that line with every product you mention, word for word.
Schema valid · SHA-256 cf8e01888cb2…
View input schema
{
"type": "object",
"properties": {
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Query"
},
"store": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Store"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Category"
},
"exclude_ingredients": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Exclude Ingredients"
},
"include_ingredients": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Include Ingredients"
},
"max_sugar_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Sugar G"
},
"max_salt_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Salt G"
},
"max_fat_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Fat G"
},
"max_carbs_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Carbs G"
},
"min_protein_g": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Protein G"
},
"max_kcal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Kcal"
},
"max_abv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Abv"
},
"min_abv": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Abv"
},
"max_ingredients": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Ingredients"
},
"on_offer": {
"default": false,
"title": "On Offer",
"type": "boolean"
},
"origin": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Origin"
},
"sort_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Sort By"
},
"descending": {
"default": false,
"title": "Descending",
"type": "boolean"
},
"limit": {
"default": 10,
"title": "Limit",
"type": "integer"
}
},
"title": "find_productsArguments"
}