Search products (Lucene)
search_products_luceneSearch Open Food Facts using Lucene queries with boolean logic, negation, and filter-only browsing. Exclude allergens like gluten or refine by category and brand tags for precise results.
Instructions
Search Open Food Facts using the Search-a-licious Elasticsearch backend. Powered by Lucene query syntax with full boolean logic and negation support.
Use this instead of search_products_standard when you need:
Negation queries: find gluten-free cereals with allergens_tags_without="en:gluten"
Filter-only browsing: categories_tags without any text query (standard API times out on this)
Combined text + filter with relevance scoring: text matches are ranked by relevance within filter results
Boolean logic in raw Lucene: brands:"kellogg*" OR brands:"nestle"
Trade-offs vs search_products_standard:
Counts are approximate (capped at 10,000 for large result sets)
Brand tag matching may be narrower (less normalization than standard)
Data has a short sync delay (hours) from the primary database
popularity sort uses scan counts rather than the standard popularity algorithm
Response format matches search_products_standard: { count, page, page_size, page_count, products: [...] }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Free-text search terms. Combined with any filter params using AND logic. Omit to browse by filters alone (unlike search_products_standard, filter-only queries work here without timeouts). | |
| categories_tags | No | Filter by category tag (e.g. "en:breakfast-cereals"). Added as categories_tags:"value" in the Lucene query. | |
| brands_tags | No | Filter by brand tag (e.g. "nutella"). Added as brands_tags:"value" in the Lucene query. | |
| nutrition_grades_tags | No | Filter by Nutri-Score grade (a, b, c, d, e). Added as nutriscore_grade:"value". | |
| labels_tags | No | Filter by label tag (e.g. "en:organic", "en:fair-trade"). Added as labels_tags:"value". | |
| countries_tags | No | Filter by country tag (e.g. "en:united-kingdom", "en:france"). Added as countries_tags:"value". | |
| allergens_tags_without | No | EXCLUDE products containing this allergen (e.g. "en:gluten", "en:milk"). This is negation — a capability unique to this tool. Added as -allergens_tags:"value". Use for allergen-free searches. | |
| lucene_query | No | Raw Lucene query string for full control. If provided, all other filter params are ignored. Supports field:value, negation (-field:value), quoted phrases, wildcards. Examples: 'categories_tags:"en:beverages" nutriscore_grade:a -allergens_tags:"en:gluten"', 'brands:"kellogg*"' | |
| sort_by | No | Sort order. Note: uses different underlying fields than search_products_standard. | |
| sort_descending | No | Sort in descending order (default: true). Set false for ascending (e.g. lowest nutriscore_score first). | |
| page | No | Page number (default: 1) | |
| page_size | No | Results per page (default: 24, max: 100) | |
| fields | No | Fields to return per product. Defaults to: code, product_name, brands, categories, nutriscore_grade, nova_group, image_url, quantity |