Introduction to the Open Food Facts API documentation

Reference: API CheatSheet

GitHubOpen in GitHub

This reference cheatsheet gives you a quick reminder to send requests to the OFF API.

If you are new to API usage you might look at the tutorial. Also, refer to the API reference documentation for complete information.

Add/Edit an Existing Product

Indicate the absence of nutrition facts

Indicate the absence of nutrition facts
no_nutrition_data=on (indicates if the nutrition facts are not indicated on the food label)

Add nutrition facts values, units and base

Add nutrition facts values, units and base
nutrition_data_per=100g

OR

nutrition_data_per=serving
serving_size=38g
Add nutrition facts values, units and base
nutriment_energy=450
nutriment_energy_unit=kJ

Adding values to a field that is already filled

You just have to prefix add_ before the name of the field

Adding values to a field that is already filled
add_categories
add_labels
add_brands

Adding nutrition facts for the prepared product

You can send prepared nutritional values

  • nutriment_energy-kj (regular)
  • nutriment_energy-kj_prepared (prepared)

Read Product Data

Get product with blame information

To get information about who last modified each field of a product, add the blame parameter:

Get product with blame information
https://world.openfoodfacts.org/api/v2/product/3017620422003.json?blame=1

This returns additional blame information showing:

  • userid: Who last modified each field
  • t: Timestamp of the modification
  • rev: Revision number
  • value: Current value of the field

Limit response fields

Use the fields parameter to get only specific product data:

Limit response fields
https://world.openfoodfacts.org/api/v2/product/3017620422003.json?fields=product_name,brands,nutriments

Search for Products

Structured (filter-based) search — API v2

Structured search by tags, nutrients, categories, brands, and other fields is available via the /api/v2/search endpoint:

Note: /api/v3/search is not yet implemented.

Full-text / plain-text search

Full-text search is not available in the v2 or v3 server-side API.

For full-text search, we are building Search-a-licious, which will be deployed at search.openfoodfacts.org. Search-a-licious will have a dedicated API: Search-a-licious API documentation.

The legacy v1 search endpoint (/cgi/search.pl) supports keyword search but is not recommended for new integrations.

Get suggestions for fields

New solution: Search-a-licious (has all actually used values)

Get brands, categories, labels… suggestions using the Search-a-licious API. You can also use the classic suggest.pl route

Legacy solution: suggest.pl (has all taxonomized values, and only taxonomized values)

Get data for a list of products

You can use comma to separate multiple values of a query parameter. This allows you to make bulk requests. The product result can also be limited to specified data using fields.

Get data for a list of products
https://world.openfoodfacts.org/api/v2/search?code=3263859883713,8437011606013,6111069000451&fields=code,product_name

Get taxonomy-based suggestions (v3 API)

The v3 API provides suggestions based on taxonomy fields such as synonyms, categories, and packaging shapes.

Reference documentation:

https://openfoodfacts.github.io/openfoodfacts-server/api/ref-v3/#get-/api/v3/taxonomy_suggestions

Example requests:

Get suggestions from synonyms

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

Get suggestions for a specific category

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

Get suggestions based on packaging shape

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

Get partial taxonomy entries (v2 API)

Use /api/v2/taxonomy when you want selected taxonomy entries only (instead of downloading a full taxonomy).

Common parameters

  • tagtype: taxonomy to query (categories, labels, ingredients, etc.)
  • tags: comma-separated list of taxonomy tags/ids
  • fields: comma-separated list of fields to return (for example: name,description,children,parents,wikidata)
  • include_children=1: include children entries in the response
  • include_parents=1: include parent entries in the response
  • include_root_entries=1: include root taxonomy entries in the response
  • lc: language(s), comma-separated (for example: en,fr)
  • cc: optional country context

Example requests

Example requests
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
Example requests
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

Reference: Barcode Normalization

Previous Page

How to download product images

Next Page