find_products

com.basketwatchireland/basketwatch · Verify this server

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 ingredient lists are often cut short, so Aldi products are not offered as free from anything). 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. "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).