Search

Search 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)

  1. 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

  2. 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

  3. 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

get/api/v2/search

Request

  • Base URL
    https://world.openfoodfacts.net
  • Auth
    API key in header User-Agent

Query parameters

additives_tagsstring
Example:e322

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.

allergens_tagsstring
Example:m

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.

brands_tagsstring
Example:ferrero

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.

categories_tagsstring
Example:chocolates

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.

countries_tags_enstring
Example:united-kingdom

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.

emb_codes_tagsstring

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.

labels_tagsstring
Example:organic

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.

manufacturing_places_tagsstring

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.

nutrition_grades_tagsstring
Example:e

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.

origins_tagsstring

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.

packaging_tags_destring
Example:1-jar-aus-klarglas

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.

purchase_places_tagsstring

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.

states_tagsstring
Example:nutrition-facts-completed

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.

stores_tagsstring
Example:aldi

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.

traces_tagsstring

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.

<tag_name>_tags_<language_code>object

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"
  }
}
<nutrient>_lt_<value>object

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
  }
}
<nutrient>_gt_<value>object

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
  }
}
<nutrient>_eq_<value>object

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
  }
}
fieldsstring

Custom comma-separated list of product field names

Example:knowledge_panels

Specific fields to return. Use 'knowledge_panels' for Knowledge Panels only.

sort_by'product_name' | 'last_modified_t' | 'scans_n' | 'unique_scans_n' | 'created_t' | 'completeness' | 'popularity_key' | 'nutriscore_score' | 'nova_score' | 'nothing' | 'ecoscore_score'
Example:product_name

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)
pageinteger
Example:24

The page number you request to view (eg. in search results spanning multiple pages)

page_sizeinteger
Example:24

The number of elements should be sent per page

Response

OK

countinteger

Total number of products found

pageinteger

Page number of returned results.

You can get a different page, by using the page query parameter.

page_countinteger

Number of products returned in the current page.

This will differ from page_size only on the last page.

page_sizeinteger

Requested number of products per page.

To get the number of pages, compute: Math.floor((count - 1) / page_size) + 1

skipinteger

Number of matching products skipped before the current page.

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 object for status

    • info

      added the new optional query request parameter <nutrient>_eq_<value>

    • info

      added the new optional query request parameter <nutrient>_gt_<value>

    24 more changes in this revision