API docs by Redocly

Open Food Facts Open API V3 - under development (3)

Download OpenAPI specification:

Open Food Facts: reuse@openfoodfacts.org URL: https://slack.openfoodfacts.org/ License: License (MIT, Apache 2.0, etc) Terms of Service

As a developer, the Open Food Facts API allows you to get information and contribute to the products database. You can create great apps to help people make better food choices and also provide data to enhance the database.

IMPORTANT: Please read the API introduction before using this API.

WARNING v3 is under development and you should expect changes

The current version of API v3 is v3.2 See the change log for the API and product schema

Read Requests

READ Product - Get information for a specific product by barcode (API V3)

Retrieve information for a product with a specific barcode.

The fields parameter allows to specify what fields to retrieve.

path Parameters
barcode
required
string
Example: 3017620422003

The barcode of the product to be fetched

query Parameters
product_type
string
Enum: "all" "beauty" "food" "petfood" "product"
Examples: product_type=all product_type=food

Used for READ queries for one product. Expected product type of the requested product. Defaults to the product type of the server the query is sent to (e.g. 'food' for Open Food Facts, 'beauty' for Open Beauty Facts, etc.). 'all' matches all product types. If the product exists on a different server that matches the requested product type, the API will return a 302 redirect to the correct server. Otherwise, the API will return a 404 error. It is possible that new product types will be added in the future.

cc
string
Example: cc=us

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.

lc
string
Example: lc=fr

2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request.

tags_lc
string

2 letter language code to request names of tags in a specific language. For READ requests: if passed, all taxonomized tags of the response will include a lc_name property with the translation in the requested language, if available. Otherwise, the property value will contain the name in the original language, prefixed by the 2 language code and a colon.

fields
string

Comma separated list of fields requested in the response.

Special values:

  • "none": returns no fields
  • "raw": returns all fields as stored internally in the database
  • "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels".

Defaults to "all" for READ requests. The "all" value can also be combined with fields like "attribute_groups" and "knowledge_panels".'

knowledge_panels_included
string
Example: knowledge_panels_included=health_card, environment_card

When knowledge_panels are requested, you can specify which panels should be in the response. All the others will be excluded.

knowledge_panels_excluded
string
Example: knowledge_panels_excluded=health_card, environment_card

When knowledge_panels are requested, you can specify which panels to exclude from the response. All the others will be included. If a panel is both excluded and included (with the knowledge_panels_excluded parameter), it will be excluded.

Responses

Response samples

Content type
application/json
{
  • "status_id": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ],
  • "abbreviated_product_name": "string",
  • "code": "string",
  • "codes_tags": [
    ],
  • "generic_name": "string",
  • "id": "string",
  • "lc": "string",
  • "lang": "string",
  • "nova_group": 0,
  • "nova_groups": "string",
  • "obsolete": "string",
  • "obsolete_since_date": "string",
  • "product_name": "string",
  • "product_name_en": "string",
  • "product_quantity": "500",
  • "product_quantity_unit": "g",
  • "quantity": "3 x 150 g",
  • "schema_version": 999,
  • "additives_n": 0,
  • "checked": "string",
  • "complete": 0,
  • "completeness": 0,
  • "ecoscore_grade": "string",
  • "ecoscore_score": 0,
  • "food_groups": "string",
  • "food_groups_tags": [
    ],
  • "nutrient_levels": {
    },
  • "packaging_text": "packaging_text_en",
  • "packagings": [
    ],
  • "packagings_complete": 1,
  • "pnns_groups_1": "string",
  • "pnns_groups_1_tags": [
    ],
  • "pnns_groups_2": "string",
  • "pnns_groups_2_tags": [
    ],
  • "popularity_key": 0,
  • "popularity_tags": [
    ],
  • "scans_n": 0,
  • "unique_scans_n": 0,
  • "serving_quantity": "string",
  • "serving_quantity_unit": "g",
  • "serving_size": "string",
  • "brands": "string",
  • "brands_hierarchy": [
    ],
  • "brands_lc": "string",
  • "brands_tags": [
    ],
  • "categories": "string",
  • "categories_hierarchy": [
    ],
  • "categories_lc": "string",
  • "categories_tags": [
    ],
  • "checkers_tags": [
    ],
  • "cities": "string",
  • "cities_tags": [
    ],
  • "correctors_tags": [
    ],
  • "countries": "string",
  • "countries_hierarchy": [
    ],
  • "countries_lc": "string",
  • "countries_tags": [
    ],
  • "ecoscore_tags": [
    ],
  • "emb_codes": "EMB 2013330",
  • "emb_codes_orig": "string",
  • "emb_codes_tags": [
    ],
  • "labels": "string",
  • "labels_hierarchy": [
    ],
  • "labels_lc": "string",
  • "labels_tags": [
    ],
  • "entry_dates_tags": [
    ],
  • "manufacturing_places": "string",
  • "manufacturing_places_tags": [
    ],
  • "nova_groups_tags": [
    ],
  • "nutrient_levels_tags": [
    ],
  • "images": {
    },
  • "selected_images": { },
  • "last_image_dates_tags": [
    ],
  • "last_image_t": 0,
  • "ecoscore_data": {
    },
  • "ecoscore_extended_data_version": "string",
  • "environment_impact_level": "string",
  • "environment_impact_level_tags": [
    ],
  • "additives_tags": [
    ],
  • "allergens": "string",
  • "allergens_lc": "string",
  • "allergens_hierarchy": [
    ],
  • "allergens_tags": [
    ],
  • "ingredients": [
    ],
  • "ingredients_analysis": {
    },
  • "ingredients_analysis_tags": [
    ],
  • "ingredients_from_or_that_may_be_from_palm_oil_n": 0,
  • "ingredients_from_palm_oil_n": 0,
  • "ingredients_from_palm_oil_tags": [
    ],
  • "ingredients_hierarchy": [
    ],
  • "ingredients_n": 0,
  • "ingredients_n_tags": [
    ],
  • "ingredients_original_tags": [
    ],
  • "ingredients_percent_analysis": 0,
  • "ingredients_sweeteners_n": 0,
  • "ingredients_non_nutritive_sweeteners_n": 0,
  • "ingredients_tags": [
    ],
  • "ingredients_lc": "string",
  • "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",
  • "ingredients_that_may_be_from_palm_oil_n": 0,
  • "ingredients_that_may_be_from_palm_oil_tags": [
    ],
  • "ingredients_with_specified_percent_n": 0,
  • "ingredients_with_specified_percent_sum": 0,
  • "ingredients_with_unspecified_percent_n": 0,
  • "ingredients_with_unspecified_percent_sum": 0,
  • "known_ingredients_n": 0,
  • "origins": "string",
  • "origins_hierarchy": [
    ],
  • "origins_lc": "string",
  • "origins_tags": [
    ],
  • "traces": "string",
  • "traces_hierarchy": [
    ],
  • "traces_lc": "string",
  • "traces_tags": [
    ],
  • "unknown_ingredients_n": 0,
  • "no_nutrition_data": "on",
  • "nutrition_data_per": "serving",
  • "nutrition_data_prepared_per": "serving",
  • "nutriments": {
    },
  • "nutriscore_data": {
    },
  • "nutrition_grade_fr": "string",
  • "nutrition_grades": "string",
  • "nutrition_grades_tags": [
    ],
  • "nutrition_score_beverage": 0,
  • "nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients": 0,
  • "nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients_value": 0,
  • "nutrition_score_warning_no_fiber": 0,
  • "other_nutritional_substances_tags": [
    ],
  • "unknown_nutrients_tags": [
    ],
  • "vitamins_tags": [
    ],
  • "nutriscore": {
    },
  • "nutriscore_2021_tags": [
    ],
  • "nutriscore_2023_tags": [
    ],
  • "nutriscore_grade": "a",
  • "nutriscore_score": 13,
  • "nutriscore_score_opposite": -13,
  • "nutriscore_tags": [
    ],
  • "nutriscore_version": "string",
  • "data_quality_bugs_tags": [
    ],
  • "data_quality_errors_tags": [
    ],
  • "data_quality_info_tags": [
    ],
  • "data_quality_tags": [
    ],
  • "data_quality_warnings_tags": [
    ],
  • "data_sources": "string",
  • "data_sources_tags": [
    ],
  • "last_check_dates_tags": [
    ],
  • "last_checked_t": 0,
  • "last_checker": "string",
  • "states": "string",
  • "states_hierarchy": [
    ],
  • "states_tags": [
    ],
  • "misc_tags": [
    ],
  • "additives_original_tags": [
    ],
  • "additives_prev_original_tags": [
    ],
  • "added_countries_tags": [
    ],
  • "allergens_from_ingredients": "string",
  • "allergens_from_user": "string",
  • "amino_acids_prev_tags": [
    ],
  • "amino_acids_tags": [
    ],
  • "carbon_footprint_percent_of_known_ingredients": 0,
  • "categories_properties": {
    },
  • "categories_properties_tags": [
    ],
  • "category_properties": {
    },
  • "ciqual_food_name_tags": [
    ],
  • "compared_to_category": "string",
  • "conservation_conditions": "string",
  • "customer_service": "string",
  • "expiration_date": "string",
  • "link": "string",
  • "main_countries_tags": [
    ],
  • "minerals_prev_tags": [
    ],
  • "minerals_tags": [
    ],
  • "owner_fields": {
    },
  • "nova_groups_markers": {
    },
  • "nucleotides_tags": [
    ],
  • "origin": "string",
  • "purchase_places": "Paris",
  • "purchase_places_tags": [
    ],
  • "stores": "Walmart",
  • "stores_tags": [
    ],
  • "traces_from_ingredients": "string",
  • "traces_from_user": "string",
  • "created_t": 1457680652,
  • "creator": "string",
  • "editors_tags": [
    ],
  • "informers_tags": [
    ],
  • "interface_version_created": "string",
  • "interface_version_modified": "string",
  • "languages": { },
  • "languages_codes": { },
  • "languages_hierarchy": [
    ],
  • "languages_tags": [
    ],
  • "last_edit_dates_tags": [
    ],
  • "last_editor": "string",
  • "last_modified_by": "sebleouf",
  • "last_modified_t": 0,
  • "last_updated_t": 0,
  • "owner": "string",
  • "owners_tags": "string",
  • "photographers_tags": [
    ],
  • "rev": 0,
  • "sources": [
    ],
  • "sources_fields": {
    },
  • "teams": "string",
  • "teams_tags": [
    ],
  • "update_key": "string",
  • "knowledge_panels": {
    },
  • "attribute_groups": [
    ]
}

Get taxonomy entries suggestions

Open Food Facts uses multilingual taxonomies to normalize entries for categories, labels, ingredients, packaging shapes / materials / recycling instructions and many more fields.

This API returns taxonomy entries suggestions that can be used in product edit forms, search forms etc. (for instance in autocomplete dropdowns using libraries like Tagify or select2 on the Web).

Suggestions filtering:

The string parameter allows to get only suggestions that contain a specific string (useful for autocomplete suggestions).

Suggestions ordering:

  • For packaging shapes and materials, suggestions are ordered first by the number of packaging components they appear in (restricted by country, categories and shape (for materials) if they are passed as parameters).
  • for all other taxonomies, results are ordered alphabetically

If a string is passed, an additional sort is done to put first suggestions that start with the string, followed by suggestions with a word that start with the string, and then suggestions that contain the string anywhere.

query Parameters
tagtype
string
Example: tagtype=additives
cc
string
Example: cc=us

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.

lc
string
Example: lc=fr

2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request.

string
string
Example: string=pe

Optional string used to filter suggestions (useful for autocomplete). If passed, suggestions starting with the string will be returned first, followed by suggestions matching the string at the beginning of a word, and suggestions matching the string inside a word.

categories
string
Example: categories=yougurts

Comma separated list of categories tags (e.g. "en:fats,en:unsalted-butters" or categories names in the language indicated by the "lc" field (e.g. "graisses, beurres salés" in French)

shape
string
Example: shape=bottle

Shape of packaging component (tag identified in the packaging_shapes taxonomy, or plain text tag name in the language indicated by the "lc" field)

limit
string

Maximum number of suggestions. Default is 25, max is 400.

get_synonyms
string

Whether or not to include "matched_synonyms" in the response. Set to 1 to include.

term
string

Alias for the "string" parameter provided for backward compatibility. "string" takes precedence.

Responses

Response samples

Content type
application/json
{
  • "status_id": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ],
  • "suggestions": [
    ],
  • "matched_synonyms": {
    }
}

Get knowledge panels for a tag

Return knowledge panels for a tag.

Currently the knowledge panels returned are:

Categories:

  • Packaging stats for a category
path Parameters
tagtype
required
string
Example: categories

Type of the tag

tag_or_tagid
required
string

Tag name (e.g. yogurts) or tag id (e.g. en:yogurts)

query Parameters
cc
string
Example: cc=us

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.

lc
string
Example: lc=fr

2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request.

Responses

Response samples

Content type
{
  • "status_id": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ],
  • "tagtype": "string",
  • "tagid": "string",
  • "tag": {
    }
}

Write Requests

WRITE Product - Create or update product, select images, or analyze test product (API V3 - Implementation in progress)

This API allows to create or update a product (if the product already exists, its data is updated, otherwise it is created), or to analyze a test product (in which case no product is created or updated). To analyze a product, the "barcode" path component needs to contain the value "test" instead of a barcode.

New API to send structured product data in a JSON format instead of in a flattened list of key / value pairs field as-in the current product add / edit API that relies on a multipart/form-data format.

Important: this new Product WRITE API has been deployed in production, but it is still under development, and it may change.

This new API is used in particular to send structured packaging data: https://openfoodfacts.github.io/openfoodfacts-server/dev/explain-packaging-data/

The new API is gradually being extended to support other product fields.

Currently supported fields are:

  • language specific fields (e.g. product name, ingredients text)
  • tags fields (e.g. categories, labels)
  • packaging fields (e.g. packagings, packagings_add, packagings_complete)
  • image selection of uploaded images (e.g. front, ingredients, nutrition, packaging) for specific languages
path Parameters
barcode
required
string
Example: 3017620422003

The barcode of the product to to create or update, or "test" to analyze the product data sent without creating or updating a product.

Request Body schema:

Structured data for the product is passed in the product field.

For complex structures such as the packagings object, it is possible to replace pre-existing data, or completing it:

  • an object sent in the packagings field will replace any pre-existing data.
  • an object sent in the field suffixed with _add (e.g. packagings_add) will be merged with any pre-existing data.
lc
string

2 letter code of the language of the interface. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the country of the user (passed through the cc field or inferred by the IP address). Full list at https://static.openfoodfacts.org/data/taxonomies/languages.json

cc
string

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request. Full list at https://static.openfoodfacts.org/data/taxonomies/countries.json

fields
string

Comma separated list of fields requested in the response. Special values: "updated": returns field that were updated by the query (e.g. sending "packagings" or "packagings_add" would return "packagings"), "none": returns no fields, "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels". Defaults to "updated" for WRITE requests, and "all" for READ requests.

tags_lc
string

2 letter language code to request names of tags in a specific language.

For READ requets: if passed, all taxonomized tags of the response will include a lc_name property with the translation in the requested language, if available. Otherwise, the property value will contain the name in the original language, prefixed by the 2 language code and a colon.

For WRITE requests: if passed, taxonomized tags fields with a lc_name property will be considered to be in this language.

user_id
string
password
string <password>

Password for login

object (product_update_api_v3)

Model for creating or updating products using the v3 version of the product update API.

Responses

Request samples

Content type
{
  • "lc": "fr",
  • "cc": "fr",
  • "fields": "product_name,packagings",
  • "tags_lc": "fr",
  • "userid": "string",
  • "password": "string",
  • "code": "string",
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "status": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ],
  • "product": {
    }
}

UPLOAD Product Image - Upload (and possibly select) an image for a product

This endpoint allows to upload an image for a product. The image is uploaded in the request body as a base64 encoded string. Optionally, it is possible to select the uploaded image for specific information (e.g. front, ingredients, nutrition, packaging) for specific languages. Each selected image is a cropped version of the uploaded image.

If the product does not exist, it will be created.

path Parameters
barcode
required
string
Example: 3017620422003

The barcode of the product corresponding to the image.

Request Body schema:

Image data for the product is passed in the image_data_base64 field as a base64 encoded string.

lc
string

2 letter code of the language of the interface. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the country of the user (passed through the cc field or inferred by the IP address). Full list at https://static.openfoodfacts.org/data/taxonomies/languages.json

cc
string

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request. Full list at https://static.openfoodfacts.org/data/taxonomies/countries.json

user_id
string

Username for login

Note: you must always use the username (and not the email) as it is far less brittle.

password
string <password>

Password for login

image_data_base64
string

Base64 encoded image data (supported formats: JPEG, PNG, GIF, HEIC)

object (ImagesSelected)

Optional instructions to select (and possibly crop) the uploaded image for specific information (e.g. front, ingredients, nutrition, packaging) for specific languages.

Responses

Request samples

Content type
{
  • "lc": "fr",
  • "cc": "fr",
  • "user_id": "string",
  • "password": "pa$$word",
  • "image_data_base64": "string",
  • "selected": {
    }
}

Response samples

Content type
application/json
{
  • "status_id": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ],
  • "product": {
    }
}

DELETE Product Image - Delete an uploaded image for a product, and selected images that are cropped from it

This endpoint allows to delete an uploaded image for a product. Selected images that are cropped from it will also be deleted.

Image deletion is allowed only for moderators and admins, so the request must be authenticated with a session cookie or userid and password.

path Parameters
barcode
required
string
Example: 3017620422003

The barcode of the product corresponding to the image.

imgid
required
integer
Example: 2

The id of the image to be deleted.

Responses

Response samples

Content type
application/json
{
  • "status_id": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ]
}

Revert a product to a previous revision

For moderators only, revert a product to a previous revision.

Request Body schema: application/json

The code and rev fields are mandatory.

fields
string

Comma separated list of fields requested in the response. Special values: "updated": returns field that were updated by the query (e.g. sending "packagings" or "packagings_add" would return "packagings"), "none": returns no fields, "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels". Defaults to "updated" for WRITE requests, and "all" for READ requests.

tags_lc
string

2 letter language code to request names of tags in a specific language.

For READ requets: if passed, all taxonomized tags of the response will include a lc_name property with the translation in the requested language, if available. Otherwise, the property value will contain the name in the original language, prefixed by the 2 language code and a colon.

For WRITE requests: if passed, taxonomized tags fields with a lc_name property will be considered to be in this language.

code
string

Barcode of the product

rev
integer

Revision number to revert to

Responses

Request samples

Content type
application/json
{
  • "fields": "product_name,packagings",
  • "tags_lc": "fr",
  • "code": "string",
  • "rev": 0
}

Response samples

Content type
application/json
{
  • "status_id": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ]
}

Schemas

Warning or error message

object
object

Field that triggered the warning or error.

object
{
  • "message": {
    },
  • "field": {
    },
  • "impact": {
    }
}

Response status

status_id
string
Enum: "success" "success_with_warnings" "success_with_errors" "failure"

Overall status of the request: whether it failed or succeeded, with or without warnings or errors.

object

Overall result of the request (e.g. a product has been created)

Array of objects (Warning or error message)

List of warnings. Warnings are used to alert about something that may be wrong, but is not necessarily wrong (e.g. a nutrient value that is unexpectedly high).

Array of objects (Warning or error message)

List of errors. Errors are used to alert about something that is definitely wrong (e.g. a nutrient value that is impossibly high).

{
  • "status_id": "success_with_errors",
  • "result": {
    },
  • "errors": [
    ]
}

product_base

abbreviated_product_name
string

Abbreviated name in requested language

code
string

barcode of the product (can be EAN-13 or internal codes for some food stores), for products without a barcode, Open Food Facts assigns a number starting with the 200 reserved prefix

codes_tags
Array of strings
generic_name
string

Legal name of the product as regulated by the European authorities.

id
string

internal identifier for the product, usually set to the value of code, except on the producers platform where it is prefixed by the owner

lc
string

Main language of the product. This is a duplicate of lang property (for historical reasons).

lang
string

Main language of the product.

This should be the main language of product packaging (if one is predominant).

Main language is also used to decide which ingredients list to parse.

nova_group
integer

Nova group as an integer from 1 to 4. See https://world.openfoodfacts.org/nova

nova_groups
string
obsolete
string
obsolete_since_date
string

A date at which the product was declared obsolete. This means it's not produced any more.

product_name
string

The name of the product

product_name_en
string

The name of the product can also be in many other languages like product_name_fr (for French).

product_quantity
string

The size in g or ml for the whole product. It is a normalized version of the quantity field. A quantity of "2 x 60 g" leads to product_quantity: "120".

product_quantity_unit
string

The unit (either g or ml) for the corresponding product_quantity. It is computed from the quantity field. A quantity of "6 x 250 ml" leads to product_quantity_unit: "ml".

quantity
string

The quantity of the product, with the corresponding number of portions or unit (g, ml, kg, l, cl, oz, lbs...). It should be the value as displayed on the product. The ℮ sign is allowed. When it refers to the number of portions, it can be filled without any units (e.g. "6 eggs").

schema_version
integer

Version of the product object schema used in the response. This indicates the structure of the 'product' field itself. For more details, please read: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-api-and-product-schema-change-log

abbreviated_product_name_(?<language_code>\w\w)
pattern property
string

Abbreviated name in language language_code.

generic_name_(?<language_code>\w\w)
pattern property
string

This can be returned in many other languages like generic_name_fr (for French).

{
  • "abbreviated_product_name": "string",
  • "code": "string",
  • "codes_tags": [
    ],
  • "generic_name": "string",
  • "id": "string",
  • "lc": "string",
  • "lang": "string",
  • "nova_group": 0,
  • "nova_groups": "string",
  • "obsolete": "string",
  • "obsolete_since_date": "string",
  • "product_name": "string",
  • "product_name_en": "string",
  • "product_quantity": "500",
  • "product_quantity_unit": "g",
  • "quantity": "3 x 150 g",
  • "schema_version": 999
}

Packaging component shape

id
string

Canonical id of the entry in the taxonomy. If the value cannot be mapped to a taxonomy entry, the value will be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

lc_name
string

Name of the entry in the language requested in the tags_lc field of the request. This field is returned only of tags_lc is specified. If the translation is not available, or if the entry does not exist in the taxonomy, the value will be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

{
  • "id": "en:bottle",
  • "lc_name": "bouteille"
}

Packaging component material

id
string

Canonical id of the entry in the taxonomy. If the value cannot be mapped to a taxonomy entry, the value will be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

lc_name
string

Name of the entry in the language requested in the tags_lc field of the request. This field is returned only of tags_lc is specified. If the translation is not available, or if the entry does not exist in the taxonomy, the value will be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

{
  • "id": "en:bottle",
  • "lc_name": "bouteille"
}

Packaging component recycling instruction

id
string

Canonical id of the entry in the taxonomy. If the value cannot be mapped to a taxonomy entry, the value will be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

lc_name
string

Name of the entry in the language requested in the tags_lc field of the request. This field is returned only of tags_lc is specified. If the translation is not available, or if the entry does not exist in the taxonomy, the value will be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

{
  • "id": "en:bottle",
  • "lc_name": "bouteille"
}

Packaging component (READ)

number_of_units
integer

umber of units of this packaging component contained in the product (e.g. 6 for a pack of 6 bottles)

object (shape)

The shape property is canonicalized using the packaging_shapes taxonomy.

object (material)

The material property is canonicalized using the packaging_materials taxonomy.

object (recycling)

The recycling property is canonicalized using the packaging_recycling taxonomy.

quantity_per_unit
string

Quantity (weight or volume) of food product contained in the packaging component. (e.g. 75cl for a wine bottle)

quantity_per_unit_value
number

Value parsed from the quantity field.

quantity_per_unit_unit
string

Unit parsed and normalized from the quantity field.

weight_specified
number

Weight (as specified by the manufacturer) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component).

weight_measured
number

Weight (as measured by one or more users) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component).

weight_estimated
number

Weight (as estimated from similar products) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component).

weight
number

Weight of one unit of the empty packaging component.

weight_source_id
string

Indicates which field was used to populate the "weight" field. Either "specified", "measured", or "estimated"

{
  • "number_of_units": 6,
  • "shape": {
    },
  • "material": {
    },
  • "recycling": {
    },
  • "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"
}

Packagings (READ)

Array
number_of_units
integer

umber of units of this packaging component contained in the product (e.g. 6 for a pack of 6 bottles)

object (shape)

The shape property is canonicalized using the packaging_shapes taxonomy.

object (material)

The material property is canonicalized using the packaging_materials taxonomy.

object (recycling)

The recycling property is canonicalized using the packaging_recycling taxonomy.

quantity_per_unit
string

Quantity (weight or volume) of food product contained in the packaging component. (e.g. 75cl for a wine bottle)

quantity_per_unit_value
number

Value parsed from the quantity field.

quantity_per_unit_unit
string

Unit parsed and normalized from the quantity field.

weight_specified
number

Weight (as specified by the manufacturer) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component).

weight_measured
number

Weight (as measured by one or more users) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component).

weight_estimated
number

Weight (as estimated from similar products) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component).

weight
number

Weight of one unit of the empty packaging component.

weight_source_id
string

Indicates which field was used to populate the "weight" field. Either "specified", "measured", or "estimated"

[
  • {
    }
]

packagings_complete

integer (packagings_complete) [ 0 .. 1 ]

Indicate if the packagings array contains all the packaging parts of the product. This field can be set by users when they enter or verify packaging data. Possible values are 0 or 1.

1

product_misc

additives_n
integer

Number of food additives.

checked
string
complete
integer
completeness
number
ecoscore_grade
string

See also: ecoscore_tags

ecoscore_score
integer

See also: ecoscore_tags

food_groups
string
food_groups_tags
Array of strings
object

Traffic light indicators on main nutrients levels

packaging_text
string

Recycling instructions as raw text, e.g. Plastic bottle to recycle, Plastic cap to recycle. This will get automatically parsed and will be used to compute the Eco-Score. You can either request it (if it exists) or send it in a specific language.

Array of objects (packagings)

The packagings object is an array of individual packaging component objects.

The Packaging data document explains how packaging data is structured in Open Food Facts: https://openfoodfacts.github.io/openfoodfacts-server/dev/explain-packaging-data/

The shape, material and recycling properties of each packaging component are linked to entries in the packaging_shapes, packaging_materials and packaging_recycling taxonomies:

https://world.openfoodfacts.org/data/taxonomies/packaging_shapes.json https://world.openfoodfacts.org/data/taxonomies/packaging_materials.json https://world.openfoodfacts.org/data/taxonomies/packaging_recycling.json

If the tags_lc field is set, the properties will include a lc_name field with the translation in the requested language.

packagings_complete
integer (packagings_complete) [ 0 .. 1 ]

Indicate if the packagings array contains all the packaging parts of the product. This field can be set by users when they enter or verify packaging data. Possible values are 0 or 1.

pnns_groups_1
string

Category of food according to French Nutrition and Health Program

pnns_groups_1_tags
Array of strings
pnns_groups_2
string

Sub Category of food according to French Nutrition and Health Program

pnns_groups_2_tags
Array of strings
popularity_key
integer

An imprecise measurement of popularity based on Scan statistics. A higher value means higher popularity.

popularity_tags
Array of strings

Indicators for the popularity of a product, like the amount of scans in a specific year. popularity_tags values from previous years are kept, if there is no popularity_tags at all, then it was never popular. This field must be used with care. In countries where Open Food Facts is not widely used, a product may obtain the value "top-90-percent-scans-2021" with a single scan.

scans_n
integer

Number of scans performed with the official Open Food Facts mobile application, the last year for which the product was scanned (current year excluded). This value is computed once a year by scanbot.pl. It is possible that a product has never been scanned at all: scans_n is not given in this case. See also unique_scans_n field.

unique_scans_n
integer

Number of unique scans performed with the official Open Food Facts mobile application, the last year for which the product was scanned (current year excluded). Unique scans means it is based on different IPs. This value is computed once a year by scanbot.pl. See also scans_n field.

serving_quantity
string

Normalized version of serving_size. Note that this is NOT the number of servings by product. (in perl, see normalize_serving_size)

serving_quantity_unit
string

The unit (either g or ml) for the correponding serving_quantity.

serving_size
string

Serving size text (generally in g or ml). We expect a quantity + unit but the user is free to input any string.

food_groups_(?<language_code>\w\w)
pattern property
string

see food_groups

packaging_text_(?<language_code>\w\w)
pattern property
string

Packaging text in language designated by language_code

{
  • "additives_n": 0,
  • "checked": "string",
  • "complete": 0,
  • "completeness": 0,
  • "ecoscore_grade": "string",
  • "ecoscore_score": 0,
  • "food_groups": "string",
  • "food_groups_tags": [
    ],
  • "nutrient_levels": {
    },
  • "packaging_text": "packaging_text_en",
  • "packagings": [
    ],
  • "packagings_complete": 1,
  • "pnns_groups_1": "string",
  • "pnns_groups_1_tags": [
    ],
  • "pnns_groups_2": "string",
  • "pnns_groups_2_tags": [
    ],
  • "popularity_key": 0,
  • "popularity_tags": [
    ],
  • "scans_n": 0,
  • "unique_scans_n": 0,
  • "serving_quantity": "string",
  • "serving_quantity_unit": "g",
  • "serving_size": "string"
}

Canonicalized taxonomy tag entry

string (Canonicalized taxonomy tag entry)

A tag entry, that has been matched against a taxonomy (e.g. a category, a label)

The entry is a string that can contain either:

  • a taxonomy entry id, in the form [2 letter language code]:[normalized canonical name] (e.g. "en:green-teas") -> for entries that could be matched to a taxonomy entry
  • a string in a specific language, prefixed by the 2 letter language code (e.g. "fr:Thés verts") -> for entries that could not be matched to a taxonomy entry
"string"

Indexed taxonomy tag entry (lossy, for search only)

string (Indexed taxonomy tag entry (lossy, for search only))

This field is used for search only. It is a lossy representation of the taxonomy tag entry, that can be used to index the entry in a search engine. A tag entry, that has been matched against a taxonomy (e.g. a category, a label)

The entry is a string that can contain either:

  • a taxonomy entry id, in the form [2 letter language code]:[normalized canonical name] (e.g. "en:green-teas") -> for entries that could be matched to a taxonomy entry
  • a string in a specific language, prefixed by the 2 letter language code, and normalized (deaccented and lowercased, depending on language) (e.g. "fr:thes-verts") -> for entries that could not be matched to a taxonomy entry
"string"

product_tags

brands
string

Comma separated list of brands (not taxonomized), in the last language used to edit it (recorded in brands_lc) This field is mostly used for debugging and testing purposes. Do not use it for display purposes.

brands_hierarchy
Array of strings (Canonicalized taxonomy tag entry)

An array of brands tag entries (for display and editing).

That is the id of brands found in taxonomy + brands not found in taxonomy (as-is, with no normalization).

This is the field that should be used for display purposes, as it is not lossy.

brands_lc
string

Language code of the last edit for brands

brands_tags
Array of strings (Indexed taxonomy tag entry (lossy, for search only))

An array of indexed brands tag entries (for search).

That is the id of brands found in taxonomy + brands not found in taxonomy (with case / accents / spaces normalized).

This is mostly used for search as the normalization of entries not in the taxonomy is lossy.

categories
string

Comma separated list of categories (not taxonomized), in the last language used to edit it (recorded in categories_lc) This field is mostly used for debugging and testing purposes. Do not use it for display purposes.

categories_hierarchy
Array of strings (Canonicalized taxonomy tag entry)

An array of categories tag entries (for display and editing).

That is the id of categories found in taxonomy + categories not found in taxonomy (as-is, with no normalization).

This is the field that should be used for display purposes, as it is not lossy.

categories_lc
string

Language code of the last edit for categories

categories_tags
Array of strings (Indexed taxonomy tag entry (lossy, for search only))

An array of indexed categories tag entries (for search).

That is the id of categories found in taxonomy + categories not found in taxonomy (with case / accents / spaces normalized).

This is mostly used for search as the normalization of entries not in the taxonomy is lossy.

checkers_tags
Array of strings
cities
string
cities_tags
Array of objects
correctors_tags
Array of strings
countries
string

List of countries where the product is sold.

countries_hierarchy
Array of strings
countries_lc
string

Countries language code

countries_tags
Array of strings
ecoscore_tags
Array of strings

All ecoscore of a product. Most of the time it's only one value, but it might eventually be more for products composed of sub-products. See also: ecoscore_score, ecoscore_grade.

emb_codes
string

Packager code. EMB is the French system of traceability codes for packager.

emb_codes_orig
string
emb_codes_tags
Array of objects
labels
string
labels_hierarchy
Array of strings
labels_lc
string
labels_tags
Array of strings
entry_dates_tags
Array of strings

The data as a series of tag: yyyy-mm-dd, yyyy-mm, yyyy

manufacturing_places
string

Places where the product was manufactured or transformed.

manufacturing_places_tags
Array of strings
nova_groups_tags
Array of strings
nutrient_levels_tags
Array of strings
{
  • "brands": "string",
  • "brands_hierarchy": [
    ],
  • "brands_lc": "string",
  • "brands_tags": [
    ],
  • "categories": "string",
  • "categories_hierarchy": [
    ],
  • "categories_lc": "string",
  • "categories_tags": [
    ],
  • "checkers_tags": [
    ],
  • "cities": "string",
  • "cities_tags": [
    ],
  • "correctors_tags": [
    ],
  • "countries": "string",
  • "countries_hierarchy": [
    ],
  • "countries_lc": "string",
  • "countries_tags": [
    ],
  • "ecoscore_tags": [
    ],
  • "emb_codes": "EMB 2013330",
  • "emb_codes_orig": "string",
  • "emb_codes_tags": [
    ],
  • "labels": "string",
  • "labels_hierarchy": [
    ],
  • "labels_lc": "string",
  • "labels_tags": [
    ],
  • "entry_dates_tags": [
    ],
  • "manufacturing_places": "string",
  • "manufacturing_places_tags": [
    ],
  • "nova_groups_tags": [
    ],
  • "nutrient_levels_tags": [
    ]
}

Image Size

h
integer

The height of the reduced/full image in pixels.

w
integer

The width of the reduced/full image in pixels.

url
string

The URL of the image. This property is generated at runtime if the generate_images_urls parameter is set to true.

{}

Images Sizes

object (ImageSize)

Contains the information (width, height and URL) about an image in a specific size. The URL is generated at runtime if the generate_images_urls parameter is set to true.

object (ImageSize)

Contains the information (width, height and URL) about an image in a specific size. The URL is generated at runtime if the generate_images_urls parameter is set to true.

object (ImageSize)

Contains the information (width, height and URL) about an image in a specific size. The URL is generated at runtime if the generate_images_urls parameter is set to true.

object (ImageSize)

Contains the information (width, height and URL) about an image in a specific size. The URL is generated at runtime if the generate_images_urls parameter is set to true.

{}

Uploaded image

uploader
string

userid of the user who uploaded the image.

object (ImageSizes)

Contains the information about the images of a product in different sizes. The reduced images are the ones with numbers as the key(100, 200 and 400) while the full images have full as the key.

{}

Selected image

imgid
integer

The imgid of the original/source image edited (rotated, cropped, normalized etc) to produce the selected image. When uploading a new image and selecting it, the imgid will be automatically assigned by the server, and this field should not be passed. When selecting a previously uploaded image, the imgid must be passed to identify the source image.

rev
integer

The revision number of the product when the image was selected.

object

Properties to specify if the image is cropped, rotated, normalized or with the white background removed.

object (ImageSizes)

Contains the information about the images of a product in different sizes. The reduced images are the ones with numbers as the key(100, 200 and 400) while the full images have full as the key.

{}

Selected images

object

Front images of the full product in languages shown on the packaging. In most cases we have a front image selected for only one language, unless the product has different packagings for different countries with the same barcode, or if the product has two front sides (e.g. in bilingual countries).

object

Cropped images of the ingredients list in languages shown on the packaging.

object

Cropped images of the nutrition facts table / list in languages shown on the packaging.

object

Cropped images of the packaging / recycling information in languages shown on the packaging.

{
  • "front": { },
  • "ingredients": { },
  • "nutrition": { },
  • "packaging": { }
}

Product Images

object (images)

Uploaded and selected images of the product.

object (Selected images URLs)

URLs of selected images, generated at runtime.

last_image_dates_tags
Array of strings

An array of tags entries to indicated the year, month and day of the last image upload (in formats YYYY, YYYY-MM, YYYY-MM-DD).

last_image_t
integer

timestamp of last image upload

{
  • "images": {
    },
  • "selected_images": { },
  • "last_image_dates_tags": [
    ],
  • "last_image_t": 0
}

EcoscoreCountryCode

string (EcoscoreCountryCode)
Enum: "ad" "al" "at" "ax" "ba" "be" "bg" "ch" "cy" "cz" "de" "dk" "dz" "ee" "eg" "es" "fi" "fo" "fr" "gg" "gi" "gr" "hr" "hu" "ie" "il" "im" "is" "it" "je" "lb" "li" "lt" "lu" "lv" "ly" "ma" "mc" "md" "me" "mk" "mt" "nl" "no" "pl" "ps" "pt" "ro" "rs" "se" "si" "sj" "sk" "sm" "sy" "tn" "tr" "ua" "uk" "us" "va" "world" "xk"
"ad"

EcoscoreCountryValues

property name*
additional property
number
Default: 0
{
  • "property1": 0,
  • "property2": 0
}

agribalyse

agribalyse_proxy_food_code
string
agribalyse_food_code
string
co2_agriculture
number
co2_consumption
integer
co2_distribution
number
co2_packaging
number
co2_processing
number
co2_total
number
co2_transportation
number
code
string
dqr
string
ef_agriculture
number
ef_consumption
integer
ef_distribution
number
ef_packaging
number
ef_processing
number
ef_total
number
ef_transportation
number
is_beverage
integer
name_en
string

This can be returned in many other languages like name_fr (for french).

score
integer
version
string
{
  • "agribalyse_proxy_food_code": "string",
  • "agribalyse_food_code": "string",
  • "co2_agriculture": 0,
  • "co2_consumption": 0,
  • "co2_distribution": 0,
  • "co2_packaging": 0,
  • "co2_processing": 0,
  • "co2_total": 0,
  • "co2_transportation": 0,
  • "code": "string",
  • "dqr": "string",
  • "ef_agriculture": 0,
  • "ef_consumption": 0,
  • "ef_distribution": 0,
  • "ef_packaging": 0,
  • "ef_processing": 0,
  • "ef_total": 0,
  • "ef_transportation": 0,
  • "is_beverage": 0,
  • "name_en": "string",
  • "score": 0,
  • "version": "string"
}

product_ecoscore

object (product_ecoscore_data)

An object about a lot of details about data needed for Eco-Score computation and complementary data of interest.

ecoscore_extended_data_version
string
environment_impact_level
string
environment_impact_level_tags
Array of objects
{
  • "ecoscore_data": {
    },
  • "ecoscore_extended_data_version": "string",
  • "environment_impact_level": "string",
  • "environment_impact_level_tags": [
    ]
}

ingredients

Array
id
string
ingredients
array (Ingredients) Recursive

This structure gives the different ingredients and some information about them, like estimate on their quantity.

percent
integer

The percentage of the ingredient.

percent_estimate
number

Estimated percentage of the ingredient.

percent_max
string or number

Maximum percentage of the ingredient.

percent_min
integer

Minimum percentage of the ingredient.

text
string

Text description of the ingredient.

vegan
string

Indicates if the ingredient is vegan.

vegetarian
string

Indicates if the ingredient is vegetarian.

[
  • {
    }
]

ingredient

id
string
ingredients
Array of objects (Ingredients)

This structure gives the different ingredients and some information about them, like estimate on their quantity.

percent
integer

The percentage of the ingredient.

percent_estimate
number

Estimated percentage of the ingredient.

percent_max
string or number

Maximum percentage of the ingredient.

percent_min
integer

Minimum percentage of the ingredient.

text
string

Text description of the ingredient.

vegan
string

Indicates if the ingredient is vegan.

vegetarian
string

Indicates if the ingredient is vegetarian.

{
  • "id": "string",
  • "ingredients": [
    ],
  • "percent": 0,
  • "percent_estimate": 0,
  • "percent_max": "string",
  • "percent_min": 0,
  • "text": "string",
  • "vegan": "string",
  • "vegetarian": "string"
}

product_ingredients

additives_tags
Array of strings
allergens
string

comma separated list of allergens

allergens_lc
string

language in which allergens where input

allergens_hierarchy
Array of strings
allergens_tags
Array of strings
Array of objects (Ingredients)

This structure gives the different ingredients and some information about them, like estimate on their quantity.

object
ingredients_analysis_tags
Array of strings
ingredients_from_or_that_may_be_from_palm_oil_n
integer
ingredients_from_palm_oil_n
integer
ingredients_from_palm_oil_tags
Array of objects
ingredients_hierarchy
Array of strings
ingredients_n
integer
ingredients_n_tags
Array of strings
ingredients_original_tags
Array of strings
ingredients_percent_analysis
integer

Indicates the result of ingredients analysis processing

  • not present -> we didn't run ingredient percent analysis (e.g. we have no ingredients)
  • 1: we estimated the ingredients percent.
  • -1 : we tried to estimate the ingredients, but the values were impossible. (e.g. if the sum of % is above 100%)
ingredients_sweeteners_n
integer

Number of sweeteners additives in the ingredients. Undefined if ingredients are not specified.

ingredients_non_nutritive_sweeteners_n
integer

Number of non-nutritive sweeteners additives (as specified in the Nutri-Score formula) in the ingredients. Undefined if ingredients are not specified.

ingredients_tags
Array of strings
ingredients_lc
string

Language that was used to parse the ingredient list. If ingredients_text is available for the product main language (lang), ingredients_lc=lang, otherwise we look at ingredients_text fields for other languages and set ingredients_lc to the first non-empty ingredient_text.

ingredients_text
string

Raw list of ingredients. This will get automatically parsed and get used to compute the Eco-Score or find allergens, etc..

It's a copy of ingredients_text in the main language of the product (see lang proprety).

ingredients_text_with_allergens
string

Same text as ingredients_text but where allergens have HTML elements around them to identify them

ingredients_that_may_be_from_palm_oil_n
integer
ingredients_that_may_be_from_palm_oil_tags
Array of objects
ingredients_with_specified_percent_n
integer
ingredients_with_specified_percent_sum
integer
ingredients_with_unspecified_percent_n
integer
ingredients_with_unspecified_percent_sum
integer
known_ingredients_n
integer
origins
string

Origins of ingredients

origins_hierarchy
Array of objects
origins_lc
string
origins_tags
Array of objects
traces
string

List of substances that might cause allergies that are present in trace amounts in the product (this does not include the ingredients, as they are not only present in trace amounts). It is taxonomized with the allergens taxonomy. Refer to the allergens taxonomy

Array of objects or strings
traces_lc
string
Array of objects or strings
unknown_ingredients_n
integer
ingredients_text_(?<language_code>\w\w)
pattern property
string

Raw list of ingredients in language given by 'language_code'.

See ingredients_text

ingredients_text_with_allergens_(?<language_code>\w\w)
pattern property
string

Like ingredients_text_with_allergens for a particular language

{
  • "additives_tags": [
    ],
  • "allergens": "string",
  • "allergens_lc": "string",
  • "allergens_hierarchy": [
    ],
  • "allergens_tags": [
    ],
  • "ingredients": [
    ],
  • "ingredients_analysis": {
    },
  • "ingredients_analysis_tags": [
    ],
  • "ingredients_from_or_that_may_be_from_palm_oil_n": 0,
  • "ingredients_from_palm_oil_n": 0,
  • "ingredients_from_palm_oil_tags": [
    ],
  • "ingredients_hierarchy": [
    ],
  • "ingredients_n": 0,
  • "ingredients_n_tags": [
    ],
  • "ingredients_original_tags": [
    ],
  • "ingredients_percent_analysis": 0,
  • "ingredients_sweeteners_n": 0,
  • "ingredients_non_nutritive_sweeteners_n": 0,
  • "ingredients_tags": [
    ],
  • "ingredients_lc": "string",
  • "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",
  • "ingredients_that_may_be_from_palm_oil_n": 0,
  • "ingredients_that_may_be_from_palm_oil_tags": [
    ],
  • "ingredients_with_specified_percent_n": 0,
  • "ingredients_with_specified_percent_sum": 0,
  • "ingredients_with_unspecified_percent_n": 0,
  • "ingredients_with_unspecified_percent_sum": 0,
  • "known_ingredients_n": 0,
  • "origins": "string",
  • "origins_hierarchy": [
    ],
  • "origins_lc": "string",
  • "origins_tags": [
    ],
  • "traces": "string",
  • "traces_hierarchy": [
    ],
  • "traces_lc": "string",
  • "traces_tags": [
    ],
  • "unknown_ingredients_n": 0
}

product_nutrition

no_nutrition_data
string

When a product does not have nutrition data displayed on the packaging, the user can check the field "Nutrition facts are not specified on the product". By doing so, the no_nutrition_data field takes the value "on". This case is frequent (thousands of products).

nutrition_data_per
string
Enum: "serving" "100g"

The nutrition data on the package can be per serving or per 100g.

This is essential to understand if <nutrient>_value and <nutrient> values in nutriments applies for a serving or for 100g.

IMPORTANT: When writing products, this setting applies to all existing nutrients values for the product, not only the nutrient values sent in the write request. So it should not be changed unless all nutrients values are provided with values that match the nutrition_data_per field.

nutrition_data_prepared_per
string
Enum: "serving" "100g"

The nutrition data for prepared product on the package (if any) can be per serving or per 100g.

This is essential to understand if <nutrient>_prepared_value and <nutrient>_prepared values in nutriments applies for a serving or for 100g.

See also important note on nutrition_data_per.

object

All known nutrients for the product.

Note that each nutrients are declined with a variety of suffixes like _100g, _serving, see patternProperties below.

A specific _unit is the unit used to measure the nutrient.

Beware that some properties are to be interpreted based upon nutrition_data_per value.

Also for products that have a nutrition table for prepared product (eg. the nutrition facts for a bowl of milk with cocoa powder), a _prepared suffix is added (before other suffixes).

You can get all possible nutrients from the nutrients taxonomy

FIXME add more nutrients with description.

object

Detail of data the Nutri-Score was computed upon.

Note: this might not be stable, don't rely too much on this, or, at least, tell us !

TODO document each property

nutrition_grade_fr
string

Nutrition grade (‘a’ to ‘e’), https://world.openfoodfacts.org/nutriscore.

nutrition_grades
string

Nutrition grades as a comma separated list.

Some products with multiple components might have multiple Nutri-Score

nutrition_grades_tags
Array of strings
nutrition_score_beverage
integer
nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients
integer
nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients_value
integer
nutrition_score_warning_no_fiber
integer
other_nutritional_substances_tags
Array of objects
unknown_nutrients_tags
Array of objects
vitamins_tags
Array of objects
{
  • "no_nutrition_data": "on",
  • "nutrition_data_per": "serving",
  • "nutrition_data_prepared_per": "serving",
  • "nutriments": {
    },
  • "nutriscore_data": {
    },
  • "nutrition_grade_fr": "string",
  • "nutrition_grades": "string",
  • "nutrition_grades_tags": [
    ],
  • "nutrition_score_beverage": 0,
  • "nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients": 0,
  • "nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients_value": 0,
  • "nutrition_score_warning_no_fiber": 0,
  • "other_nutritional_substances_tags": [
    ],
  • "unknown_nutrients_tags": [
    ],
  • "vitamins_tags": [
    ]
}

NutriscoreGrade

string (NutriscoreGrade)
Enum: "a" "b" "c" "d" "e"

Nutri-Score for the product as a letter.

See https://world.openfoodfacts.org/nutriscore.

"a"

NutriscoreYearData

category_available
integer
Enum: 0 1
grade
string (NutriscoreGrade)
Enum: "a" "b" "c" "d" "e"

Nutri-Score for the product as a letter.

See https://world.openfoodfacts.org/nutriscore.

nutrients_available
integer
Enum: 0 1
nutriscore_applicable
integer
Enum: 0 1
nutriscore_computed
integer
Enum: 0 1
score
integer
{
  • "category_available": 1,
  • "grade": "a",
  • "nutrients_available": 1,
  • "nutriscore_applicable": 1,
  • "nutriscore_computed": 1,
  • "score": 13
}

ProductType

is_beverage
integer
Enum: 0 1
is_cheese
integer
Enum: 0 1
is_water
integer
Enum: 0 1
{
  • "is_beverage": 0,
  • "is_cheese": 0,
  • "is_water": 0
}

Nutriscore2021InnerData

is_beverage
integer
Enum: 0 1
is_cheese
integer
Enum: 0 1
is_water
integer
Enum: 0 1
is_fat
integer
Enum: 0 1
energy
integer
energy_points
integer
energy_value
integer
fiber
number <float>
fiber_points
integer
fiber_value
number <float>
fruits_vegetables_nuts_colza_walnut_olive_oils
number <float>
fruits_vegetables_nuts_colza_walnut_olive_oils_points
integer
fruits_vegetables_nuts_colza_walnut_olive_oils_value
number <float>
proteins
number <float>
proteins_points
integer
proteins_value
number <float>
saturated_fat
number <float>
saturated_fat_points
integer
saturated_fat_value
number <float>
sodium
number <float>
sodium_points
integer
sodium_value
number <float>
sugars
number <float>
sugars_points
integer
sugars_value
number <float>
negative_points
integer
positive_points
integer
{
  • "is_beverage": 0,
  • "is_cheese": 0,
  • "is_water": 0,
  • "is_fat": 0,
  • "energy": 1996,
  • "energy_points": 5,
  • "energy_value": 1996,
  • "fiber": 3.8,
  • "fiber_points": 4,
  • "fiber_value": 3.8,
  • "fruits_vegetables_nuts_colza_walnut_olive_oils": 0,
  • "fruits_vegetables_nuts_colza_walnut_olive_oils_points": 0,
  • "fruits_vegetables_nuts_colza_walnut_olive_oils_value": 0,
  • "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
}

Nutriscore2021Data

is_beverage
integer
Enum: 0 1
is_cheese
integer
Enum: 0 1
is_water
integer
Enum: 0 1
is_fat
integer
Enum: 0 1
energy
integer
energy_points
integer
energy_value
integer
fiber
number <float>
fiber_points
integer
fiber_value
number <float>
fruits_vegetables_nuts_colza_walnut_olive_oils
number <float>
fruits_vegetables_nuts_colza_walnut_olive_oils_points
integer
fruits_vegetables_nuts_colza_walnut_olive_oils_value
number <float>
proteins
number <float>
proteins_points
integer
proteins_value
number <float>
saturated_fat
number <float>
saturated_fat_points
integer
saturated_fat_value
number <float>
sodium
number <float>
sodium_points
integer
sodium_value
number <float>
sugars
number <float>
sugars_points
integer
sugars_value
number <float>
negative_points
integer
positive_points
integer
grade
string (NutriscoreGrade)
Enum: "a" "b" "c" "d" "e"

Nutri-Score for the product as a letter.

See https://world.openfoodfacts.org/nutriscore.

score
integer
{
  • "is_beverage": 0,
  • "is_cheese": 0,
  • "is_water": 0,
  • "is_fat": 0,
  • "energy": 1996,
  • "energy_points": 5,
  • "energy_value": 1996,
  • "fiber": 3.8,
  • "fiber_points": 4,
  • "fiber_value": 3.8,
  • "fruits_vegetables_nuts_colza_walnut_olive_oils": 0,
  • "fruits_vegetables_nuts_colza_walnut_olive_oils_points": 0,
  • "fruits_vegetables_nuts_colza_walnut_olive_oils_value": 0,
  • "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": "a",
  • "score": 13
}

NutriscoreComponent

id
string
points
integer
points_max
integer
unit
string
value
null or number <float>
{
  • "id": "energy",
  • "points": 5,
  • "points_max": 10,
  • "unit": "kJ",
  • "value": 21.5
}

Nutriscore2023Data

is_beverage
integer
Enum: 0 1
is_cheese
integer
Enum: 0 1
is_water
integer
Enum: 0 1
is_fat_oil_nuts_seeds
integer
Enum: 0 1
is_red_meat_product
integer
Enum: 0 1
object (Nutriscore2023DataComponents)
count_proteins
number <float>
count_proteins_reason
string
negative_points
integer
positive_points
integer
negative_points_max
integer
positive_points_max
integer
positive_nutrients
Array of strings
{
  • "is_beverage": 0,
  • "is_cheese": 0,
  • "is_water": 0,
  • "is_fat_oil_nuts_seeds": 0,
  • "is_red_meat_product": 0,
  • "components": {
    },
  • "count_proteins": 0,
  • "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": [
    ]
}

Nutriscores

object (Nutriscore2021)
object (Nutriscore2023)
{
  • "2021": {
    },
  • "2023": {
    }
}

NutriscoreGradeTags

Array
string (NutriscoreGrade)
Enum: "a" "b" "c" "d" "e"

Nutri-Score for the product as a letter.

See https://world.openfoodfacts.org/nutriscore.

[
  • "d"
]

ProductNutriscore

object (Nutriscores)
nutriscore_2021_tags
Array of strings (NutriscoreGradeTags)
Items Enum: "a" "b" "c" "d" "e"
nutriscore_2023_tags
Array of strings (NutriscoreGradeTags)
Items Enum: "a" "b" "c" "d" "e"
object (Nutriscore2021Data)
nutriscore_grade
string (NutriscoreGrade)
Enum: "a" "b" "c" "d" "e"

Nutri-Score for the product as a letter.

See https://world.openfoodfacts.org/nutriscore.

nutriscore_score
integer

Nutri-Score for the product as an integer (see also nutriscore_grade).

nutriscore_score_opposite
integer
nutriscore_tags
Array of strings (NutriscoreGradeTags)
Items Enum: "a" "b" "c" "d" "e"
nutriscore_version
string
{
  • "nutriscore": {
    },
  • "nutriscore_2021_tags": [
    ],
  • "nutriscore_2023_tags": [
    ],
  • "nutriscore_data": {
    },
  • "nutriscore_grade": "a",
  • "nutriscore_score": 13,
  • "nutriscore_score_opposite": -13,
  • "nutriscore_tags": [
    ],
  • "nutriscore_version": "string"
}

product_quality

data_quality_bugs_tags
Array of strings
data_quality_errors_tags
Array of strings
data_quality_info_tags
Array of strings
data_quality_tags
Array of strings
data_quality_warnings_tags
Array of strings
data_sources
string

Source of data imported from producers.

data_sources_tags
Array of strings
last_check_dates_tags
Array of strings
last_checked_t
integer
last_checker
string
states
string

comma separated list of values indicating some states of the product, like things to be done, or to be completed. See states taxonomy

states_hierarchy
Array of strings
states_tags
Array of strings
misc_tags
Array of strings

Information about different aspect of the product Refer to misc taxonomy

{
  • "data_quality_bugs_tags": [
    ],
  • "data_quality_errors_tags": [
    ],
  • "data_quality_info_tags": [
    ],
  • "data_quality_tags": [
    ],
  • "data_quality_warnings_tags": [
    ],
  • "data_sources": "string",
  • "data_sources_tags": [
    ],
  • "last_check_dates_tags": [
    ],
  • "last_checked_t": 0,
  • "last_checker": "string",
  • "states": "string",
  • "states_hierarchy": [
    ],
  • "states_tags": [
    ],
  • "misc_tags": [
    ]
}

product_extended

additives_original_tags
Array of strings
additives_prev_original_tags
Array of strings
added_countries_tags
Array of objects
allergens_from_ingredients
string
allergens_from_user
string
amino_acids_prev_tags
Array of objects
amino_acids_tags
Array of objects
carbon_footprint_percent_of_known_ingredients
integer
object
categories_properties_tags
Array of strings
object
ciqual_food_name_tags
Array of strings
compared_to_category
string

the category to use for comparison.

TODO explain how it is chosen.

conservation_conditions
string
customer_service
string

Contact info of customer service.

expiration_date
string
link
string

link to the product on the website of the producer

main_countries_tags
Array of objects
minerals_prev_tags
Array of objects
minerals_tags
Array of objects
object

Those are fields provided by the producer (through producers platform), and the value he provided.

object

Detail of ingredients or processing that makes the products having Nova 3 or 4

nucleotides_tags
Array of objects
origin
string
purchase_places
string

Country, state, or city where the product can be purchased.

purchase_places_tags
Array of strings
stores
string

Distributor name.

stores_tags
Array of strings
traces_from_ingredients
string
traces_from_user
string
conservation_conditions_(?<language_code>\w\w)
pattern property
string
customer_service_(?<language_code>\w\w)
pattern property
string
origin_(?<language_code>\w\w)
pattern property
string

origin in language indicated by language_code

{
  • "additives_original_tags": [
    ],
  • "additives_prev_original_tags": [
    ],
  • "added_countries_tags": [
    ],
  • "allergens_from_ingredients": "string",
  • "allergens_from_user": "string",
  • "amino_acids_prev_tags": [
    ],
  • "amino_acids_tags": [
    ],
  • "carbon_footprint_percent_of_known_ingredients": 0,
  • "categories_properties": {
    },
  • "categories_properties_tags": [
    ],
  • "category_properties": {
    },
  • "ciqual_food_name_tags": [
    ],
  • "compared_to_category": "string",
  • "conservation_conditions": "string",
  • "customer_service": "string",
  • "expiration_date": "string",
  • "link": "string",
  • "main_countries_tags": [
    ],
  • "minerals_prev_tags": [
    ],
  • "minerals_tags": [
    ],
  • "owner_fields": {
    },
  • "nova_groups_markers": {
    },
  • "nucleotides_tags": [
    ],
  • "origin": "string",
  • "purchase_places": "Paris",
  • "purchase_places_tags": [
    ],
  • "stores": "Walmart",
  • "stores_tags": [
    ],
  • "traces_from_ingredients": "string",
  • "traces_from_user": "string"
}

product_meta

created_t
integer

Date when the product was added (UNIX timestamp format). See also entry_dates_tags

creator
string

The contributor who added the product first.

editors_tags
Array of strings

List of editors who edited the product.

informers_tags
Array of strings
interface_version_created
string
interface_version_modified
string
object
object

Same as languages but by language code, instead of language tags

languages_hierarchy
Array of strings
languages_tags
Array of strings
last_edit_dates_tags
Array of strings
last_editor
string
last_modified_by
string

The username of the user who last modified the product.

last_modified_t
integer

Date when the product page was last modified. This date is updated only when primary data is modified (data entered by the user or updated by an interface)

last_updated_t
integer

Date when the product page was last modified. This date is updated when primary data or secondary data is modified (primary: data entered by a user or read from an interface, secondary: data computed by a utility such as update_all_products.pl)

owner
string

Id of the producer in case he provides his own data about a product (producer platform).

owners_tags
string

Tagyfied version of owner

photographers_tags
Array of strings
rev
integer

revision number of this product version (each edit adds a revision)

Array of objects (product_meta_source)
object (product_meta_source_fields)
teams
string
teams_tags
Array of strings
update_key
string
{
  • "created_t": 1457680652,
  • "creator": "string",
  • "editors_tags": [
    ],
  • "informers_tags": [
    ],
  • "interface_version_created": "string",
  • "interface_version_modified": "string",
  • "languages": { },
  • "languages_codes": { },
  • "languages_hierarchy": [
    ],
  • "languages_tags": [
    ],
  • "last_edit_dates_tags": [
    ],
  • "last_editor": "string",
  • "last_modified_by": "sebleouf",
  • "last_modified_t": 0,
  • "last_updated_t": 0,
  • "owner": "string",
  • "owners_tags": "string",
  • "photographers_tags": [
    ],
  • "rev": 0,
  • "sources": [
    ],
  • "sources_fields": {
    },
  • "teams": "string",
  • "teams_tags": [
    ],
  • "update_key": "string"
}

title_element

name
string

A short name of this panel, not including any actual values

title
string
type
string
Enum: "grade" "percentage"

Used to indicate how the value of this item is measured, such as "grade" for Nutri-Score and Green-Score or "percentage" for Salt

grade
string
Enum: "a+" "a" "b" "c" "d" "e" "f" "unknown"

The value for this panel where it corresponds to a A to E grade such as the Nutri-Score or the Green-Score.

value
number

The numeric value of the panel, where the type is "percentage"

icon_url
string
icon_color_from_evaluation
string
icon_size
string

If set to "small", the icon should be displayed at a small size.

{
  • "name": "string",
  • "title": "string",
  • "type": "grade",
  • "grade": "a+",
  • "value": 0,
  • "icon_url": "string",
  • "icon_color_from_evaluation": "string",
  • "icon_size": "string"
}

text_element

type
string
Enum: "summary" "warning" "notes"

the type of text, might influence the way you display it.

html
string

Text to display in HTML format.

language
string

Language of the text. The name of the language is returned in the language requested when making the API call. e.g. if the text is in Polish, and the requested language is French, the language field will contain "Polonais" (French for "Polish"). Only set for specific fields such as the list of ingredients of a product.

lc
string

2 letter language code for the text. Only set for specific fields such as the list of ingredients of a product.

edit_field_id
string

id of the field used to edit this text in the product edit API.

edit_field_type
string

Type of the product field.

edit_field_value
string

Current value of the product field. This may differ from the html field which can contain extra formating.

source_url
string

Link to the source

source_text
string

name of the source

source_lc
string

Source locale name

source_language
string

Human readable source locale name

{
  • "type": "summary",
  • "html": "string",
  • "language": "string",
  • "lc": "string",
  • "edit_field_id": "string",
  • "edit_field_type": "string",
  • "edit_field_value": "string",
  • "source_url": "https://en.wikipedia.org/wiki/Sodium acetate",
  • "source_text": "Wikipedia",
  • "source_lc": "en",
  • "source_language": "English"
}

image_element

url
string

full URL of the image

width
integer

Width of the image.

This is just a suggestion coming from the server, the client may choose to use its own dimensions for the image.

height
integer

Height of the image.

This is just a suggestion coming from the server, the client may choose to use its own dimensions for the image.

alt_text
string

Alt Text of the image.

{
  • "url": "string",
  • "width": 0,
  • "height": 0,
  • "alt_text": "string"
}

panel_element

panel_id
string

The id of the panel to include. The id is the key of the panel in the panels object returned in the knowledge_panels field.

{
  • "panel_id": "string"
}

panel_group_element

title
string
panel_ids
Array of strings

The ids of the panels to include. The ids are the keys of the panels in the panels object returned in the knowledge_panels field.

image
object

An image related to the panel group (e.g. the ingredients or nutrition facts image for the ingredients and nutrition panel groups).

{
  • "title": "string",
  • "panel_ids": [
    ],
  • "image": { }
}

table_element

id
string

An id for the table.

title
string

Title of the column.

rows
string
Array of objects (table_column)
{
  • "id": "string",
  • "title": "string",
  • "rows": "string",
  • "columns": [
    ]
}

element

type
required
string
Enum: "text" "image" "action" "panel" "panel_group" "table"

The type of the included element object. The type also indicates which field contains the included element object. e.g. if the type is "text", the included element object will be in the "text_element" field.

Note that in the future, new type of element may be added, so your code should ignore unrecognized types, and unknown properties.

TODO: add Map type

object (text_element)

A text in simple HTML format to display.

For some specific texts that correspond to a product field (e.g. a product name, the ingredients list of a product),the edit_field_* fields are used to indicate how to edit the field value.

object (image_element)
action_element
string
object (panel_element)

Panels can include other panels as sub-panels using the panel_element.

object (panel_group_element)

The panel group element is used to display an optional title followed by a number of sub-panels.

object (table_element)

Element to display a table.

{
  • "type": "text",
  • "text_element": {
    },
  • "image_element": {
    },
  • "action_element": "string",
  • "panel_element": {
    },
  • "panel_group_element": {
    },
  • "table_element": {
    }
}

panel

type
string

Type of the panel. If set to "card", the panel and its sub-panels should be displayed in a card. If set to "inline", the panel should have its content always displayed.

expanded
boolean

If true, the panel is to be displayed already expanded. If false, only the title should be displayed, and the user should be able to click or tap it to open the panel and display the elements.

expand_for
string

If set to "large", the content of the panel should be expanded on large screens, but it should still be possible to unexpand it.

evaluation
string
Enum: "good" "average" "neutral" "bad" "unknown"

An evaluation status specifically for this title element. This can be used to directly color the icon if 'icon_color_from_evaluation' is true and this field is present, or it might provide context for the title itself. e.g. bad is red. Please be careful in choosing colors, to avoid 50 shades of red.

half_width_on_mobile
boolean

If true, suggests that this panel could be rendered as half-width on mobile devices, allowing for side-by-side display with another half-width panel if applicable.

object (title_element)

The title of a panel.

Array of objects (element)

An ordered list of elements to display in the content of the panel.

level
string

a message level, as levels we use in log. It might help theming the panel visually. Some possible values: info, recommendation

size
string
Value: "small"

size is either empty (normal display) or small to indicate a panel that should have a smaller font size

topics
Array of strings

topics currently include health, environment, problem

{
  • "type": "string",
  • "expanded": true,
  • "expand_for": "string",
  • "evaluation": "bad",
  • "half_width_on_mobile": true,
  • "title_element": {
    },
  • "elements": [
    ],
  • "level": "info",
  • "size": "small",
  • "topics": [
    ]
}

panels

object (panel)

Each panel contains an optional title and an optional array of elements.

{
  • "additionalProperties": "string"
}

product_knowledge_panels

object (panels)

The panels object is a dictionary of individual panel objects. Each key of the dictionary is the id of the panel, and the value is the panel object.

Apps typically display a number of root panels with known panel ids (e.g. health_card and environment_card). Panels can reference other panels and display them as sub-panels.

{
  • "knowledge_panels": {
    }
}

product_attribute_groups

Array of objects (product_attribute_group)

Each element is an attribute that can help compute a personal ranking for the product

{
  • "attribute_groups": [
    ]
}

product

abbreviated_product_name
string

Abbreviated name in requested language

code
string

barcode of the product (can be EAN-13 or internal codes for some food stores), for products without a barcode, Open Food Facts assigns a number starting with the 200 reserved prefix

codes_tags
Array of strings
generic_name
string

Legal name of the product as regulated by the European authorities.

id
string

internal identifier for the product, usually set to the value of code, except on the producers platform where it is prefixed by the owner

lc
string

Main language of the product. This is a duplicate of lang property (for historical reasons).

lang
string

Main language of the product.

This should be the main language of product packaging (if one is predominant).

Main language is also used to decide which ingredients list to parse.

nova_group
integer

Nova group as an integer from 1 to 4. See https://world.openfoodfacts.org/nova

nova_groups
string
obsolete
string
obsolete_since_date
string

A date at which the product was declared obsolete. This means it's not produced any more.

product_name
string

The name of the product

product_name_en
string

The name of the product can also be in many other languages like product_name_fr (for French).

product_quantity
string

The size in g or ml for the whole product. It is a normalized version of the quantity field. A quantity of "2 x 60 g" leads to product_quantity: "120".

product_quantity_unit
string

The unit (either g or ml) for the corresponding product_quantity. It is computed from the quantity field. A quantity of "6 x 250 ml" leads to product_quantity_unit: "ml".

quantity
string

The quantity of the product, with the corresponding number of portions or unit (g, ml, kg, l, cl, oz, lbs...). It should be the value as displayed on the product. The ℮ sign is allowed. When it refers to the number of portions, it can be filled without any units (e.g. "6 eggs").

schema_version
integer

Version of the product object schema used in the response. This indicates the structure of the 'product' field itself. For more details, please read: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-api-and-product-schema-change-log

additives_n
integer

Number of food additives.

checked
string
complete
integer
completeness
number
ecoscore_grade
string

See also: ecoscore_tags

ecoscore_score
integer

See also: ecoscore_tags

food_groups
string
food_groups_tags
Array of strings
object

Traffic light indicators on main nutrients levels

packaging_text
string

Recycling instructions as raw text, e.g. Plastic bottle to recycle, Plastic cap to recycle. This will get automatically parsed and will be used to compute the Eco-Score. You can either request it (if it exists) or send it in a specific language.

Array of objects (packagings)

The packagings object is an array of individual packaging component objects.

The Packaging data document explains how packaging data is structured in Open Food Facts: https://openfoodfacts.github.io/openfoodfacts-server/dev/explain-packaging-data/

The shape, material and recycling properties of each packaging component are linked to entries in the packaging_shapes, packaging_materials and packaging_recycling taxonomies:

https://world.openfoodfacts.org/data/taxonomies/packaging_shapes.json https://world.openfoodfacts.org/data/taxonomies/packaging_materials.json https://world.openfoodfacts.org/data/taxonomies/packaging_recycling.json

If the tags_lc field is set, the properties will include a lc_name field with the translation in the requested language.

packagings_complete
integer (packagings_complete) [ 0 .. 1 ]

Indicate if the packagings array contains all the packaging parts of the product. This field can be set by users when they enter or verify packaging data. Possible values are 0 or 1.

pnns_groups_1
string

Category of food according to French Nutrition and Health Program

pnns_groups_1_tags
Array of strings
pnns_groups_2
string

Sub Category of food according to French Nutrition and Health Program

pnns_groups_2_tags
Array of strings
popularity_key
integer

An imprecise measurement of popularity based on Scan statistics. A higher value means higher popularity.

popularity_tags
Array of strings

Indicators for the popularity of a product, like the amount of scans in a specific year. popularity_tags values from previous years are kept, if there is no popularity_tags at all, then it was never popular. This field must be used with care. In countries where Open Food Facts is not widely used, a product may obtain the value "top-90-percent-scans-2021" with a single scan.

scans_n
integer

Number of scans performed with the official Open Food Facts mobile application, the last year for which the product was scanned (current year excluded). This value is computed once a year by scanbot.pl. It is possible that a product has never been scanned at all: scans_n is not given in this case. See also unique_scans_n field.

unique_scans_n
integer

Number of unique scans performed with the official Open Food Facts mobile application, the last year for which the product was scanned (current year excluded). Unique scans means it is based on different IPs. This value is computed once a year by scanbot.pl. See also scans_n field.

serving_quantity
string

Normalized version of serving_size. Note that this is NOT the number of servings by product. (in perl, see normalize_serving_size)

serving_quantity_unit
string

The unit (either g or ml) for the correponding serving_quantity.

serving_size
string

Serving size text (generally in g or ml). We expect a quantity + unit but the user is free to input any string.

brands
string

Comma separated list of brands (not taxonomized), in the last language used to edit it (recorded in brands_lc) This field is mostly used for debugging and testing purposes. Do not use it for display purposes.

brands_hierarchy
Array of strings (Canonicalized taxonomy tag entry)

An array of brands tag entries (for display and editing).

That is the id of brands found in taxonomy + brands not found in taxonomy (as-is, with no normalization).

This is the field that should be used for display purposes, as it is not lossy.

brands_lc
string

Language code of the last edit for brands

brands_tags
Array of strings (Indexed taxonomy tag entry (lossy, for search only))

An array of indexed brands tag entries (for search).

That is the id of brands found in taxonomy + brands not found in taxonomy (with case / accents / spaces normalized).

This is mostly used for search as the normalization of entries not in the taxonomy is lossy.

categories
string

Comma separated list of categories (not taxonomized), in the last language used to edit it (recorded in categories_lc) This field is mostly used for debugging and testing purposes. Do not use it for display purposes.

categories_hierarchy
Array of strings (Canonicalized taxonomy tag entry)

An array of categories tag entries (for display and editing).

That is the id of categories found in taxonomy + categories not found in taxonomy (as-is, with no normalization).

This is the field that should be used for display purposes, as it is not lossy.

categories_lc
string

Language code of the last edit for categories

categories_tags
Array of strings (Indexed taxonomy tag entry (lossy, for search only))

An array of indexed categories tag entries (for search).

That is the id of categories found in taxonomy + categories not found in taxonomy (with case / accents / spaces normalized).

This is mostly used for search as the normalization of entries not in the taxonomy is lossy.

checkers_tags
Array of strings
cities
string
cities_tags
Array of objects
correctors_tags
Array of strings
countries
string

List of countries where the product is sold.

countries_hierarchy
Array of strings
countries_lc
string

Countries language code

countries_tags
Array of strings
ecoscore_tags
Array of strings

All ecoscore of a product. Most of the time it's only one value, but it might eventually be more for products composed of sub-products. See also: ecoscore_score, ecoscore_grade.

emb_codes
string

Packager code. EMB is the French system of traceability codes for packager.

emb_codes_orig
string
emb_codes_tags
Array of objects
labels
string
labels_hierarchy
Array of strings
labels_lc
string
labels_tags
Array of strings
entry_dates_tags
Array of strings

The data as a series of tag: yyyy-mm-dd, yyyy-mm, yyyy

manufacturing_places
string

Places where the product was manufactured or transformed.

manufacturing_places_tags
Array of strings
nova_groups_tags
Array of strings
nutrient_levels_tags
Array of strings
object (images)

Uploaded and selected images of the product.

object (Selected images URLs)

URLs of selected images, generated at runtime.

last_image_dates_tags
Array of strings

An array of tags entries to indicated the year, month and day of the last image upload (in formats YYYY, YYYY-MM, YYYY-MM-DD).

last_image_t
integer

timestamp of last image upload

object (product_ecoscore_data)

An object about a lot of details about data needed for Eco-Score computation and complementary data of interest.

ecoscore_extended_data_version
string
environment_impact_level
string
environment_impact_level_tags
Array of objects
additives_tags
Array of strings
allergens
string

comma separated list of allergens

allergens_lc
string

language in which allergens where input

allergens_hierarchy
Array of strings
allergens_tags
Array of strings
Array of objects (Ingredients)

This structure gives the different ingredients and some information about them, like estimate on their quantity.

object
ingredients_analysis_tags
Array of strings
ingredients_from_or_that_may_be_from_palm_oil_n
integer
ingredients_from_palm_oil_n
integer
ingredients_from_palm_oil_tags
Array of objects
ingredients_hierarchy
Array of strings
ingredients_n
integer
ingredients_n_tags
Array of strings
ingredients_original_tags
Array of strings
ingredients_percent_analysis
integer

Indicates the result of ingredients analysis processing

  • not present -> we didn't run ingredient percent analysis (e.g. we have no ingredients)
  • 1: we estimated the ingredients percent.
  • -1 : we tried to estimate the ingredients, but the values were impossible. (e.g. if the sum of % is above 100%)
ingredients_sweeteners_n
integer

Number of sweeteners additives in the ingredients. Undefined if ingredients are not specified.

ingredients_non_nutritive_sweeteners_n
integer

Number of non-nutritive sweeteners additives (as specified in the Nutri-Score formula) in the ingredients. Undefined if ingredients are not specified.

ingredients_tags
Array of strings
ingredients_lc
string

Language that was used to parse the ingredient list. If ingredients_text is available for the product main language (lang), ingredients_lc=lang, otherwise we look at ingredients_text fields for other languages and set ingredients_lc to the first non-empty ingredient_text.

ingredients_text
string

Raw list of ingredients. This will get automatically parsed and get used to compute the Eco-Score or find allergens, etc..

It's a copy of ingredients_text in the main language of the product (see lang proprety).

ingredients_text_with_allergens
string

Same text as ingredients_text but where allergens have HTML elements around them to identify them

ingredients_that_may_be_from_palm_oil_n
integer
ingredients_that_may_be_from_palm_oil_tags
Array of objects
ingredients_with_specified_percent_n
integer
ingredients_with_specified_percent_sum
integer
ingredients_with_unspecified_percent_n
integer
ingredients_with_unspecified_percent_sum
integer
known_ingredients_n
integer
origins
string

Origins of ingredients

origins_hierarchy
Array of objects
origins_lc
string
origins_tags
Array of objects
traces
string

List of substances that might cause allergies that are present in trace amounts in the product (this does not include the ingredients, as they are not only present in trace amounts). It is taxonomized with the allergens taxonomy. Refer to the allergens taxonomy

Array of objects or strings
traces_lc
string
Array of objects or strings
unknown_ingredients_n
integer
no_nutrition_data
string

When a product does not have nutrition data displayed on the packaging, the user can check the field "Nutrition facts are not specified on the product". By doing so, the no_nutrition_data field takes the value "on". This case is frequent (thousands of products).

nutrition_data_per
string
Enum: "serving" "100g"

The nutrition data on the package can be per serving or per 100g.

This is essential to understand if <nutrient>_value and <nutrient> values in nutriments applies for a serving or for 100g.

IMPORTANT: When writing products, this setting applies to all existing nutrients values for the product, not only the nutrient values sent in the write request. So it should not be changed unless all nutrients values are provided with values that match the nutrition_data_per field.

nutrition_data_prepared_per
string
Enum: "serving" "100g"

The nutrition data for prepared product on the package (if any) can be per serving or per 100g.

This is essential to understand if <nutrient>_prepared_value and <nutrient>_prepared values in nutriments applies for a serving or for 100g.

See also important note on nutrition_data_per.

object

All known nutrients for the product.

Note that each nutrients are declined with a variety of suffixes like _100g, _serving, see patternProperties below.

A specific _unit is the unit used to measure the nutrient.

Beware that some properties are to be interpreted based upon nutrition_data_per value.

Also for products that have a nutrition table for prepared product (eg. the nutrition facts for a bowl of milk with cocoa powder), a _prepared suffix is added (before other suffixes).

You can get all possible nutrients from the nutrients taxonomy

FIXME add more nutrients with description.

object (Nutriscore2021Data)

Detail of data the Nutri-Score was computed upon.

Note: this might not be stable, don't rely too much on this, or, at least, tell us !

TODO document each property

nutrition_grade_fr
string

Nutrition grade (‘a’ to ‘e’), https://world.openfoodfacts.org/nutriscore.

nutrition_grades
string

Nutrition grades as a comma separated list.

Some products with multiple components might have multiple Nutri-Score

nutrition_grades_tags
Array of strings
nutrition_score_beverage
integer
nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients
integer
nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients_value
integer
nutrition_score_warning_no_fiber
integer
other_nutritional_substances_tags
Array of objects
unknown_nutrients_tags
Array of objects
vitamins_tags
Array of objects
object (Nutriscores)
nutriscore_2021_tags
Array of strings (NutriscoreGradeTags)
Items Enum: "a" "b" "c" "d" "e"
nutriscore_2023_tags
Array of strings (NutriscoreGradeTags)
Items Enum: "a" "b" "c" "d" "e"
nutriscore_grade
string (NutriscoreGrade)
Enum: "a" "b" "c" "d" "e"

Nutri-Score for the product as a letter.

See https://world.openfoodfacts.org/nutriscore.

nutriscore_score
integer

Nutri-Score for the product as an integer (see also nutriscore_grade).

nutriscore_score_opposite
integer
nutriscore_tags
Array of strings (NutriscoreGradeTags)
Items Enum: "a" "b" "c" "d" "e"
nutriscore_version
string
data_quality_bugs_tags
Array of strings
data_quality_errors_tags
Array of strings
data_quality_info_tags
Array of strings
data_quality_tags
Array of strings
data_quality_warnings_tags
Array of strings
data_sources
string

Source of data imported from producers.

data_sources_tags
Array of strings
last_check_dates_tags
Array of strings
last_checked_t
integer
last_checker
string
states
string

comma separated list of values indicating some states of the product, like things to be done, or to be completed. See states taxonomy

states_hierarchy
Array of strings
states_tags
Array of strings
misc_tags
Array of strings

Information about different aspect of the product Refer to misc taxonomy

additives_original_tags
Array of strings
additives_prev_original_tags
Array of strings
added_countries_tags
Array of objects
allergens_from_ingredients
string
allergens_from_user
string
amino_acids_prev_tags
Array of objects
amino_acids_tags
Array of objects
carbon_footprint_percent_of_known_ingredients
integer
object
categories_properties_tags
Array of strings
object
ciqual_food_name_tags
Array of strings
compared_to_category
string

the category to use for comparison.

TODO explain how it is chosen.

conservation_conditions
string
customer_service
string

Contact info of customer service.

expiration_date
string
link
string

link to the product on the website of the producer

main_countries_tags
Array of objects
minerals_prev_tags
Array of objects
minerals_tags
Array of objects
object

Those are fields provided by the producer (through producers platform), and the value he provided.

object

Detail of ingredients or processing that makes the products having Nova 3 or 4

nucleotides_tags
Array of objects
origin
string
purchase_places
string

Country, state, or city where the product can be purchased.

purchase_places_tags
Array of strings
stores
string

Distributor name.

stores_tags
Array of strings
traces_from_ingredients
string
traces_from_user
string
created_t
integer

Date when the product was added (UNIX timestamp format). See also entry_dates_tags

creator
string

The contributor who added the product first.

editors_tags
Array of strings

List of editors who edited the product.

informers_tags
Array of strings
interface_version_created
string
interface_version_modified
string
object
object

Same as languages but by language code, instead of language tags

languages_hierarchy
Array of strings
languages_tags
Array of strings
last_edit_dates_tags
Array of strings
last_editor
string
last_modified_by
string

The username of the user who last modified the product.

last_modified_t
integer

Date when the product page was last modified. This date is updated only when primary data is modified (data entered by the user or updated by an interface)

last_updated_t
integer

Date when the product page was last modified. This date is updated when primary data or secondary data is modified (primary: data entered by a user or read from an interface, secondary: data computed by a utility such as update_all_products.pl)

owner
string

Id of the producer in case he provides his own data about a product (producer platform).

owners_tags
string

Tagyfied version of owner

photographers_tags
Array of strings
rev
integer

revision number of this product version (each edit adds a revision)

Array of objects (product_meta_source)
object (product_meta_source_fields)
teams
string
teams_tags
Array of strings
update_key
string
object (panels)

The panels object is a dictionary of individual panel objects. Each key of the dictionary is the id of the panel, and the value is the panel object.

Apps typically display a number of root panels with known panel ids (e.g. health_card and environment_card). Panels can reference other panels and display them as sub-panels.

Array of objects (product_attribute_group)

Each element is an attribute that can help compute a personal ranking for the product

conservation_conditions_(?<language_code>\w\w)
pattern property
string
customer_service_(?<language_code>\w\w)
pattern property
string
origin_(?<language_code>\w\w)
pattern property
string

origin in language indicated by language_code

{
  • "abbreviated_product_name": "string",
  • "code": "string",
  • "codes_tags": [
    ],
  • "generic_name": "string",
  • "id": "string",
  • "lc": "string",
  • "lang": "string",
  • "nova_group": 0,
  • "nova_groups": "string",
  • "obsolete": "string",
  • "obsolete_since_date": "string",
  • "product_name": "string",
  • "product_name_en": "string",
  • "product_quantity": "500",
  • "product_quantity_unit": "g",
  • "quantity": "3 x 150 g",
  • "schema_version": 999,
  • "additives_n": 0,
  • "checked": "string",
  • "complete": 0,
  • "completeness": 0,
  • "ecoscore_grade": "string",
  • "ecoscore_score": 0,
  • "food_groups": "string",
  • "food_groups_tags": [
    ],
  • "nutrient_levels": {
    },
  • "packaging_text": "packaging_text_en",
  • "packagings": [
    ],
  • "packagings_complete": 1,
  • "pnns_groups_1": "string",
  • "pnns_groups_1_tags": [
    ],
  • "pnns_groups_2": "string",
  • "pnns_groups_2_tags": [
    ],
  • "popularity_key": 0,
  • "popularity_tags": [
    ],
  • "scans_n": 0,
  • "unique_scans_n": 0,
  • "serving_quantity": "string",
  • "serving_quantity_unit": "g",
  • "serving_size": "string",
  • "brands": "string",
  • "brands_hierarchy": [
    ],
  • "brands_lc": "string",
  • "brands_tags": [
    ],
  • "categories": "string",
  • "categories_hierarchy": [
    ],
  • "categories_lc": "string",
  • "categories_tags": [
    ],
  • "checkers_tags": [
    ],
  • "cities": "string",
  • "cities_tags": [
    ],
  • "correctors_tags": [
    ],
  • "countries": "string",
  • "countries_hierarchy": [
    ],
  • "countries_lc": "string",
  • "countries_tags": [
    ],
  • "ecoscore_tags": [
    ],
  • "emb_codes": "EMB 2013330",
  • "emb_codes_orig": "string",
  • "emb_codes_tags": [
    ],
  • "labels": "string",
  • "labels_hierarchy": [
    ],
  • "labels_lc": "string",
  • "labels_tags": [
    ],
  • "entry_dates_tags": [
    ],
  • "manufacturing_places": "string",
  • "manufacturing_places_tags": [
    ],
  • "nova_groups_tags": [
    ],
  • "nutrient_levels_tags": [
    ],
  • "images": {
    },
  • "selected_images": { },
  • "last_image_dates_tags": [
    ],
  • "last_image_t": 0,
  • "ecoscore_data": {
    },
  • "ecoscore_extended_data_version": "string",
  • "environment_impact_level": "string",
  • "environment_impact_level_tags": [
    ],
  • "additives_tags": [
    ],
  • "allergens": "string",
  • "allergens_lc": "string",
  • "allergens_hierarchy": [
    ],
  • "allergens_tags": [
    ],
  • "ingredients": [
    ],
  • "ingredients_analysis": {
    },
  • "ingredients_analysis_tags": [
    ],
  • "ingredients_from_or_that_may_be_from_palm_oil_n": 0,
  • "ingredients_from_palm_oil_n": 0,
  • "ingredients_from_palm_oil_tags": [
    ],
  • "ingredients_hierarchy": [
    ],
  • "ingredients_n": 0,
  • "ingredients_n_tags": [
    ],
  • "ingredients_original_tags": [
    ],
  • "ingredients_percent_analysis": 0,
  • "ingredients_sweeteners_n": 0,
  • "ingredients_non_nutritive_sweeteners_n": 0,
  • "ingredients_tags": [
    ],
  • "ingredients_lc": "string",
  • "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",
  • "ingredients_that_may_be_from_palm_oil_n": 0,
  • "ingredients_that_may_be_from_palm_oil_tags": [
    ],
  • "ingredients_with_specified_percent_n": 0,
  • "ingredients_with_specified_percent_sum": 0,
  • "ingredients_with_unspecified_percent_n": 0,
  • "ingredients_with_unspecified_percent_sum": 0,
  • "known_ingredients_n": 0,
  • "origins": "string",
  • "origins_hierarchy": [
    ],
  • "origins_lc": "string",
  • "origins_tags": [
    ],
  • "traces": "string",
  • "traces_hierarchy": [
    ],
  • "traces_lc": "string",
  • "traces_tags": [
    ],
  • "unknown_ingredients_n": 0,
  • "no_nutrition_data": "on",
  • "nutrition_data_per": "serving",
  • "nutrition_data_prepared_per": "serving",
  • "nutriments": {
    },
  • "nutriscore_data": {
    },
  • "nutrition_grade_fr": "string",
  • "nutrition_grades": "string",
  • "nutrition_grades_tags": [
    ],
  • "nutrition_score_beverage": 0,
  • "nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients": 0,
  • "nutrition_score_warning_fruits_vegetables_nuts_estimate_from_ingredients_value": 0,
  • "nutrition_score_warning_no_fiber": 0,
  • "other_nutritional_substances_tags": [
    ],
  • "unknown_nutrients_tags": [
    ],
  • "vitamins_tags": [
    ],
  • "nutriscore": {
    },
  • "nutriscore_2021_tags": [
    ],
  • "nutriscore_2023_tags": [
    ],
  • "nutriscore_grade": "a",
  • "nutriscore_score": 13,
  • "nutriscore_score_opposite": -13,
  • "nutriscore_tags": [
    ],
  • "nutriscore_version": "string",
  • "data_quality_bugs_tags": [
    ],
  • "data_quality_errors_tags": [
    ],
  • "data_quality_info_tags": [
    ],
  • "data_quality_tags": [
    ],
  • "data_quality_warnings_tags": [
    ],
  • "data_sources": "string",
  • "data_sources_tags": [
    ],
  • "last_check_dates_tags": [
    ],
  • "last_checked_t": 0,
  • "last_checker": "string",
  • "states": "string",
  • "states_hierarchy": [
    ],
  • "states_tags": [
    ],
  • "misc_tags": [
    ],
  • "additives_original_tags": [
    ],
  • "additives_prev_original_tags": [
    ],
  • "added_countries_tags": [
    ],
  • "allergens_from_ingredients": "string",
  • "allergens_from_user": "string",
  • "amino_acids_prev_tags": [
    ],
  • "amino_acids_tags": [
    ],
  • "carbon_footprint_percent_of_known_ingredients": 0,
  • "categories_properties": {
    },
  • "categories_properties_tags": [
    ],
  • "category_properties": {
    },
  • "ciqual_food_name_tags": [
    ],
  • "compared_to_category": "string",
  • "conservation_conditions": "string",
  • "customer_service": "string",
  • "expiration_date": "string",
  • "link": "string",
  • "main_countries_tags": [
    ],
  • "minerals_prev_tags": [
    ],
  • "minerals_tags": [
    ],
  • "owner_fields": {
    },
  • "nova_groups_markers": {
    },
  • "nucleotides_tags": [
    ],
  • "origin": "string",
  • "purchase_places": "Paris",
  • "purchase_places_tags": [
    ],
  • "stores": "Walmart",
  • "stores_tags": [
    ],
  • "traces_from_ingredients": "string",
  • "traces_from_user": "string",
  • "created_t": 1457680652,
  • "creator": "string",
  • "editors_tags": [
    ],
  • "informers_tags": [
    ],
  • "interface_version_created": "string",
  • "interface_version_modified": "string",
  • "languages": { },
  • "languages_codes": { },
  • "languages_hierarchy": [
    ],
  • "languages_tags": [
    ],
  • "last_edit_dates_tags": [
    ],
  • "last_editor": "string",
  • "last_modified_by": "sebleouf",
  • "last_modified_t": 0,
  • "last_updated_t": 0,
  • "owner": "string",
  • "owners_tags": "string",
  • "photographers_tags": [
    ],
  • "rev": 0,
  • "sources": [
    ],
  • "sources_fields": {
    },
  • "teams": "string",
  • "teams_tags": [
    ],
  • "update_key": "string",
  • "knowledge_panels": {
    },
  • "attribute_groups": [
    ]
}

Language and country of the user

lc
string

2 letter code of the language of the interface. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the country of the user (passed through the cc field or inferred by the IP address). Full list at https://static.openfoodfacts.org/data/taxonomies/languages.json

cc
string

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request. Full list at https://static.openfoodfacts.org/data/taxonomies/countries.json

{
  • "lc": "fr",
  • "cc": "fr"
}

Fields requested and language for taxonomized tags fields

fields
string

Comma separated list of fields requested in the response. Special values: "updated": returns field that were updated by the query (e.g. sending "packagings" or "packagings_add" would return "packagings"), "none": returns no fields, "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels". Defaults to "updated" for WRITE requests, and "all" for READ requests.

tags_lc
string

2 letter language code to request names of tags in a specific language.

For READ requets: if passed, all taxonomized tags of the response will include a lc_name property with the translation in the requested language, if available. Otherwise, the property value will contain the name in the original language, prefixed by the 2 language code and a colon.

For WRITE requests: if passed, taxonomized tags fields with a lc_name property will be considered to be in this language.

{
  • "fields": "product_name,packagings",
  • "tags_lc": "fr"
}

Input taxonomy tag

string (Input taxonomy tag)

A tag entry, that will be matched against a taxonomy (e.g. a category, a label)

The entry is a string that can contain either:

  • a taxonomy entry id, in the form [2 letter language code]:[normalized canonical name] (e.g. "en:green-teas")
  • a string in a specific language, prefixed by the 2 letter language code (e.g. "fr:Thés verts")
  • API v0 to v2: a string in the language of the request (specified with the lc field, or inferred from the subdomain the request is sent to (e.g. "nl" for requests sent to be.openfoodfacts.org)
  • API v3: a string in the default language of the field (e.g. French for categories_tags_fr) or in the language indicated by the tags_lc request field (e.g. Thés verts)

All entries will be matched to the corresponding taxonomy. It is possible to specify values that do not exist yet in the taxonomy. They may later be added as new taxonomy entries, or as new translations or synonyms of an existing entry.

"string"

Tags (WRITE)

categories_tags
Array of strings (Input taxonomy tag)

An array of categories tag entries that will replace existing categories

categories_tags_add
Array of strings (Input taxonomy tag)

An array of categories tag entries that will be added to existing categories

categories_tags_(?<language_code>\w\w)
pattern property
Array of strings (Input taxonomy tag)

An array of categories tag entries that will replace existing categories, with a default language code

categories_tags_(?<language_code>\w\w)_add
pattern property
Array of strings (Input taxonomy tag)

An array of categories tag entries that will be added to existing categories, with a default language code

{
  • "categories_tags": [
    ],
  • "categories_tags_add": [
    ]
}

Packaging component shape (WRITE)

Any of
id
string

Canonical id of the entry in the taxonomy. If the value cannot be mapped to a taxonomy entry, the value must be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

{
  • "lc_name": "string",
  • "id": "string"
}

Packaging component material (WRITE)

Any of
id
string

Canonical id of the entry in the taxonomy. If the value cannot be mapped to a taxonomy entry, the value must be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

{
  • "lc_name": "string",
  • "id": "string"
}

Packaging component recycling instruction (WRITE)

Any of
id
string

Canonical id of the entry in the taxonomy. If the value cannot be mapped to a taxonomy entry, the value must be the name of the entry in its original language prefixed by the language 2 letter code and a colon.

{
  • "lc_name": "string",
  • "id": "string"
}

Packaging component (WRITE)

number_of_units
integer

Number of units of this packaging component contained in the product (e.g. 6 for a pack of 6 bottles)

shape-write (object) or shape-write (object) (shape-write)

The shape property is canonicalized using the packaging_shapes taxonomy.

material-write (object) or material-write (object) (material-write)

The material property is canonicalized using the packaging_materials taxonomy.

recycling-write (object) or recycling-write (object) (recycling-write)

The recycling property is canonicalized using the packaging_recycling taxonomy.

quantity_per_unit
string

Quantity (weight or volume) of food product contained in the packaging component. (e.g. 75cl for a wine bottle)

weight_specified
number or string

Weight (as specified by the manufacturer) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component). If passed a string - possibly with an unit - it will be converted to a number.

weight_measured
number or string

Weight (as measured by one or more users) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component). If passed a string - possibly with an unit - it will be converted to a number.

brands
string

A comma separated list of brands / product names for the packaging component (e.g. "Tetra Pak", Tetra Brik"

labels
string

A comma separated list of labels, canonicalized with the packaging_labels taxonomy (e.g. "en:FSC, fr:Encre végétale")

{
  • "number_of_units": 6,
  • "shape": {
    },
  • "material": {
    },
  • "recycling": {
    },
  • "quantity_per_unit": "25 cl",
  • "weight_measured": 10
}

Packagings (WRITE)

Array
number_of_units
integer

Number of units of this packaging component contained in the product (e.g. 6 for a pack of 6 bottles)

shape-write (object) or shape-write (object) (shape-write)

The shape property is canonicalized using the packaging_shapes taxonomy.

material-write (object) or material-write (object) (material-write)

The material property is canonicalized using the packaging_materials taxonomy.

recycling-write (object) or recycling-write (object) (recycling-write)

The recycling property is canonicalized using the packaging_recycling taxonomy.

quantity_per_unit
string

Quantity (weight or volume) of food product contained in the packaging component. (e.g. 75cl for a wine bottle)

weight_specified
number or string

Weight (as specified by the manufacturer) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component). If passed a string - possibly with an unit - it will be converted to a number.

weight_measured
number or string

Weight (as measured by one or more users) of one unit of the empty packaging component (in grams). (e.g. for a 6 pack of 1.5l water bottles, it might be 30, the weight in grams of 1 empty water bottle without its cap which is a different packaging component). If passed a string - possibly with an unit - it will be converted to a number.

brands
string

A comma separated list of brands / product names for the packaging component (e.g. "Tetra Pak", Tetra Brik"

labels
string

A comma separated list of labels, canonicalized with the packaging_labels taxonomy (e.g. "en:FSC, fr:Encre végétale")

[
  • {
    }
]

Product update API V3 (WRITE)

categories_tags
Array of strings (Input taxonomy tag)

An array of categories tag entries that will replace existing categories

categories_tags_add
Array of strings (Input taxonomy tag)

An array of categories tag entries that will be added to existing categories

Array of objects (packagings-write)

The packagings object is an array of individual packaging component objects.

The Packaging data document explains how packaging data is structured in Open Food Facts: https://openfoodfacts.github.io/openfoodfacts-server/dev/explain-packaging-data/

Array of objects (packagings-write)

The packagings object is an array of individual packaging component objects.

The Packaging data document explains how packaging data is structured in Open Food Facts: https://openfoodfacts.github.io/openfoodfacts-server/dev/explain-packaging-data/

packagings_complete
integer (packagings_complete) [ 0 .. 1 ]

Indicate if the packagings array contains all the packaging parts of the product. This field can be set by users when they enter or verify packaging data. Possible values are 0 or 1.

lang
string = 2 characters

2 letter language code of the main language of the product (the most prominent on the packaging)

quantity
string
serving_size
string
object
categories_tags_(?<language_code>\w\w)
pattern property
Array of strings (Input taxonomy tag)

An array of categories tag entries that will replace existing categories, with a default language code

categories_tags_(?<language_code>\w\w)_add
pattern property
Array of strings (Input taxonomy tag)

An array of categories tag entries that will be added to existing categories, with a default language code

{
  • "categories_tags": [
    ],
  • "categories_tags_add": [
    ],
  • "packagings": [
    ],
  • "packagings_add": [
    ],
  • "packagings_complete": 1,
  • "lang": "fr",
  • "quantity": "string",
  • "serving_size": "string",
  • "images": {
    }
}