Open Food Facts API

https://openfoodfacts.github.io/openfoodfacts-server/api
Admin
Open Food Facts API enables developers to access and contribute to a crowdsourced database of food...
Tokens:22,932
Snippets:299
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Fetch Product Data from Staging Environment

Source: https://openfoodfacts.github.io/openfoodfacts-server/api

Example of performing an authenticated GET request to the staging API using basic authentication in a browser console.

```javascript
fetch("https://world.openfoodfacts.net/api/v3.6/product/3274080005003.json", {
  method: "GET",
  headers: { Authorization: "Basic " + btoa("off:off") },
})
  .then((response) => response.json())
  .then((json) => console.log(json));
```

--------------------------------

### Example API Request

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/contributing-to-image-refresh-api

This is an example of a GET request to the API to check the French images for a specific product barcode.

```URL
https://fr.openfoodfacts.org/api/v2/produit/3483130043180?fields=images_to_update_fr
```

--------------------------------

### Get taxonomy-based suggestions (v3 API)

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Examples of querying the v3 taxonomy suggestions endpoint for synonyms, categories, and packaging materials.

```http
https://world.openfoodfacts.org/api/v3/taxonomy_suggestions?tagtype=labels&lc=fr&string=f&get_synonyms=1
```

```http
https://world.openfoodfacts.org/api/v3/taxonomy_suggestions?tagtype=categories&string=organic
```

```http
https://world.openfoodfacts.org/api/v3/taxonomy_suggestions?tagtype=packaging_materials&shape=box
```

--------------------------------

### Search Response Example

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

An example of a JSON response from the search API, showing product count and a list of matching products with selected fields.

```JSON
{
    "count": 1629,
    "page": 1,
    "page_count": 24,
    "page_size": 24,
    "products": [
        {
            "categories_tags_en": [
                "Plant-based foods and beverages",
                "Beverages",
                "Plant-based beverages",
                "Fruit-based beverages",
                "Juices and nectars",
                "Fruit juices",
                "Concentrated fruit juices",
                "Orange juices",
                "Concentrated orange juices"
            ],
            "code": "3123340008288",
            "nutrition_grades": "c"
        },
        . 
        . 
        . 
        {
            "categories_tags_en": [
                "Plant-based foods and beverages",
                "Beverages",
                "Plant-based beverages",
                "Fruit-based beverages",
                "Juices and nectars",
                "Fruit juices",
                "Non-Alcoholic beverages",
                "Orange juices",
                "Squeezed juices",
                "Squeezed orange juices"
            ],
            "code": "3608580844136",
            "nutrition_grades": "c"
        }
    ],
    "skip": 0
}

```

--------------------------------

### Example User Preferences

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/getting-personal-with-attributes

Define user preferences in your code, specifying attributes they prefer and optionally attributes they wish to avoid.

```JSON
{
  "preferred_attributes": ["nutriscore-a", "labels-organic", "ingredients-analysis-palm-oil-free"],
  "avoided_attributes": ["labels-gluten-free"]  // optional if user has no dietary constraint
}
```

--------------------------------

### Get Nutella Ferrero Product Data

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

Example of a GET request to retrieve data for a specific product using its barcode.

```http
https://world.openfoodfacts.net/api/v2/product/3017624010701
```

--------------------------------

### Sorted Search Response Example

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

An example of a JSON response sorted by the 'last_modified_t' field, showing the order of products based on their modification date.

```JSON
{
    "count": 1629,
    "page": 1,
    "page_count": 24,
    "page_size": 24,
    "products": [
        {
            "categories_tags_en": [
                "Plant-based foods and beverages",
                "Beverages",
                "Plant-based beverages",
                "Fruit-based beverages",
                "Juices and nectars",
                "Fruit juices",
                "Orange juices"
            ],
            "code": "3800014268048",
            "nutrition_grades": "c"
        },
        '
        '
        '
        {
            "categories_tags_en": [
                "Plant-based foods and beverages",
                "Beverages",
                "Plant-based beverages",
                "Fruit-based beverages",
                "Juices and nectars",
                "Fruit juices",
                "Orange juices",
                "Squeezed juices",
                "Squeezed orange juices"
            ],
            "code": "4056489641018",
            "nutrition_grades": "c"
        }
    ],
    "skip": 0
}

```

--------------------------------

### Basic Search Endpoint

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

The base URL for the product search API. Use this as the starting point for all search requests.

```HTTP
https://world.openfoodfacts.org/api/v2/search

```

--------------------------------

### Construct Full Resolution Raw Image URL

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/how-to-download-images

Example of constructing the URL for a full-resolution raw image using the product's barcode and image ID.

```url
https://images.openfoodfacts.org/images/products/316/893/001/0883/1.jpg
```

--------------------------------

### Nutri-Score Computation Response Example

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

An example JSON response containing detailed 'nutriscore_data' and 'nutriments' for calculating the Nutri-score.

```json
{
    "code": "3017624010701",
    "product": {
        "nutriments": {
            "carbohydrates": 57.5,
            "carbohydrates_100g": 57.5,
            "carbohydrates_unit": "g",
            "carbohydrates_value": 57.5,
            "energy": 2255,
            "energy-kcal": 539,
            "energy-kcal_100g": 539,
            "energy-kcal_unit": "kcal",
            "energy-kcal_value": 539,
            "energy_unit": "kJ",
            "energy_value": 2255,
            "fat": 30.9,
            "fat_100g": 30.9,
            "fat_unit": "g",
            "fat_value": 30.9,
            "proteins": 6.7,
            "proteins_100g": 6.7,
            "proteins_unit": "g",
            "proteins_value": 6.7,
            "sugars": 56.3,
            "sugars_100g": 56.3,
            "sugars_unit": "g",
            "sugars_value": 56.3
        },
        "nutriscore_data": {
            "energy": 2255,
            "energy_points": 6,
            "energy_value": 2255,
            "grade": "e",
            "grades": {
                "a": null,
                "b": null,
                "c": null,
                "d": null,
                "e": 10
            },
            "is_beverage": false,
            "negative_points": 0,
            "positive_points": 10,
            "score": "10",
            "saturated-fat": 10.6,
            "saturated-fat_points": 10,
            "saturated-fat_value": 10.6,
            "sodium": 0.01,
            "sodium_points": 0,
            "sodium_value": 0.01,
            "sugars": 56.3,
            "sugars_points": 10,
            "sugars_value": 56.3
        },
        "nutrition_grades": "e",
        "product_name": "Nutella"
    },
    "status": 1,
    "status_verbose": "product found"
}
```

--------------------------------

### Get partial taxonomy entries (v2 API)

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Examples of querying the v2 taxonomy endpoint to retrieve specific taxonomy entries with field filtering and language context.

```http
https://world.openfoodfacts.org/api/v2/taxonomy?tagtype=labels&tags=en:organic,en:fair-trade&fields=name,description,children&include_children=1&lc=en,fr
```

```http
https://world.openfoodfacts.org/api/v2/taxonomy?tagtype=categories&tags=en:carrot-juices&fields=name,parents,children,wikidata,auth_url&lc=en,fr&cc=fr
```

--------------------------------

### Search with Filters

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

Filter products by category and nutrition grade. This example searches for 'Orange Juice' with a nutrition grade of 'c'.

```HTTP
https://world.openfoodfacts.net/api/v2/search?categories_tags_en=Orange Juice&nutrition_grades_tags=c

```

--------------------------------

### User-Agent Header Example

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/finding-healthy-cereals

A User-Agent header is required for API calls. It identifies your application to prevent accidental blocking.

```text
User-Agent: HealthyFoodChoices - Android - Version 1.0
```

--------------------------------

### Construct Lower Resolution Raw Image URL

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/how-to-download-images

Example of constructing the URL for a lower-resolution raw image (e.g., 400px) using the product's barcode and image ID.

```url
https://images.openfoodfacts.org/images/products/316/893/001/0883/1.400.jpg
```

--------------------------------

### Nutri-Score Response Example

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

A sample JSON response from the API, showing product name and Nutri-score. The 'status' field indicates if the product was found.

```json
{
    "code": "3017624010701",
    "product": {
        "nutrition_grades": "e",
        "product_name": "Nutella"
    },
    "status": 1,
    "status_verbose": "product found"
}
```

--------------------------------

### Get Product Data with Specific Fields

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

This request uses query parameters to limit the response to only 'product_name' and 'nutriscore_data'. This is useful for fetching only the necessary information.

```http
https://world.openfoodfacts.net/api/v2/product/3017624010701?fields=product_name,nutriscore_data
```

--------------------------------

### GET /api/v3.6/product/{barcode}.json

Source: https://openfoodfacts.github.io/openfoodfacts-server/api

Retrieves product information by barcode. This is a read operation requiring a custom User-Agent.

```APIDOC
## GET /api/v3.6/product/{barcode}.json

### Description
Retrieves product details for a specific barcode.

### Method
GET

### Endpoint
https://world.openfoodfacts.org/api/v3.6/product/{barcode}.json

### Parameters
#### Path Parameters
- **barcode** (string) - Required - The barcode of the product to retrieve.

### Request Example
GET https://world.openfoodfacts.org/api/v3.6/product/3274080005003.json

### Response
#### Success Response (200)
- **product** (object) - The product data object.
```

--------------------------------

### Successful Product Image Upload Response

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-uploading-photo-to-a-product

This is an example of a successful JSON response after uploading a product image. It includes details about the saved fields and the new image ID.

```json
{
  "files": [
    {
      "url": "/product/0180411000803/100%-real-orange-juice",
      "filename": "",
      "name": "100% Real Orange Juice",
      "thumbnailUrl": "/images/products/018/041/100/0803.jpg",
      "code": "0180411000803"
    }
  ],
  "image": {
    "thumb_url": "123.100.jpg",
    "imgid": 123,
    "crop_url": "123.400.jpg"
  },
  "imgid": 123,
  "status": "status ok",
  "imagefield": "ingredients_en",
  "code": "0180411000803"
}

```

--------------------------------

### Get Product Barcode Endpoint

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

This is the base endpoint for retrieving product information by barcode. Replace {barcode} with the actual product's barcode.

```http
https://world.openfoodfacts.net/api/v2/product/{barcode}
```

--------------------------------

### GET /api/v2/product/{barcode}.json

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Retrieves product information by barcode with options to include modification history or filter specific response fields.

```APIDOC
## GET /api/v2/product/{barcode}.json

### Description
Retrieves product data in JSON format. Supports optional parameters to include modification history (blame) or limit the returned fields.

### Method
GET

### Endpoint
https://world.openfoodfacts.org/api/v2/product/{barcode}.json

### Parameters
#### Path Parameters
- **barcode** (string) - Required - The unique barcode of the product.

#### Query Parameters
- **blame** (integer) - Optional - Set to 1 to include modification history (userid, timestamp, revision, value) for each field.
- **fields** (string) - Optional - Comma-separated list of specific fields to return (e.g., product_name,brands,nutriments).

### Response
#### Success Response (200)
- **product** (object) - The product data object containing requested fields and optional blame metadata.
```

--------------------------------

### Get Product Data with Nutri-Score Computation Details

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

This request includes additional fields like 'nutriscore_data' and 'nutriments' to provide details on how the Nutri-score is computed.

```http
https://world.openfoodfacts.net/api/v2/product/3017624010701?fields=product_name,nutriscore_data,nutriments,nutrition_grades
```

--------------------------------

### Product Attributes API Response

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/explain-product-attributes

Example response from the Open Food Facts API showing product details including attribute groups and individual attributes with their match scores.

```json
{
    "status": 1,
    "code": "3700214614266",
    "status_verbose": "product found",
    "product": {
        "product_name": "Chocolat noir Pérou 90% fruité et boisé",
        "code": "3700214614266",
        "attribute_groups_en": [
            {
                "attributes": [
                    {
                        "status": "known",
                        "name": "Nutri-Score",
                        "match": 30,
                        "id": "nutriscore",
                        "title": "Nutri-Score D",
                        "description": "",
                        "description_short": "Poor nutritional quality"
                    }
                ],
                "name": "Nutritional quality",
                "id": "nutritional_quality"
            },
            {
                "id": "processing",
                "name": "Food processing",
                "attributes": [
                    {
                        "id": "nova",
                        "match": 50,
                        "name": "NOVA group",
                        "status": "known",
                        "description_short": "Processed foods",
                        "description": "",
                        "title": "NOVA 3"
                    }
                ]
            },
            {
                "id": "labels",
                "name": "Labels",
                "attributes": [
                    {
                        "title": "Organic product",
                        "description_short": "Promotes ecological sustainability and biodiversity.",
                        "description": "Organic farming aims to protect the environment and to conserve biodiversity by prohibiting or limiting the use of synthetic fertilizers, pesticides and food additives.",
                        "name": "Organic farming",
                        "match": 100,
                        "status": "known",
                        "id": "labels_organic"
                    },
                    {
                        "id": "labels_fair_trade",
                        "match": 100,
                        "name": "Fair trade",
                        "status": "known",
                        "description_short": "Fair trade products help producers in developing countries.",
                        "description": "When you buy fair trade products, producers in developing countries are paid a higher and fairer price, which helps them improve and sustain higher social and often environmental standards.",
                        "title": "Fair trade product"
                    }
                ]
            }
        ]
    }
}
```

--------------------------------

### Fetch Green-Score via Raw API v0

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/get-the-green-score

Example request to the Open Food Facts v0 API to retrieve the ecoscore_grade field.

```http
https://world.openfoodfacts.org/api/v0/product/3414280980209.json?fields=ecoscore_grade
```

--------------------------------

### Get Product Details

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

Retrieve detailed information about a specific product, including its name, nutriscore data, and nutriment information. This is useful for verifying updates or checking computed scores.

```APIDOC
## GET /api/v2/product/{code}

### Description
Retrieves detailed information for a specific product, including its name, nutriscore data, and nutriment information.

### Method
GET

### Endpoint
https://world.openfoodfacts.net/api/v2/product/{code}

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response. Example: `product_name,nutriscore_data,nutriments,nutrition_grades`

### Request Example
```
https://world.openfoodfacts.net/api/v2/product/0180411000803?fields=product_name,nutriscore_data,nutriments,nutrition_grades
```

### Response
#### Success Response (200)
- **code** (string) - The product's barcode.
- **product** (object) - Contains product details including:
  - **product_name** (string) - The name of the product.
  - **nutriments** (object) - Nutritional information.
  - **nutriscore_data** (object) - Data related to the Nutri-Score computation.
  - **nutrition_grades** (string) - The computed nutrition grade (e.g., 'c').
- **status** (integer) - Indicates the success status of the operation.
- **status_verbose** (string) - A verbose description of the status.

#### Response Example
```json
{
    "code": "0180411000803",
    "product": {
        "nutriments": {
            "carbohydrates": 11.864406779661,
            "sugars_unit": "g",
            "sugars_value": 11.864406779661
        },
        "nutriscore_data": {
            "energy": 195,
            "energy_points": 7,
            "energy_value": 195,
            "sugars_value": 11.86
        },
        "nutrition_grades": "c",
        "product_name": "100% Real Orange Juice"
    },
    "status": 1,
    "status_verbose": "product found"
}
```
```

--------------------------------

### Upload Product Image using curl

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-uploading-photo-to-a-product

Use this curl command to upload a product image. Ensure you replace placeholders with your actual user ID, password, and provide the correct file path.

```bash
curl -XPOST https://world.openfoodfacts.net/cgi/product_image_upload.pl \
  -F user_id=your_user_id -F password=your_password \
  -F code=0180411000803 -F imagefield=ingredients_en -F imgupload_ingredients_en=@images/real-orange-juice-ingredients.jpg

```

--------------------------------

### Sample API Response

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/contributing-to-image-refresh-api

The API response contains a 'product' object with an 'images_to_update_[lang]' field. The values indicate the status of each image type.

```JSON
{
  "product": {
    "images_to_update_fr": {
      "packaging_fr": 0,
      "front_fr": 83734290,
      "ingredients_fr": 83734290
    }
  }
}
```

--------------------------------

### Retrieve field suggestions via suggest.pl

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Use these URLs to fetch taxonomized values for various product attributes like brands, categories, and ingredients.

```text
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=emb_codes&term=FR
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=categories&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=labels&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=ingredients&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=packaging_shapes&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=packaging_materials&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=packaging_shapes&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=languages&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=stores&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=brands&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=countries&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=traces&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=origins&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=states&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=nutrients&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=additives&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=allergens&term=f
https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=minerals&term=f
```

--------------------------------

### GET /api/v2/taxonomy

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Retrieves selected taxonomy entries based on specified tags and fields.

```APIDOC
## GET /api/v2/taxonomy

### Description
Use this endpoint to retrieve selected taxonomy entries instead of downloading the full taxonomy.

### Method
GET

### Endpoint
/api/v2/taxonomy

### Query Parameters
- **tagtype** (string) - Required - The taxonomy to query (e.g., categories, labels, ingredients)
- **tags** (string) - Optional - Comma-separated list of taxonomy tags or IDs
- **fields** (string) - Optional - Comma-separated list of fields to return
- **include_children** (integer) - Optional - Set to 1 to include children entries
- **include_parents** (integer) - Optional - Set to 1 to include parent entries
- **include_root_entries** (integer) - Optional - Set to 1 to include root entries
- **lc** (string) - Optional - Comma-separated language codes
- **cc** (string) - Optional - Country context
```

--------------------------------

### GET /api/v3/taxonomy_suggestions

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Retrieves suggestions based on taxonomy fields such as synonyms, categories, and packaging shapes.

```APIDOC
## GET /api/v3/taxonomy_suggestions

### Description
Retrieves suggestions based on taxonomy fields like synonyms, categories, and packaging shapes.

### Method
GET

### Endpoint
/api/v3/taxonomy_suggestions

### Query Parameters
- **tagtype** (string) - Required - The taxonomy to query (e.g., labels, categories, packaging_materials)
- **lc** (string) - Optional - Language code
- **string** (string) - Optional - Search string for suggestions
- **get_synonyms** (integer) - Optional - Set to 1 to include synonyms
- **shape** (string) - Optional - Packaging shape filter
```

--------------------------------

### Setting a Proper User-Agent

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/scanning-barcodes

It is essential to set a proper User-Agent header for API etiquette. Use the specified format including your app name, platform, version, and a contact URL.

```text
User-Agent: MyAppName - Android - Version 2.1 - https://example.com - scan
```

--------------------------------

### Filter and Download Sample Images

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/aws-images-dataset

Extract a random sample of images from the dataset by filtering the data keys file and downloading selected images.

```bash
# Extract images from AWS
n=1000
images_dir="images"
bucket_url="https://openfoodfacts-images.s3.eu-west-3.amazonaws.com/"

zcat data_keys.gz |
grep '.jpg' | # Filter
shuf -n "$n" | # Random sample
sed "s|^|$bucket_url|" | #Add bucket_url: "https://openfoodfacts-images.s3.eu-west-3.amazonaws.com/data/376/005/047/0099/1.jpg"
while read -r url; do
    filename=$(echo "$url" | sed "s|$bucket_url||" | tr '/' '_' | sed 's|data_||') # Filename as 376_005_047_0099_1.jpg
    wget -O "$images_dir/$filename" "$url"
done

```

--------------------------------

### Generate Open Food Facts Image URL (Python)

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/how-to-download-images

Use this Python function to generate the correct URL for a product image. It handles both raw and selected images, different resolutions, and constructs the product folder path based on the product code.

```python
def get_image_url(product_data, image_name, resolution="full"):
    if image_name not in product_data["images"]:
        return None
    base_url = "https://images.openfoodfacts.org/images/products"
    # get product folder name
    folder_name = product_data["code"]
    if len(folder_name) > 8:
        folder_name = re.sub(r'(...)(...)(...)(.*)', r'\1/\2/\3/\4', folder_name)
    # get filename
    if re.match("^\d+$", image_name):  # only digits
        # raw image
        resolution_suffix = "" if resolution == "full" else f".{resolution}"
        filename = f"{image_name}{resolution_suffix}.jpg"
    else:
        # selected image
        rev = product_data["images"][image_name]["rev"]
        filename = f"{image_name}.{rev}.{resolution}.jpg"
    # join things together
    return f"{base_url}/{folder_name}/{filename}"

```

--------------------------------

### Fetch Green-Score via Raw API v3

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/get-the-green-score

Example request to the Open Food Facts v3 API to retrieve the environmental_score_grade field.

```http
https://world.openfoodfacts.org/api/v3/product/3414280980209.json?fields=environmental_score_grade
```

--------------------------------

### Fetch Product with Attributes

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/getting-personal-with-attributes

Retrieve a specific product's details, including its associated attribute groups. Use the 'fields' parameter to specify 'attribute_groups' for inclusion.

```HTTP
GET https://world.openfoodfacts.org/api/v2/product/3700214614266?fields=product_name,code,attribute_groups
```

--------------------------------

### Retrieve product data with blame information

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Include the blame parameter to receive metadata about the last modification of each field.

```url
https://world.openfoodfacts.org/api/v2/product/3017620422003.json?blame=1
```

--------------------------------

### Add or Edit A Product

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

This endpoint allows you to add or edit product information. It requires authentication with user_id and password. You can provide various product details, including nutriment data and categories, to update existing products or add new ones.

```APIDOC
## POST /cgi/product_jqm2.pl

### Description
Allows adding or editing product information, including nutriment data and categories. Requires authentication.

### Method
POST

### Endpoint
https://world.openfoodfacts.net/cgi/product_jqm2.pl

### Parameters
#### Request Body
- **user_id** (string) - Required - A valid user_id for authentication.
- **password** (string) - Required - A valid password for authentication.
- **code** (string) - Required - The barcode of the product to be added/edited.
- **nutriment_sodium** (string) - Optional - Amount of sodium.
- **nutriment_sodium_unit** (string) - Optional - Unit of sodium relative to the amount.
- **categories** (string) - Optional - Category of the Product.

### Request Example
```json
{
  "user_id": "your_user_id",
  "password": "your_password",
  "code": "0180411000803",
  "nutriment_sodium": "0.015",
  "nutriment_sodium_unit": "g",
  "categories": "Orange Juice"
}
```

### Response
#### Success Response (200)
- **status_verbose** (string) - Indicates that the fields have been saved.
- **status** (integer) - Indicates the success status of the operation.

#### Response Example
```json
{
    "status_verbose": "fields saved",
    "status": 1
}
```
```

--------------------------------

### Accessing Wikidata QID in API Output

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/leveraging-links-to-wikidata

Example of a JSON response from the Open Food Facts facets API showing the linkeddata field containing a Wikidata QID.

```json
{
  "linkeddata": { "wikidata:en": "Q40050" },
  "url": "https://world.openfoodfacts.net/facets/categories/beverages",
  "name": "Beverages",
  "id": "en:beverages",
  "products": 14196
}
```

--------------------------------

### Download Image using wget

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/aws-images-dataset

Directly download a specific image from the S3 bucket using wget.

```bash
wget https://openfoodfacts-images.s3.eu-west-3.amazonaws.com/data/401/235/911/4303/1.jpg
```

--------------------------------

### Get Missing Tags for Nutri-Score Computation

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

Retrieve the `misc_tags` field for a product to identify missing data required for Nutri-Score computation. This helps in understanding what data needs to be provided.

```APIDOC
## GET /api/v2/product/{code}

### Description
Retrieves the `misc_tags` field for a product, which indicates missing data required for Nutri-Score computation.

### Method
GET

### Endpoint
https://world.openfoodfacts.net/api/v2/product/{code}

### Parameters
#### Query Parameters
- **fields** (string) - Required - Specify `misc_tags` to retrieve this specific field. Example: `misc_tags`

### Request Example
```
https://world.openfoodfacts.net/api/v2/product/0180411000803?fields=misc_tags
```

### Response
#### Success Response (200)
- **code** (string) - The product's barcode.
- **product** (object) - Contains product details:
  - **misc_tags** (array) - A list of tags indicating missing data or computation status (e.g., `en:nutriscore-missing-category`, `en:nutriscore-missing-nutrition-data-sodium`).
- **status** (integer) - Indicates the success status of the operation.
- **status_verbose** (string) - A verbose description of the status.

#### Response Example
```json
{
    "code": "0180411000803",
    "product": {
        "misc_tags": [
            "en:nutriscore-not-computed",
            "en:nutriscore-missing-category",
            "en:nutrition-not-enough-data-to-compute-nutrition-score",
            "en:nutriscore-missing-nutrition-data",
            "en:nutriscore-missing-nutrition-data-sodium",
            "en:ecoscore-extended-data-not-computed",
            "en:ecoscore-not-computed",
            "en:main-countries-new-product"
        ]
    },
    "status": 1,
    "status_verbose": "product found"
}
```
```

--------------------------------

### Fetch Multiple Products with Attributes

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/getting-personal-with-attributes

Efficiently fetch multiple products by their codes and include their attribute groups. This is useful for batch processing and applying matching algorithms to a list of products.

```HTTP
GET https://world.openfoodfacts.org/api/v2/search?code=3700214614266,3274080005003,3017620429484&fields=product_name,code,attribute_groups
```

--------------------------------

### Download Data Keys File

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/aws-images-dataset

Download the gzipped text file containing all object keys in the S3 bucket.

```bash
wget https://openfoodfacts-images.s3.eu-west-3.amazonaws.com/data/data_keys.gz
```

--------------------------------

### Filter Data Keys for 400px Images

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/aws-images-dataset

Use zcat and grep to filter the data keys file and list only the 400px versions of all images.

```bash
zcat data_keys.gz | grep '.400.jpg'
```

--------------------------------

### Check Product Status for Ingredient Completion

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/get-ingredient-related-analysis

Logic for determining which prompts to display to the user based on missing product information.

```text
if ( 
status= category-to-be-completed && 
status = ingredients-to-be-completed 
)
then "Add ingredients and a category to see the level of food processing and potential additives"

if ( 
status= category-to-be-completed
)
then "Add a category to see the level of food processing and potential additives"

if ( 
status = ingredients-to-be-completed 
)
then "Add ingredients to see the level of food processing and potential additives"
```

--------------------------------

### List and descriptions of available product attributes

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/explain-product-attributes

Retrieve a list of all available product attribute groups and their associated attributes. This endpoint provides machine-readable data and internationalized human-friendly data for various product characteristics.

```APIDOC
## GET /api/v3.4/attribute_groups

### Description
Fetches a list of all available product attribute groups and their attributes for API v3.4 and later.

### Method
GET

### Endpoint
/api/v3.4/attribute_groups

### Parameters
None

### Response
#### Success Response (200)
Returns a JSON array of attribute groups. Each group contains an `id`, `name`, optional `warning`, and an `attributes` array.
Each attribute in the `attributes` array contains an `id`, `name`, `setting_name`, optional `setting_note`, and optional `parameters`.

#### Response Example
```json
[
  {
    "id": "nutritional_quality",
    "name": "Nutritional quality",
    "attributes": [
      {
        "id": "nutriscore",
        "name": "Nutri-Score",
        "setting_name": "Good nutritional quality (Nutri-Score)"
      }
    ]
  }
]
```

## GET /api/v2/attribute_groups

### Description
Fetches a list of all available product attribute groups and their attributes for API v2.

### Method
GET

### Endpoint
/api/v2/attribute_groups

### Parameters
None

### Response
#### Success Response (200)
Returns a JSON array of attribute groups. The structure is similar to API v3.4 but may not support attributes with parameters.

## GET /api/v2/attribute_groups_[language code]

### Description
Fetches a list of all available product attribute groups and their attributes for API v2, localized to a specific language.

### Method
GET

### Endpoint
/api/v2/attribute_groups_[language code]

### Parameters
- **language code** (string) - Required - The ISO 639-1 code for the desired language (e.g., 'en', 'fr').

### Response
#### Success Response (200)
Returns a JSON array of attribute groups localized to the specified language. The structure is similar to API v2.

### Note
API versions prior to 3.4 do not support product attributes with parameters.
```

--------------------------------

### POST /cgi/product_jqm2.pl

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/adding-missing-products

Updates product information for a specific barcode. Supports authentication and additive updates for fields.

```APIDOC
## POST /cgi/product_jqm2.pl

### Description
Updates product information for a specific barcode. Use the 'add_' prefix for parameters to append data rather than overwriting existing values.

### Method
POST

### Endpoint
https://us.openfoodfacts.org/cgi/product_jqm2.pl

### Query Parameters
- **code** (string) - Required - The barcode of the product.
- **user_id** (string) - Required - The identifier of the user from your system.
- **password** (string) - Required - The user's password.
- **brands** (string) - Optional - Sets the brands for the product (overwrites existing).
- **labels** (string) - Optional - Sets the labels for the product (overwrites existing).
- **add_brands** (string) - Optional - Appends brands to the product.
- **add_labels** (string) - Optional - Appends labels to the product.
- **add_categories** (string) - Optional - Appends categories to the product.
- **comment** (string) - Optional - A comment identifying the user agent and system-generated user ID.
```

--------------------------------

### Client-Side Logic for Button Text

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/contributing-to-image-refresh-api

This pseudo-code demonstrates how to parse the API response to determine whether to prompt the user to 'Take' a new picture (if missing) or 'Refresh' an old one.

```Pseudocode
// Assume 'images_to_update' is the object from the API response
// e.g., { packaging_fr: 0, front_fr: 83734290 }

for (key, value) in images_to_update:
    // 1. Determine the action (verb)
    let verb = ""
    if value == 0:
        verb = "Take"  // Image is missing
    else:
        verb = "Refresh" // Image is old

    // 2. Get the field name and language
    // e.g., "front_fr" -> ["front", "fr"]
    let parts = key.split("_")
    let field_name = parts[0]
    let field_language = parts[1] // Useful for localization

    // 3. Create the button text
    // You would use localized strings in a real app
    let button_text = `${verb} ${field_name} picture`

    // Now, create a button with this text.
    // e.g., "Refresh front picture", "Take packaging picture"

```

--------------------------------

### Perform bulk product search with field filtering

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref-cheatsheet

Query multiple product codes simultaneously and restrict the returned data fields using the fields parameter.

```text
https://world.openfoodfacts.org/api/v2/search?code=3263859883713,8437011606013,6111069000451&fields=code,product_name
```

--------------------------------

### Fruits/nuts missing disclaimer

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/get-the-nutriscore

Warning message for when fruits, vegetables, and nuts content is not specified.

```gettext
msgctxt "nutrition_grade_fr_no_fruits_vegetables_nuts_warning"
msgid "Warning: the amount of fruits, vegetables and nuts is not specified, their possible positive contribution to the grade could not be taken into account."
```

--------------------------------

### Product Images V3 Schema

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/ref/schemas/product_images_v3.yaml

This schema defines the structure for product images, including uploaded and selected images, their URLs, and metadata.

```APIDOC
## Product Images V3 Schema

### Description
Information about images (photos) of a product. Images ensure the reliability of Open Food Facts data and provide a primary source and proof of all the structured data. They may therefore be displayed along the structured information.

For each product, we store:
- the original images uploaded by users or manufacturers in `images.uploaded`
- images that have been selected / cropped / rotated etc. containing specific information (e.g. the front image, the ingredients image, etc.) for specific languages in `images.selected`.

See also tutorials about images:
* [Getting images](https://openfoodfacts.github.io/openfoodfacts-server/api/how-to-download-images/)
* [Uploading images](https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-uploading-photo-to-a-product/)

### Properties

*   **images** (object) - Uploaded and selected images of the product.
    *   **uploaded** (object) - List of all images uploaded by users or manufacturers. These images are typically not displayed to users but are used in edit mode to crop images with specific information for specific languages. Older uploaded images that may correspond to older revisions of the product are also kept in this list.
        *   `{imgid}` (object) - Represents an uploaded image.
    *   **selected** (object) - List of all images selected by users or manufacturers. These images are typically displayed to users and are used in edit mode to crop images with specific information for specific languages.

*   **selected_images** (object) - URLs of selected images, generated at runtime.
    *   `{image_type}` (object) - Type of the selected image: front, ingredients, nutrition, packaging.
        *   `{language_code}` (object) - URL of the selected image for a specific language. 'best' returns the best image available.
            *   **100** (string) - The URL of the image in max 100px width and height.
            *   **200** (string) - The URL of the image in max 200px width and height.
            *   **400** (string) - The URL of the image in max 400px width and height.

*   **last_image_dates_tags** (array of strings) - An array of tags entries to indicate 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.
```

--------------------------------

### Add or Edit Product Data via API (cURL)

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorial-off-api

Use a cURL command to send a POST request to the Open Food Facts API to add or edit product data. This is necessary for providing missing information like sodium and category to enable Nutri-Score computation.

```bash
curl -XPOST -x POST https://world.openfoodfacts.net/cgi/product_jqm2.pl \
  -F user_id=your_user_id -F password=your_password \
  -F code=0180411000803 -F nutriment_sodium=0.015 -F nutriment_sodium_unit=g -F categories="Orange Juice"
```

--------------------------------

### API Endpoint Structure

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/contributing-to-image-refresh-api

Use this URL structure to request image status for a product. Specify the product barcode and the desired language code in the fields parameter.

```URL
https://{world|fr|...}.openfoodfacts.org/api/v2/product/[BARCODE]?fields=images_to_update_[LANG]
```

--------------------------------

### Compute Product Image Folder from Barcode

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/how-to-download-images

This regex can be used to split a barcode into subfolders for constructing image URLs. Ensure the barcode is padded to 13 digits first.

```regex
/^(...)(...)(...)(.*)$/
```

--------------------------------

### Raw API v3 JSON Response

Source: https://openfoodfacts.github.io/openfoodfacts-server/api/tutorials/get-the-green-score

Sample JSON response structure returned by the v3 API for a product query.

```json
{"status_verbose":"product found","product":{"ecoscore_grade":"b"},"status":1,"code":"3414280980209"}
```
Tokens:
Raw