Search Products
Changed onSearch request allows you to get products that match your search criteria.
It allows you create many custom APIs for your use case.
If a search query parameter has multiple values, separate them with commas (,). When filtering with a language-specific parameter (fr, de, en, etc.), specify the language code in the parameter name (for example: categories_tags_en).
Important: search API v2 does not support full text request (search_term), you have to use search API v1 for that. Upcoming search-a-licious project will fix that.
Limiting results
You can limit the size of returned objects thanks to the fields object (see below).
Example: fields=code,product_name,brands,attribute_groups
Please use it as much as possible to avoid overloading the servers.
The search endpoint uses pagination: see page and page_size parameters.
Beware: page_count is the number of products returned in the current page, not the total number of pages.
Conditions on tags
All `_tags`` parameters accepts either:
- a single value
- or a comma-separated list of values (doing a AND)
- or a pipe separated list of values (doing a OR)
You can exclude terms by using a "-" prefix.
For taxonomized entries, you might either use the tag id (recommended), or a known synonym (without language prefix)
- labels_tags=en:organic,en:fair-trade find items that are fair-trade AND organic
- labels_tags=en:organic|en:fair-trade find items that are fair-trade OR organic
- labels_tags=en:organic,en:-fair-trade find items that are organic BUT NOT fair-trade
Conditions on nutriments
To get a list of nutrients:
You can either query on nutrient per 100g (_100g suffix) or per serving (serving suffix).
You can also add _prepared_ to get the nutrients in the prepared product instead of as sold.
You can add a comparison operator and value to the parameter name to get products with nutrient above or below a value. If you use a parameter value it exactly match it.
- energy-kj_100g<200 products where energy in kj for 100g is less than 200kj
- sugars_serving>10 products where sugar per serving is greater than 10g
- saturated-fat_100g=1 products where saturated fat per 100g is exactly 10g
- salt_prepared_serving<0.1 products where salt per serving for prepared product is less than 0.1g
Combining filters and pagination (examples)
-
Breakfast cereals with Nutri-Score A or B, with explicit pagination: /api/v2/search?categories_tags_en=breakfast-cereals&nutrition_grades_tags=a|b&page=2&page_size=20&fields=code,product_name,nutrition_grades
-
Multiple constraints in one query (category + nutrients + sorting + compact fields): /api/v2/search?categories_tags_en=orange-juices&sugars_100g%3C8&salt_100g%3C0.2&sort_by=last_modified_t&page=1&page_size=24&fields=code,product_name,nutriments
-
Include/exclude tags together: /api/v2/search?labels_tags=en:organic,en:-fair-trade&page=1&page_size=24&fields=code,product_name,labels_tags
Response structure at a glance
A successful response contains:
- count: total number of matching products
- page: current page number
- page_size: requested number of products per page
- page_count: number of products actually returned in this page
- skip: number of products skipped before this page
- products: array of products for the current page
Total page count can be computed with: Math.floor((count - 1) / page_size) + 1
More references
See also wiki page
Request
- Base URLhttps://world.openfoodfacts.net
- AuthAPI key in header User-Agent
Query parameters
The additives_tags in english of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for additives. Translated values are available at https://static.openfoodfacts.org/data/taxonomies/additives.json
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The allergens_tags in english of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for allergens. Translated values are available at https://static.openfoodfacts.org/data/taxonomies/allergens.json
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The brands_tags of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for brands. Taxonomized values are available at https://static.openfoodfacts.org/data/taxonomies/brands.json
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The category of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for categories. Translated values are available at https://static.openfoodfacts.org/data/taxonomies/categories.json
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The countries_tags_en of product(s) you are searching for. The Open Food Facts Web App shows a list of possible values for countries. Translated values are available at https://static.openfoodfacts.org/data/taxonomies/countries.json
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The emb_codes_tags of product(s) you are searching for.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The labels_tags in english of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for labels.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The manufacturing_places_tags of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for manufacturing-places.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The nutrition_grades_tags of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for nutrition-grades.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The origins_tags of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for origins.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The packaging_tag in german of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for packaging.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The purchase_places_tags of product(s) you are searching for.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The states_tags in english of product(s) you are searching for. The Open Food Facts Web App has a list of possible values for states. Translated values are available at https://static.openfoodfacts.org/data/taxonomies/states.json You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The stores_tags of product(s) you are searching for.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
The traces_tags of product(s) you are searching for. The Open Food Facts Web App shows a list of possible values for traces.
You can use multiple values by using a comma separated list. You can add a "-" before values to avoid matching a tag.
You can add a language code to a specific tag to query it in a specific language
{
"packaging_tags_de": null,
"summary": "packaging in German",
"value": {
"packaging_tags_de": "de:Flasche"
}
}Search on nutrient lower than a value
{
"salt_100g_lt_2": null,
"summary": "salt per 100g is lower than 2g (in product as sold)",
"value": {
"salt_100g<2": 1
}
}Search on nutrient greater than a value
{
"carbohydrates_prepared_serving_gt_10": null,
"summary": "carbohydrates per serving is greater than 10g in prepared product",
"value": {
"salt_100g>10": 1
}
}Search on nutrient for an exact quantity
{
"fat_100g_eq_5": null,
"summary": "fat per 100g is exactly equal to 5g (in product as sold)",
"value": {
"fat_100g": 5
}
}Custom comma-separated list of product field names
Specific fields to return. Use 'knowledge_panels' for Knowledge Panels only.
The allowed values used to sort/order the search results.
- product_name sorts on name
- ecoscore_score, nova_score, nutriscore_score rank on the Eco-Score, Nova, or Nutri-Score
- scans_n, unique_scans_n and popularity_key are about product popularity: number of scans on unique scans, rank of product
- created_t, last_modified_t, are about creation and modification dates
- nothing, tells not to sort at all (because if you do not provide the sort_by argument we default to sorting on popularity (for food) or last modification date)
The page number you request to view (eg. in search results spanning multiple pages)
The number of elements should be sent per page
Response
OK
Example response
{
"count": 2701,
"page": 1,
"page_count": 24,
"page_size": 24,
"products": [
{
"codes_tags": [
"code-13"
],
"product_quantity": "500",
"product_quantity_unit": "g",
"quantity": "3 x 150 g",
"schema_version": 999,
"packaging_text": "packaging_text_en",
"packagings": [
{
"number_of_units": 6,
"shape": {
"id": "en:bottle",
"lc_name": "bouteille"
},
"material": {
"id": "en:bottle",
"lc_name": "bouteille"
},
"recycling": {
"id": "en:bottle",
"lc_name": "bouteille"
},
"quantity_per_unit": "25 cl",
"quantity_per_unit_value": 25,
"quantity_per_unit_unit": "cl",
"weight_specified": 30,
"weight_measured": 32,
"weight_estimated": 26,
"weight": 30,
"weight_source_id": "specified"
}
],
"popularity_tags": [
"bottom-25-percent-scans-2020",
"top-85-percent-scans-2021",
"top-90-percent-scans-2022",
"top-country-it-scans-2019",
"top-100000-mg-scans-2024"
],
"serving_quantity_unit": "g",
"emb_codes": "EMB 2013330",
"entry_dates_tags": [
"2016-03-11",
"2016-03",
"2016"
],
"images": {
"front": {
"coordinates_image_size": "full",
"geometry": "0x0--1--1",
"imgid": "121",
"rev": "420",
"sizes": {
"100": {
"h": 400,
"w": 255
},
"200": {
"h": 400,
"w": 255
},
"400": {
"h": 400,
"w": 255
},
"full": {
"h": 400,
"w": 255
}
},
"x1": "-1",
"x2": "-1",
"y1": "-1",
"y2": "-1"
}
},
"ecoscore_data": {
"adjustments": {
"packaging": {
"packagings": [
{
"number_of_units": 1,
"quantity_per_unit": "33 cL",
"quantity_per_unit_unit": "cl",
"quantity_per_unit_value": 33,
"recycling": "en:recycle-in-sorting-bin",
"weight_measured": 12.08
}
]
}
}
},
"ingredients_text": "Farine de blé* 67,4%, sucre de canne*, huile de tournesol oléique*, graines de chia* 5,2%, son de blé*, oranges déshydratées * 0,9%, farine de riz*, poudres à lever (acide citrique, carbonates de sodium), arôme naturel d'orange.\n",
"ingredients_text_with_allergens": "Farine de <span class=\"allergen\">blé*</span> 67,4%, sucre de canne*, huile de tournesol oléique*, graines de chia* 5,2%, <span class=\"allergen\">son de blé*</span>, oranges déshydratées * 0,9%, farine de riz*, poudres à lever (acide citrique, carbonates de sodium), arôme naturel d'orange.\n",
"no_nutrition_data": "on",
"nutriments": {
"erythritol": 12.5
},
"nutriscore_data": {
"energy": 1996,
"energy_points": 5,
"energy_value": 1996,
"fiber": 3.8,
"fiber_points": 4,
"fiber_value": 3.8,
"proteins": 6.6,
"proteins_points": 4,
"proteins_value": 6.6,
"saturated_fat": 6.2,
"saturated_fat_points": 6,
"saturated_fat_value": 6.2,
"sodium": 210,
"sodium_points": 2,
"sodium_value": 210,
"sugars": 21.5,
"sugars_points": 4,
"sugars_value": 21.5,
"negative_points": 17,
"positive_points": 4,
"grade": "d",
"score": 13
},
"nutriscore": {
"2021": {
"category_available": 1,
"grade": "d",
"nutrients_available": 1,
"nutriscore_applicable": 1,
"nutriscore_computed": 1,
"score": 13,
"data": {
"energy": 1996,
"energy_points": 5,
"energy_value": 1996,
"fiber": 3.8,
"fiber_points": 4,
"fiber_value": 3.8,
"proteins": 6.6,
"proteins_points": 4,
"proteins_value": 6.6,
"saturated_fat": 6.2,
"saturated_fat_points": 6,
"saturated_fat_value": 6.2,
"sodium": 210,
"sodium_points": 2,
"sodium_value": 210,
"sugars": 21.5,
"sugars_points": 4,
"sugars_value": 21.5,
"negative_points": 17,
"positive_points": 4,
"grade": "d",
"score": 13
}
},
"2023": {
"category_available": 1,
"grade": "d",
"nutrients_available": 1,
"nutriscore_applicable": 1,
"nutriscore_computed": 1,
"score": 13,
"data": {
"components": {
"negative": [
{
"id": "energy",
"points": 5,
"points_max": 10,
"unit": "kJ",
"value": 21.5
}
],
"positive": [
{
"id": "energy",
"points": 5,
"points_max": 10,
"unit": "kJ",
"value": 21.5
}
]
},
"count_proteins_reason": "negative_points_greater_than_or_equal_to_11",
"negative_points": 19,
"positive_points": 1,
"negative_points_max": 55,
"positive_points_max": 10,
"positive_nutrients": [
"fiber",
"fruits_vegetables_legumes"
]
}
}
},
"nutriscore_2021_tags": [
"d"
],
"nutriscore_2023_tags": [
"d"
],
"nutriscore_grade": "d",
"nutriscore_score": 13,
"nutriscore_score_opposite": -13,
"nutriscore_tags": [
"d"
],
"purchase_places": "Paris",
"stores": "Walmart",
"created_t": 1457680652,
"last_modified_by": "sebleouf",
"knowledge_panels": {
"additionalProperties": "string"
},
"attribute_groups": [
{
"title": "Does not contain: Molluscs"
}
]
}
]
}Changes
- breaking
the response's body type changed from no type to
objectfor status - info
added the new optional
queryrequest parameter<nutrient>_eq_<value> - info
added the new optional
queryrequest parameter<nutrient>_gt_<value>
24 more changes in this revision
- breaking