diff --git a/index.html b/index.html index f571118..69eb97c 100644 --- a/index.html +++ b/index.html @@ -1,14 +1,19 @@ Open Food Facts API Documentation

Open Food Facts API Documentation

1. General Information -2

As a developer, the Open Food Facts API allows you to get information about existing products and contribute to the products database.

Using the API, you can create apps to help people make better food choices and also provide data to enhance the database.

Check out how others are making use of the API at https://world.openfoodfacts.org/discover#reuses.

Data Disclaimer

The data contained in the Open Food Facts database are collected by users willing to selflessly contribute to the Open Food Facts initiative.

Therefore, no guarantees can be made for the accuracy, completeness, or reliability of the information provided. The user assumes the entire risk related to the use of data. You (or your users) are very welcome to provide fixes using the WRITE API.

Usage

You can use the Open Food Facts API for production use cases, as long as 1 API call equals 1 real scan by a user.

Do you know that we have ready-made SDKs for many programming languages ?

Domains

You can either use the global domain (https://world.openfoodfacts.org) or the local domains (https://fr.openfoodfacts.org, https://en.openfoodfacts.org …) for your API queries.

Endpoint

The Open Food Facts base API endpoint is https://world.openfoodfacts.org/api/2

Version

The current version of the API is 2 .

Authentication

READ and SEARCH operations

No authentication is required.

Add a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.

For example: User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com

WRITE operations

No authentication is required for adding new products or adding images.

Basic authentication is required for editing existing products. You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site.

See: 1.2 Authentication

Environments

You can do READ / SEARCH operations on the prod environment running @ https://world.openfoodfacts.org.

You can do WRITE operations tests on the dev environment running @ https://world.openfoodfacts.net (user:off, password:off).

Security

Use the SSL version of the API: https://world.openfoodfacts.org

Error Codes

  • Product does not exist - HTTP code 200 + “status_verbose” : “product not found” + “Status” : 0.
    The request format is correct, but the product code does not exist in the database.
  • Wrong Password - HTTP code 200 + an HTML page with a link to log in.
    The request format is correct, but basic authentication is missing or the password entered is not correct.
  • Server down - HTTP codes 502/503/500
  • Redirect to another product - HTTP code 301

Disclaimer: The HTML code 404 is never thrown, even when a wrong password is entered. A feature request has been created and we are already working to fix this.

Rate limit

The API intended use is for apps, with one real user scan = one query. Automated queries are not supported. Please let us know in advance if you expect a high volume of calls.

For more information, see: https://world.openfoodfacts.org/data

Cache

Some queries (facets) are caches. Should you need to disable the cache, you can pass the nocache=1 parameter.

Payload size reduction

Using the fields= parameter, you can reduce the response to only the fields you need.

Preliminary Considerations

The API development is in progress. This has several implications:

  • Open Food Facts and food products are constantly evolving.
  • Assume that data is less reliable until the product is marked as complete. You might want to filter incomplete products to avoid issues (this is especially relevant for allergens or food intolerances). Let your end users know about this and encourage them to exercise caution. Be upfront about possible risks. You can use the following template to inform your users: The data provided to you by this app are retrieved from the Open Food Facts database. No guarantees can be made for the accuracy, completeness, or reliability of the information provided. The data are provided “as is” and the originating source for the data (Open Food Facts) is not liable for any damages arising out of the use of the data.
  • Join our Slack Channel (https://slack-ssl-openfoodfacts.herokuapp.com) to get help, to share your thoughts, to let us know what you build with the API (contact@openfoodfacts.org or in the #API channel) or if you want to use WRITE operations.
  • You can also join the mailing list to be notified when improvements or changes are made to the API (we send only relevant information and very few e-mails. Don’t worry, you won’t be spammed). To join the mailing list, send an empty e-mail to api-subscribe@openfoodfacts.org to subscribe.

License

  • Do not send copyrighted photos or information using the API. Everything you send is OdBL for the data (https://opendatacommons.org/licenses/odbl/summary/index.html) and CC-BY-SA for the pictures (https://creativecommons.org/licenses/by-sa/4.0/). If you don’t own the data, you bear all the legal consequences.
  • Mention Open Food Facts as the source of the data.
  • Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk).
  • Share any additions under the OdBL with the community.
  • By using any part of the API you have read and understood the license.

API Conventions

  • Fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
  • Fields that end with _datetime are dates in the ISO8601 format: yyyy-mm-ddThh:mn:ssZ
  • Fields that end with _tags are comma-separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)
  • Fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language
  • Fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product

Bugs

Do not hesitate to file a bug if you find an issue in the API or need an improvement.
You can fill out the issue report on GitHub:

Downloading Data

It is recommended to use the live API to get updated data about products. However, in some cases, you may need a snapshot.
They are available at:

  • https://world.openfoodfacts.org/data (all data)
  • https://[countrycode].openfoodfacts.org/data (data for a specific country). -Example: https://us.openfoodfacts.org/data - (See the list of countries in the Countries taxonomy)

Exporting Data

  • File Encoding: The file encoding is Unicode UTF-8.
  • CSV API: The character that separates fields is < tab > (tabulation).
  • JSON

API Roadmap

API Redesign: The API is far from perfect. It’s been decided to fix the most urgent bugs and start planning for a new version, more compliant with modern API standards. We need all the help we can get. Please join us on the #api Slack channel.

  • Project API: Additives
  • Project API: States
  • Project API: Statistics
  • Project API: Statistics Entry Dates

Other Projects

  • Open Pet Food Facts
  • Open Beauty Facts
  • Open Products Facts

More topics

1.2 Authentication  |  +2

As a developer, the Open Food Facts API allows you to get information about existing products and contribute to the products database.

Using the API, you can create apps to help people make better food choices and also provide data to enhance the database.

Check out how others are making use of the API at https://world.openfoodfacts.org/discover#reuses.

Data Disclaimer

The data contained in the Open Food Facts database are collected by users willing to selflessly contribute to the Open Food Facts initiative.

Therefore, no guarantees can be made for the accuracy, completeness, or reliability of the information provided. The user assumes the entire risk related to the use of data. You (or your users) are very welcome to provide fixes using the WRITE API.

Usage

You can use the Open Food Facts API for production use cases, as long as 1 API call equals 1 real scan by a user.

Do you know that we have ready-made SDKs for many programming languages ?

Domains

You can either use the global domain (https://world.openfoodfacts.net) or the local domains (https://fr.openfoodfacts.net, https://en.openfoodfacts.net …) for your API queries.

Endpoint

The Open Food Facts base API endpoint is https://world.openfoodfacts.net/api/2

Version

The current version of the API is 2 .

Authentication

READ and SEARCH operations

No authentication is required.

Add a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.

For example: User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com

WRITE operations

No authentication is required for adding new products or adding images.

Basic authentication is required for editing existing products. You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site.

Parameters: +* user_id: YourUserID +* password: YourPassword

Checking you’re authentified

https://world.openfoodfacts.org/cgi/auth.pl

This endpoint returns status 200 or 403 if the user is authentified, either through the “session” cookie, or with the user_id and password parameters.

Environments

You can do READ / SEARCH operations on the prod environment running @ https://world.openfoodfacts.org.

You can do WRITE operations tests on the dev environment running @ https://world.openfoodfacts.net (user:off, password:off).

Security

Use the SSL version of the API: https://world.openfoodfacts.net

Error Codes

  • Product does not exist - HTTP code 200 + “status_verbose” : “product not found” + “Status” : 0. +The request format is correct, but the product code does not exist in the database.
  • Wrong Password - HTTP code 200 + an HTML page with a link to log in. +The request format is correct, but basic authentication is missing or the password entered is not correct.
  • Server down - HTTP codes 502/503/500
  • Redirect to another product - HTTP code 301

Disclaimer: The HTML code 404 is never thrown, even when a wrong password is entered. A feature request has been created and we are already working to fix this.

Rate limit

The API intended use is for apps, with one real user scan = one query. Automated queries are not supported. Please let us know in advance if you expect a high volume of calls. 

For more information, see: https://world.openfoodfacts.org/data

Cache

Some queries (facets) are caches. Should you need to disable the cache, you can pass the nocache=1 parameter.

Payload size reduction

Using the fields= parameter, you can reduce the response to only the fields you need.

Preliminary Considerations

The API development is in progress. This has several implications:

  • Open Food Facts and food products are constantly evolving.
  • Assume that data is less reliable until the product is marked as complete. You might want to filter incomplete products to avoid issues (this is especially relevant for allergens or food intolerances). Let your end users know about this and encourage them to exercise caution. Be upfront about possible risks. You can use the following template to inform your users: The data provided to you by this app are retrieved from the Open Food Facts database. No guarantees can be made for the accuracy, completeness, or reliability of the information provided. The data are provided “as is” and the originating source for the data (Open Food Facts) is not liable for any damages arising out of the use of the data.
  • Join our Slack Channel (https://slack-ssl-openfoodfacts.herokuapp.com) to get help, to share your thoughts, to let us know what you build with the API (contact@openfoodfacts.org or in the #API channel) or if you want to use WRITE operations.
  • You can also join the mailing list to be notified when improvements or changes are made to the API (we send only relevant information and very few e-mails. Don’t worry, you won’t be spammed). To join the mailing list, send an empty e-mail to api-subscribe@openfoodfacts.org to subscribe.

License

  • Do not send copyrighted photos or information using the API. Everything you send is OdBL for the data (https://opendatacommons.org/licenses/odbl/summary/index.html) and CC-BY-SA for the pictures (https://creativecommons.org/licenses/by-sa/4.0/). If you don’t own the data, you bear all the legal consequences.
  • Mention Open Food Facts as the source of the data.
  • Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk).
  • Share any additions under the OdBL with the community.
  • By using any part of the API you have read and understood the license.

API Conventions

  • Fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
  • Fields that end with _datetime are dates in the ISO8601 format: yyyy-mm-ddThh:mn:ssZ
  • Fields that end with _tags are comma-separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)
  • Fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language
  • Fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product

Bugs

Do not hesitate to file a bug if you find an issue in the API or need an improvement. +You can fill out the issue report on GitHub:

Downloading Data

It is recommended to use the live API to get updated data about products. However, in some cases, you may need a snapshot. +They are available at:

  • https://world.openfoodfacts.net/data (all data)
  • https://[countrycode].openfoodfacts.net/data (data for a specific country).

Example: https://us.openfoodfacts.org/data - (See the list of countries in the Countries taxonomy)

Exporting Data

  • File Encoding: The file encoding is Unicode UTF-8.
  • CSV API: The character that separates fields is < tab > (tabulation).
  • JSON

API Roadmap

API Redesign: The API is far from perfect. It’s been decided to fix the most urgent bugs and start planning for a new version, more compliant with modern API standards. We need all the help we can get. Please join us on the #api Slack channel.

  • Project API: Additives
  • Project API: States
  • Project API: Statistics
  • Project API: Statistics Entry Dates

Other Projects

  • Open Pet Food Facts
  • Open Beauty Facts
  • Open Products Facts

More topics

Get all food products  |  GET   -https://world.openfoodfacts.org

Description

Get all products from Open Food Facts API.

Query
KeyValueDescription
jsontrue

READ requests allow you to retrieve the nutritional data of a product with a barcode.

Get nutrition facts for a specific barcode  |  GET   -https://world.openfoodfacts.org/api/v2/product/04963406

Description

  • Add product/<BARCODE> to locate the product by it’s barcode.


Get a country-specific nutrients ordered list  |  GET   -https://us.openfoodfacts.org/cgi/nutrients.pl

Description

Get a country-specific nutrients ordered list. It changes based on country and is useful both to show a nutrition table or a nutrition input form.

https://fr.openfoodfacts.org/cgi/nutrients.pl

https://us.openfoodfacts.org/cgi/nutrients.pl

3. SEARCH Requests +https://us.openfoodfacts.net/cgi/nutrients.pl

Description

Get a country-specific nutrients ordered list. It changes based on country and is useful both to show a nutrition table or a nutrition input form.

https://fr.openfoodfacts.org/cgi/nutrients.pl

https://us.openfoodfacts.org/cgi/nutrients.pl

3. SEARCH Requests 6

SEARCH requests allow you to retrieve the nutritional data of products that comply with your search criteria. Check out the examples below to see what you can do !

Important! The search feature works on whole words only, not parts of words. Your application should not have “search as you type” features that send search queries with parts of words, since this causes performance issues on the Open Food Facts server.

Search for Spanish products  |  GET   -https://es.openfoodfacts.org/cgi/search.pl

Description

  • Add es. prefix to get only Spanish products.
  • Add json=true to get a JSON response.


Headers
KeyValueDescription
Content-Typeapplication/json
Query
KeyValueDescription
actionprocess
jsontrue

Search for US breakfast cereals  |  +https://es.openfoodfacts.net/cgi/search.pl

Description

  • Add es. prefix to get only Spanish products.
  • Add json=true to get a JSON response.


Headers
KeyValueDescription
Content-Typeapplication/json
Query
KeyValueDescription
actionprocess
jsontrue

Search for US breakfast cereals  |  GET   -https://us.openfoodfacts.org/cgi/search.pl

Description

  • Add us. prefix to get only US products.
  • Add json=true to get a JSON response.
  • Add a categories filter to get only breakfast cereals.


Query
KeyValueDescription
actionprocess
tagtype_0categories
tag_contains_0contains
tag_0breakfast_cereals
jsontrue

Search for Italian foods with a great Nutriscore (A)  |  +https://us.openfoodfacts.net/cgi/search.pl

Description

  • Add us. prefix to get only US products.
  • Add json=true to get a JSON response.
  • Add a categories filter to get only breakfast cereals.


Query
KeyValueDescription
actionprocess
tagtype_0categories
tag_contains_0contains
tag_0breakfast_cereals
jsontrue

Search for Italian foods with a great Nutriscore (A)  |  GET   -https://it.openfoodfacts.org/cgi/search.pl

Description

  • Add it. prefix to get only Italian products.
  • Add json=true to get a JSON response.
  • Add a nutrition_grade filter to get food with Nutriscore ‘A’


Query
KeyValueDescription
actionprocess
tagtype_1nutrition_grades
tag_contains_1contains
tag_1A
jsontrue

Search for French breakfast cereals with no additives nor palm oil and a great Nutriscore (A)  |  +https://it.openfoodfacts.net/cgi/search.pl

Description

  • Add it. prefix to get only Italian products.
  • Add json=true to get a JSON response.
  • Add a nutrition_grade filter to get food with Nutriscore ‘A’


Query
KeyValueDescription
actionprocess
tagtype_1nutrition_grades
tag_contains_1contains
tag_1A
jsontrue

Search for French breakfast cereals with no additives nor palm oil and a great Nutriscore (A)  |  GET   -https://fr.openfoodfacts.org/cgi/search.pl

Description

  • Add fr. prefix to get only French products.
  • Add json=true to get a JSON response.
  • Add multiple criteria (AND):
    • Add a categories filter to get only breakfast cereals
    • Add a nutrition_grade filter to get food with Nutriscore ‘A’
    • Add ingredients_from_palm_oil=without to get food without palm oil
    • Add additives=without to get food without additives


Query
KeyValueDescription
actionprocess
tagtype_0categories
tag_contains_0contains
tag_0breakfast_cereals
tagtype_1nutrition_grades
tag_contains_1contains
tag_1A
ingredients_from_palm_oilwithout
additiveswithout
jsontrue

WRITE requests allow you to contribute new products and data to the Open Food Facts database.

Note: Please use the dev environment https://world.openfoodfacts.net for making test write calls (user:off, password:off). Remember to join the API channel on Slack before making a POST request !

Note:

Selecting, cropping and rotating photos are non-destructive actions. That means, the original version of the image uploaded to the system is kept as is. The subsequent changes made to the image are also stored as versions of the original image.

The actions described in this topic do not modify the image, but provide metadata on how to use it (the data of the corners in the case of selection and the data of the rotation). That is, you send an image to the API, provide an id, you define, for example, the cropping and rotation parameters and as a response, the server generates a new image as requested and you can call this new version of the image.

Add a new product  |  POST   -https://us.openfoodfacts.org/cgi/product_jqm2.pl

Query
KeyValueDescription
code04963406
user_idtest
passwordtest
brandsHäagen-Dazs
labelskosher

Add a photo to an existing product  |  POST   -https://us.openfoodfacts.org/cgi/product_jqm2.pl

Description

Photos are source and proof of data. When you upload an image to Open Food Facts, the image is stored as is. The first photo uploaded for a product is auto-selected as the product’s “front” photo.

Before uploading photos:

  • Image Quality: +https://us.openfoodfacts.net/cgi/product_jqm2.pl

Description

Photos are source and proof of data. When you upload an image to Open Food Facts, the image is stored as is. The first photo uploaded for a product is auto-selected as the product’s “front” photo.

Before uploading photos:

  • Image Quality: Uploading quality photos of a product, its ingredients and nutrition table is very important, since it allows the Open Food Facts OCR system to retrieve important data to analyze the product. The minimal allowed size for photos is 640 x 160 px.

  • Upload Behavior: In case you upload more than one photo of the front, the ingredients and the nutrition facts, beware that only the first photo of each category will be displayed. (You might want to take additional images of labels, recycling instructions, and so on). All photos will be saved.

  • Label Languages: Multilingual products have several photos based on languages present on the packaging. You can specify the language by adding a lang code suffix to the request.

Product Image Upload (Perl):

The API route is product_image_upload.pl and you can specify from which perspective the photo was taken, by sending the imagefield to precise the angle, AND the image as a Multipart response in the matching field.

Parameters:

  • code: the barcode of the product
  • imagefield: (can be either: front | ingredients | nutrition | packaging)
  • imgupload_front : your image file if imagefield=front
  • imgupload_ingredients: your image file if imagefield=ingredients
  • imgupload_nutrition: your image file if imagefield=nutrition
  • imgupload_packaging: your image file if imagefield=packaging


Query
KeyValueDescription
code04963406
product_image_upload.pl/imgupload_frontcheeriosfrontphoto.jpg

Crop a photo  |  POST   -https://world.openfoodfacts.org/cgi/product_image_crop.pl

Description

Note: Cropping is only relevant for editing existing products. You cannot crop an image the first time you upload it to the system.

Query
KeyValueDescription
code04963406
imgid2
idfront_en
x10
y10
x2145
y2145

Rotate a photo  |  POST   -https://world.openfoodfacts.org/cgi/product_image_crop.pl

Description

Although we recommend rotating photos manually and uploading a new version of the image, the OFF API allows you make api calls to automate this process.

You can rotate existing photos by setting angle to 90º, 180º or 270º clockwise.

Example:

POST https://world.openfoodfacts.org/cgi/product_image_crop.pl?code=3266110700910&id=nutrition_fr&imgid=1&angle=90

Query
KeyValueDescription
code04963406
idnutrition_fr
imgid1
angle90

Deselecting a photo  |  POST  

Description

You have to deselect photos to remove languages that are not relevant to the product.

[DOCUMENTATION TBA]


Performing OCR on a product  |  GET   -https://world.openfoodfacts.org/cgi/ingredients.pl

Description

Open Food Facts uses optical character recognition (OCR) to retrieve nutritional data and other information from the product labels.

Process

  1. Capture the barcode of the product where you want to perform the OCR.
  2. The Product Opener server software opens the image (process_image=1)
  3. Product Opener returns a JSON response. Processing is done using Tesseract or Google Cloud Vision (recommended). The result is often cripped with errors with Tesseract, less with Google Cloud Vision.

Notes: +https://world.openfoodfacts.net/cgi/ingredients.pl

Description

Open Food Facts uses optical character recognition (OCR) to retrieve nutritional data and other information from the product labels.

Process

  1. Capture the barcode of the product where you want to perform the OCR.
  2. The Product Opener server software opens the image (process_image=1)
  3. Product Opener returns a JSON response. Processing is done using Tesseract or Google Cloud Vision (recommended). The result is often cripped with errors with Tesseract, less with Google Cloud Vision.

Notes: * The OCR may contain errors. Encourage your users to correct the output using the ingredients WRITE API. -* You can also use your own OCR, especially if to plan to send a high number of queries.

OCR with Google Cloud Vision

We recommend Google’s Vision API to detect and extract text from the images.

For more information about this product, see: https://cloud.google.com/vision/docs/ocr?hl=en

Set ocr_engine=google_cloud_vision to use it.

Query
KeyValueDescription
code04963406
idingredients_fr
process_image1
ocr_enginegoogle_cloud_vision

Image Refresh API  |  GET   https://fr.openfoodfacts.org/api/v0/produit/3483130043180/beurre-cru-a-la-baratte-les-petites-laiteries

Description

image @@ -25536,7 +25541,7 @@ “packaging”

Optional - mention how old the image is

How to convert seconds in human readable format: 83734290 = 2 years and 7 months (example routine to convert) - https://stackoverflow.com/questions/29681328/convert-seconds-into-years-months-weeks-hours-minutes-and-seconds

Send the right query based on the initial field in images_to_update_fr

  • Do not use the computed values in the pseudo code
  • Probably refactor the methods we currently have to pass the field name, and make it future proof if we want to add new image fields.


Query
KeyValueDescription
fieldsimages_to_update_fr

5. Filtering 3

Advanced filtering is available to make fine-grained requests to the API.

General parameters  |  GET - 

Description

This section includes the parameters you can add to make READ / SEARCH / WRITE requests.

URL Parameters

Country code

A country code is prefixed to the domain name openfoodfacts.org, e.g: fr.: it allows filtering all products from a specific country.

You can use world. to display products from all over the world or use one of the Alpha 2 codes as per ISO-3166-1.

Examples: + 

Description

This section includes the parameters you can add to make READ / SEARCH / WRITE requests.

URL Parameters

Country code

A country code is prefixed to the domain name openfoodfacts.net, e.g: fr.: it allows filtering all products from a specific country.

You can use world. to display products from all over the world or use one of the Alpha 2 codes as per ISO-3166-1.

Examples: - United States: us - France: fr - Spain: es

You can find the full list of supported country codes in the Countries taxonomy.

Important! Using a specific country code will also change the naming of the response fields, see language code.

Language code

A language code can be added after the country code to specify the language of the response fields, e.g: https://<cc>-<lc>.openfoodfacts.org

Example:

https://fr.openfoodfacts.org/categorie/pizzas.json

  • Products returned are sold in France.
  • Names of the response fields are in French.

Example 2:

https://fr-en.openfoodfacts.org/category/pizzas.json

  • Products returned are sold in France.
  • Names of the response fields are in English.

The language codes supported are based on the ISO Standards 639-1.

You can find the full list of supported language codes in the Languages taxonomy.

API Version

Current version number of the Open Food Facts API. For now, only version 0 is available. To be represented as: /api/v0

Results per page

page_size # page_size

  • 20 # 20
  • 50 # 50
  • 100 # 100
  • 250 # 250
  • 500 # 500
  • 1000 # 1000

Pagination

  • page=1

Format

  • json=true (recommended)
  • xml=true

Output fields

Filtering the output fields reduces the payload size, the bandwith needed and the download time. To filter the fields, simply add the “fields” parameter to your search query. Example to retrieve only the generic_name: https://world.openpetfoodfacts.org/api/v0/product/20106836.json?fields=generic_name



6. Understanding responses 5

Product  |  GET - 

Description

General information:

  • code : 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.
  • url : url of the product page on Open Food Facts.
  • creator : contributor who first added the product.
  • created_t : date when the product was added (UNIX timestamp format).
  • created_datetime : date when the product was added (ISO8601 format: yyyy-mm-ddThh:mn:ssZ).
  • last_modified_t : date when the product page was last modified.
  • last_modified_datetime: date and time when the product was last modified.
  • product_name : name of the product.
  • generic_name: legal name of the product as regulated by the European authorities.
  • quantity : quantity and unit.

Ingredients:

  • ingredients_text
  • traces: List of substances that might cause allergies that are present in trace amount in the product (this does not include the ingredients, as they are not only present in trace amount). It is taxonomized with the allergens taxonomy.
  • traces_tags

Packages:

  • packaging : shape, material. Example: Cardboard
  • packaging_tags
  • emb_codes : packager code. Example: EMB 2013330
  • emb_codes_tags

Brands:

  • brands
  • brands_tags

Categories:

  • categories
  • categories_tags

Location:

  • origins : origins of ingredients
  • origins_tags
  • first_packaging_code_geo : coordinates corresponding to the first packaging code.
  • manufacturing_places : places where the product was manufactured or transformed.
  • manufacturing_places_tags
  • cities
  • cities_tags
  • purchase_places: country, state and/or city where the product can be purchased. For example: Paris, France.
  • stores: distributor name. Example: Tesco, Walmart, Carrefour.
  • countries : list of countries where the product is sold.
  • countries_tags

Labels

  • labels: Example: vegan, fat free, Kosher.
  • labels_tags

Producer

  • producer
  • producer_product_id
  • producer_version_id

Value and Weight

  • net_weight_value
  • net_weight_unit
  • drained_weight_value
  • drained_weight_unit
  • volume_value
  • volume_unit

Images

  • image_url
  • image_small_url: simplified version of the url.

Energy

  • Legacy

    • energy_unit: (string). The unit used in the energy_value field (example in JSON: “energy_unit”:“kJ”). Possible values are “kJ” or “kcal”.
    • energy_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in the unit specified in the field energy_unit (example in JSON: “energy_value”:“190”).

  • Preferred method

    • energy-kj_unit: (string). The unit used in the field energy-kj_value (example in JSON: “energy_unit”:“kJ”). The only possible value is “kJ”;
    • energy-kj_value: (string).  The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kJ (example in JSON: “energy-kj_value”:“190”).
    • energy-kcal_unit: (string). The unit used in the field energy-kcal_unit (example in JSON: “energy_unit”:“kcal”). The only possible value is “kcal”;
    • energy-kcal_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kcal (example in JSON: “energy-kcal_value”:“190”).

According to the European regulation, the ratio between values calculated in kJ and values calculated in kcal may differ from the standard conversion ratio of 4.184 (because of carried rounding errors). Both values might appear on the same product. In that case, the value in kJ will be the one returned in the legacy energy_unit and energy_value fields. If only one unit was provided (kJ or kcal), this unit will be returned in the legacy energy_unit and energy_value fields.

Additives:

  • additives_n : number of food additives
  • additives
  • additives_tags

Miscellaneous:

  • serving_size : serving size in g (or ml)
  • serving_quantity
  • no_nutriments : indicates if the nutrition facts are shown on the product label.
  • ingredients_text
  • allergens
  • traces
  • ingredients_from_palm_oil_n
  • ingredients_from_palm_oil
  • ingredients_from_palm_oil_tags
  • ingredients_that_may_be_from_palm_oil_n
  • ingredients_that_may_be_from_palm_oil
  • ingredients_that_may_be_from_palm_oil_tags
  • nutrition_grade_fr : nutrition grade (‘a’ to ‘e’). see https://world.openfoodfacts.org/nutriscore
  • main_category
  • other_information
  • conservation_conditions: Example: Keep in a dry place.
  • recycling_instructions_to_recycle
  • recycling_instructions_to_discard
  • nutrition_grade_fr_producer: declarative (printed on the packaging)
  • recipe_idea
  • customer_service: contact info of customer service.
  • preparation: how to cook the food: microwave, oven, which temperature…
  • warning: regulatory warning. Example: contains sorbitol.
  • data_sources: source of data imported from producers.
  • nova_group: system of grades for comparing the degree of processing of products. For more information, see: https://world.openfoodfacts.org/nova
  • pnns_groups_1: disregard. Used to improve the nutriscore calculation.
  • pnns_groups_2: disregard. Used to improve the nutriscore calculation.
  • states: if the product is complete or if there is any information missing.

Environment -The Eco-Score needs to be queried according to the country of the user. -Due to the recent nature of the Eco-Score, the full APIs are documented in a separate document. -https://docs.google.com/document/d/1_5AeofpXbaKY9Rd3eeWmHIrhJE8GiPQ-Mfx1SCvpzME/edit?usp=sharing

Other nutrition keys

  • carbon-footprint_100g : carbon footprint (indicated on some products). The unit is absolute grams of C02.
  • ph_100g : pH (no unit)
  • cocoa : minimal cacao content of the product in %. Important!: Note the typo.
  • fruits-vegetables-nuts_100g : % of fruits, vegetables and nuts (excluding potatoes, yams, manioc)
  • nutrition-score-fr_100g : experimental nutrition score derived from the UK FSA score and adapted for the French market (formula defined by the team of Professor Hercberg)
  • nutrition-score-uk_100g : nutrition score defined by the UK Food Standards Administration (FSA). -For more information about the difference between the fr and uk nutri-scores see the FAQ section of this documentation.


Nutrition facts  |  + 

Description

General information:

  • code : 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.
  • url : url of the product page on Open Food Facts.
  • creator : contributor who first added the product.
  • created_t : date when the product was added (UNIX timestamp format).
  • created_datetime : date when the product was added (ISO8601 format: yyyy-mm-ddThh:mn:ssZ).
  • last_modified_t : date when the product page was last modified.
  • last_modified_datetime: date and time when the product was last modified.
  • product_name : name of the product.
  • generic_name: legal name of the product as regulated by the European authorities.
  • quantity : quantity and unit.

Ingredients:

  • ingredients_text: Raw list of ingredients. This will get automatically parsed and get used to compute the Eco-Score. You can either request if (if it exists) or send it in a specific language, e.g: ingredients_text_en
  • traces: List of substances that might cause allergies that are present in trace amount in the product (this does not include the ingredients, as they are not only present in trace amount). It is taxonomized with the allergens taxonomy.
  • traces_tags

Packages:

  • packaging : shape, material. Example: Cardboard
  • packaging_tags
  • packaging_text : Recycling instructions as raw text eg: “Plastic bottle to recycle, Plastic cap to recycle”. This will get automatically parsed and get used to compute the Eco-Score. You can either request if (if it exists) or send it in a specific language, e.g: packaging_text_en for the above example
  • emb_codes : packager code. Example: EMB 2013330
  • emb_codes_tags

Brands:

  • brands
  • brands_tags

Categories:

  • categories
  • categories_tags

Location:

  • origins : origins of ingredients
  • origins_tags
  • first_packaging_code_geo : coordinates corresponding to the first packaging code.
  • manufacturing_places : places where the product was manufactured or transformed.
  • manufacturing_places_tags
  • cities
  • cities_tags
  • purchase_places: country, state and/or city where the product can be purchased. For example: Paris, France.
  • stores: distributor name. Example: Tesco, Walmart, Carrefour.
  • countries : list of countries where the product is sold.
  • countries_tags

Labels

  • labels: Example: vegan, fat free, Kosher.
  • labels_tags

Producer

  • producer
  • producer_product_id
  • producer_version_id

Value and Weight

  • net_weight_value
  • net_weight_unit
  • drained_weight_value
  • drained_weight_unit
  • volume_value
  • volume_unit

Images

  • image_url
  • image_small_url: simplified version of the url.

Energy

  • Legacy
    • energy_unit: (string). The unit used in the energy_value field (example in JSON: “energy_unit”:“kJ”). Possible values are “kJ” or “kcal”.
    • energy_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in the unit specified in the field energy_unit (example in JSON: “energy_value”:“190”).
  • Preferred method
    • energy-kj_unit: (string). The unit used in the field energy-kj_value (example in JSON: “energy_unit”:“kJ”). The only possible value is “kJ”;
    • energy-kj_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kJ (example in JSON: “energy-kj_value”:“190”).
    • energy-kcal_unit: (string). The unit used in the field energy-kcal_unit (example in JSON: “energy_unit”:“kcal”). The only possible value is “kcal”;
    • energy-kcal_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kcal (example in JSON: “energy-kcal_value”:“190”).

According to the European regulation, the ratio between values calculated in kJ and values calculated in kcal may differ from the standard conversion ratio of 4.184 (because of carried rounding errors). Both values might appear on the same product. In that case, the value in kJ will be the one returned in the legacy energy_unit and energy_value fields. If only one unit was provided (kJ or kcal), this unit will be returned in the legacy energy_unit and energy_value fields.

Additives:

  • additives_n : number of food additives
  • additives
  • additives_tags

Miscellaneous:

  • serving_size : serving size in g (or ml)
  • serving_quantity
  • no_nutriments : indicates if the nutrition facts are shown on the product label.
  • ingredients_text
  • allergens
  • traces
  • ingredients_from_palm_oil_n
  • ingredients_from_palm_oil
  • ingredients_from_palm_oil_tags
  • ingredients_that_may_be_from_palm_oil_n
  • ingredients_that_may_be_from_palm_oil
  • ingredients_that_may_be_from_palm_oil_tags
  • nutrition_grade_fr : nutrition grade (‘a’ to ‘e’). see https://world.openfoodfacts.org/nutriscore
  • main_category
  • other_information
  • conservation_conditions: Example: Keep in a dry place.
  • recycling_instructions_to_recycle
  • recycling_instructions_to_discard
  • nutrition_grade_fr_producer: declarative (printed on the packaging)
  • recipe_idea
  • customer_service: contact info of customer service.
  • preparation: how to cook the food: microwave, oven, which temperature…
  • warning: regulatory warning. Example: contains sorbitol.
  • data_sources: source of data imported from producers.
  • nova_group: system of grades for comparing the degree of processing of products. For more information, see: https://world.openfoodfacts.org/nova
  • pnns_groups_1: disregard. Used to improve the nutriscore calculation.
  • pnns_groups_2: disregard. Used to improve the nutriscore calculation.
  • states: if the product is complete or if there is any information missing.

Environment
The Eco-Score needs to be queried according to the country of the user.
Due to the recent nature of the Eco-Score, the full APIs are documented in a separate document.
https://docs.google.com/document/d/1_5AeofpXbaKY9Rd3eeWmHIrhJE8GiPQ-Mfx1SCvpzME/edit?usp=sharing

Other nutrition keys

  • carbon-footprint_100g : carbon footprint (indicated on some products). The unit is absolute grams of C02.
  • ph_100g : pH (no unit)
  • cocoa : minimal cacao content of the product in %. Important!: Note the typo.
  • fruits-vegetables-nuts_100g : % of fruits, vegetables and nuts (excluding potatoes, yams, manioc)
  • nutrition-score-fr_100g : experimental nutrition score derived from the UK FSA score and adapted for the French market (formula defined by the team of Professor Hercberg)
  • nutrition-score-uk_100g : nutrition score defined by the UK Food Standards Administration (FSA).
    For more information about the difference between the fr and uk nutri-scores see the FAQ section of this documentation.


Nutrition facts  |  GET  

Description

Each nutrition fact consists of multiple fields which are represented by a key. The fields can also be found in the taxonomy translation file.

Field names are built by concatenating 3 concepts:

  • The nutriment: “fiber”, “carbohydrate”, “salt”, etc…
  • as sold vs prepared: “” (nothing is added for as sold) or “prepared” (for prepared products. Example: dehydrated soups, instant cocoa or convenience products like fries).
  • The reference quantity: “100g” or “serving”

Example 1: 3.4 g of carbohydrates in the product as sold for 100g should be represented as:

carbohydrates_100g: 3.4

Example 2: 12 mg of zinc in the prepared product for a serving of 125 mL should be defined as:

zinc_prepared_serving: 0.012

Important: * Only the nutrition facts that are actually found on the packaging are present in the interface. @@ -25613,11 +25614,11 @@

Facets

A facet refers to all the values that contributors add to a property. A facet includes the values defined in the taxonomy and the new values added by the contributors. Facet change constantly and their values are not validated. Facets vary by country.

Facet queries can be made to retrieve a list of the values that belong to a specific facet (for example, labels) and its product count.

A facet query has the following structure:

https://world.openfoodfacts.org/allergens.json

You can replace world with any of the country codes described in the Countries taxonomy.

The values of the facet that are not included in the taxonomy are marked with an asterisk (*).

See an example here: https://us.openfoodfacts.org/labels

Categories

A category is a “tag” used to classify foods in different groups. For example, cheeses. Categories can be freely entered by users. Food category is one of the facets of Open Food Facts. Other examples are allergens or additives.

Note that there is also a taxonomy of categories used to define as many as possible of the “tags” entered by users as known entries in the taxonomy.

The following query retrieves a list of all categories available:

https://world.openfoodfacts.org/categories.json

You can retrieve a list of products that belong to a specific category. For example, “cheeses”:

https://world.openfoodfacts.org/category/cheeses.json

Note that the query has an additional parameter “category”.

Important! The categories hierarchy is not a tree but a lattice: each node can have several children, but also several parents.

List Allergens  |  GET   -https://world.openfoodfacts.org/allergens.json

Description

Query allergens facet.

See examples below for taxonomy and other queries.

List Additives  |  GET   -https://world.openfoodfacts.org/additives.json

Description

Query additives facet.

See examples below for taxonomy and other queries.

The response includes the code and name of the additive, a link to a Wikipedia page with more information about the additive, and the number of products containing this additive in the Open Food Facts database.

List Additive classes  |  GET   -https://world.openfoodfacts.org/data/taxonomies/additives_classes.json

Description

Query additives classes taxonomy.

Headers
KeyValueDescription
Content-Typeapplication/json

List Brands  |  GET   -https://world.openfoodfacts.org/brands.json

Description

Query brands facet.

See examples below for taxonomy and other queries.

List Countries  |  GET   -https://world.openfoodfacts.org/countries.json

Description

Query countries facet.

See examples below for taxonomy and other queries.

The only country code accepted for queries to the API is ‘country_code_2’. The other formats are only provided for your convenience. Those are the country codes for Top Level Domains.

List Ingredients  |  GET   -https://world.openfoodfacts.org/ingredients.json

Description

Query ingredients facet.

See examples below for taxonomy and other queries.

List Ingredients Analysis  |  GET   -https://world.openfoodfacts.org/data/taxonomies/ingredients_analysis.json

Description

Query ingredients taxonomy.

This request is used to get information about absence or unawareness of the presence of:

  • palm oil: Palm oil free, Palm oil, Palm oil content unknown, may-contain-palm-oil
  • vegetarian ingredients: vegetarian, non-vegetarian, vegetarian-status-unknown, maybe-vegetarian.
  • vegan ingredients: vegan, non-vegan, vegan-status-unknown, maybe-vegan.

Important! Parsing might not be perfect and the ingredient detection might have issues in some languages. For more information on how the translation works, see: https://github.com/openfoodfacts/openfoodfacts-server/blob/master/taxonomies/ingredients.txt

List Languages  |  GET   -https://world.openfoodfacts.org/languages.json

Description

Query languages facet.

See examples below for taxonomy and other queries.

List Nova Groups  |  GET   -https://world.openfoodfacts.org/data/taxonomies/nova_groups.json

Description

Query nova groups taxonomy.

List Nutrients  |  GET   -https://world.openfoodfacts.org/cgi/nutrients.pl

Description

Open Food Facts uses optical character recognition (OCR) to retrieve nutritional data and other information from the product labels.

Process

  1. Capture the barcode of the product where you want to perform the OCR.
  2. The Product Opener server software opens the image (process_image=1)
  3. Product Opener returns a JSON response. Processing is done using Tesseract or Google Cloud Vision (recommended). The result is often cripped with errors with Tesseract, less with Google Cloud Vision.

Notes: +https://world.openfoodfacts.net/cgi/nutrients.pl

Description

Open Food Facts uses optical character recognition (OCR) to retrieve nutritional data and other information from the product labels.

Process

  1. Capture the barcode of the product where you want to perform the OCR.
  2. The Product Opener server software opens the image (process_image=1)
  3. Product Opener returns a JSON response. Processing is done using Tesseract or Google Cloud Vision (recommended). The result is often cripped with errors with Tesseract, less with Google Cloud Vision.

Notes: * The OCR may contain errors. Encourage your users to correct the output using the ingredients WRITE API. * You can also use your own OCR, especially if to plan to send a high number of queries.

OCR with Google Cloud Vision

We recommend Google’s Vision API to detect and extract text from the images.

For more information about this product, see: https://cloud.google.com/vision/docs/ocr?hl=en

Set ocr_engine=google_cloud_vision to use it.

Query
KeyValueDescription
code04963406
idingredients_fr
process_image1
ocr_enginegoogle_cloud_vision

List Nutrient Levels  |  GET   -https://world.openfoodfacts.org/data/taxonomies/nutrient_levels.json

Description

Query nutrient levels taxonomy.

The nutrient levels indicate the quantity of fat, saturated fat, sugar and salt in a product.

The quantity levels are the following:

  • low
  • moderate
  • high

For more information about the quantity levels, read the annex 3 of the guide on the development of front of pack nutrition labels, issued by the Department of Health of the British Government, the Food Standards Agency, and devolved administrations in Scotland, Northern Ireland and Wales in collaboration with the British Retail Consortium. +https://world.openfoodfacts.net/data/taxonomies/nutrient_levels.json

Description

Query nutrient levels taxonomy.

The nutrient levels indicate the quantity of fat, saturated fat, sugar and salt in a product.

The quantity levels are the following:

  • low
  • moderate
  • high

For more information about the quantity levels, read the annex 3 of the guide on the development of front of pack nutrition labels, issued by the Department of Health of the British Government, the Food Standards Agency, and devolved administrations in Scotland, Northern Ireland and Wales in collaboration with the British Retail Consortium. Annex 3. Determining red, amber and green colour coding (and High, Medium and Low (HML) text if applied): https://www.food.gov.uk/sites/default/files/media/document/fop-guidance_0.pdf

Examples:

  • Saturated fat in moderate quantity
  • Salt in high quantity



List States  |  GET   -https://world.openfoodfacts.org/states.json

Description

You can use the following query to retrieve the states taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/states.json
+https://world.openfoodfacts.net/states.json
Description

You can use the following query to retrieve the states taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/states.json

Use the following query to retrieve the states facet:

GET https://world.openfoodfacts.org/states.json

You can drill-down to the list of products in a certain state by making the following call:

GET https://world.openfoodfacts.org/state/statename.json

Example:

To retrieve a list of products with photo, you can make the following request:

GET https://world.openfoodfacts.org/state/photos-uploaded.json
@@ -544232,7 +544233,7 @@

8. Developer Journeys +https://world.openfoodfacts.net/packagings.json

8. Developer Journeys 6

Meet Dave.

Dave is an active Open Food Facts contributor and a developer who wants to build HealthyFoodChoices, an Android app aimed at conscious consumers that buy healthy products.

alt text

HealthyFoodChoices will query Open Food Facts API and provide information on healthy foods available in the place users are living in. Users can narrow down the results by applying different filters and save their search criteria so that the app shows them the products that match their preferences next time they use it.

To identify the potential users’ needs, Dave has met with some conscious consumers.

  • Anna is a 25-year old New Yorker who doesn’t drink soda, but her nephew does. She wants to compare the nutrition facts of two cola brands, and its variants (diet, zero, and so on) to decide which one to buy.

  • Stefano is a 36-year old Italian who follows a plant-based diet and wants to avoid the intake of palm oil. He’s looking for a breakfast cereal brand that does not use palm oil nor additives and has a great nutriscore (A).

Dev Journey 1: Comparing sodas for Anna  |  GET  

Description

Dave wants his app to make an API call to provide Anna the information she needs to make a conscious choice when buying sodas. 

Authentication and Header

To make the API query that returns the products that might be interesting for Anna, Dave doesn’t need to authenticate (READ request).

However, he has to add a User-Agent HTTP Header with the name of his app, the version, system and a url (if any), so that he doesn’t get blocked by mistake.

In this case, that would be: User-Agent: HealthyFoodChoices - Android - Version 1.0

Subdomain

Since Anna lives in NY, Dave wants to define the subdomain for the query as us. The subdomain automatically defines the country code (cc) and language of the interface (lc).  

The country code determines that only the products sold in the US are displayed. The language of the interface for the country code us is English.

In this case:

https://us.openfoodfacts.org

API Version

The current version number of the Open Food Facts API is v0.

https://us.openfoodfacts.org/api/v0

Product Barcode

After the version number, the word “product”, followed by its barcode must be added:

https://us.openfoodfacts.org/api/v0/product/

The app will provide Anna with information about additives, sugars and nutriscore of different types of colas, to help her make her purchase decision.

Anna selects the products she wants to compare in the application (Coca-Cola, Pepsi, Coca-Cola diet, Coca-Cola zero and Pepsi diet). The app retrieves the corresponding barcodes and makes the following calls: 

  • Pepsico Pepsi Cola Soda: @@ -554903,34 +554904,34 @@ Example: https://robotoff.openfoodfacts.org/api/v1/questions/3274570800026?lang=en&count=3

    {"questions": [{"barcode": "3274570800026", "type": "add-binary", "value": "Scallop", "question": "Does the product belong to this category?", "insight_id": "5cac03bc-a5a7-4ec2-a548-17fd9319fee7", "insight_type": "category", "source_image_url": "https://static.openfoodfacts.org/images/products/327/457/080/0026/front_en.4.400.jpg"}], "status": "found"}

  • Display the question and possible answers in the UI.

  • Send back the proper ping to the Open Food Facts server if the user answers.

    https://github.com/openfoodfacts/robotoff/blob/master/doc/api.md

    http://robotoff.openfoodfacts.org/api/v1/insights/annotate?insight_id=(insight_id)&annotation=(1,0,-1)&update=1

    Get a random insight  |  GET   -https://robotoff.openfoodfacts.org/api/{{ROBOTOFF_API_VERSION}/questions/random

    Description

    Fetch a random insight.

    Parameters

    • type (string, optional): The type of insight. If not provided, an insight from any type will be returned.

    • country (string, optional): Only return predictions with products from a specific country (ex: en:france)

    • value_tag (string, optional): Filter by value tag, i.e the value that is going to be sent to Open Food Facts.

    • server_domain (string, optional): Server domain. Default to ‘api.openfoodfacts.org’



    Query
    KeyValueDescription
    langfr
    insight_typescategory

    str, optional - comma-separated list, the type of insight. If not provided, an insight from any type will be returned.

    server_domainapi.openfoodfacts.org

    str, optional - server domain. Default to ‘api.openfoodfacts.org’

    count10

    str, optional - number of results to return (default: 1)

    value_tagen:bcaa

    str, optional - filter by value tag, i.e the value that is going to be sent to Openfoodfacts

    countryen:france

    str, optional - Only return predictions with products from a specific country (ex: en:france)

    brandsironmaxx

    (string, optional): filter by brands, comma-separated list of brand tags.

    Get insights (filtering system)  |  GET   -https://robotoff.openfoodfacts.org/api/{{ROBOTOFF_API_VERSION}/insights/

    Description

    Return all insights associated with a specific product.

    Parameters

    • barcode: Product barcode
    • server_domain (string, optional) - server domain. Default to ‘api.openfoodfacts.org’


    Query
    KeyValueDescription
    barcode0021000123803

    Optional. Allows to get all insights for a product

    langfr

    The language the response is served in, useful to get translated questions to ask users

    server_domainapi.openfoodfacts.org

    Domain it’s queried from

    count50

    number of insight you’d like

    insight_typespackaging

    packaging, category, label, brand,product_weight

    page1

    In some cases, you might want the nth page of insights

    Get a specific insight  |  +https://robotoff.openfoodfacts.net/api/{{ROBOTOFF_API_VERSION}/insights/

    Description

    Return all insights associated with a specific product.

    Parameters

    • barcode: Product barcode
    • server_domain (string, optional) - server domain. Default to ‘api.openfoodfacts.org’


    Query
    KeyValueDescription
    barcode0021000123803

    Optional. Allows to get all insights for a product

    langfr

    The language the response is served in, useful to get translated questions to ask users

    server_domainapi.openfoodfacts.org

    Domain it’s queried from

    count50

    number of insight you’d like

    insight_typespackaging

    packaging, category, label, brand,product_weight

    page1

    In some cases, you might want the nth page of insights

    Get a specific insight  |  GET   -https://robotoff.openfoodfacts.org/api/{{ROBOTOFF_API_VERSION}/insights/detail/

    Description

    Parameters

    • insight_id: ID of the insight


    Query
    KeyValueDescription
    id23541d80-02fc-4cd6-88eb-d93aa17e3386

    ID of the insight

    Submit an annotation  |  +https://robotoff.openfoodfacts.net/api/{{ROBOTOFF_API_VERSION}/insights/detail/

    Description

    Parameters

    • insight_id: ID of the insight


    Query
    KeyValueDescription
    id23541d80-02fc-4cd6-88eb-d93aa17e3386

    ID of the insight

    Submit an annotation  |  POST   -https://robotoff.openfoodfacts.org/api/{{ROBOTOFF_API_VERSION}/insights/annotate

    Description

    Submit an annotation, given the insight_id. The request type must be application/x-www-form-urlencoded.

    Parameters

    • insight_id (string, required): ID of the insight
    • annotation (integer, required): +https://robotoff.openfoodfacts.net/api/{{ROBOTOFF_API_VERSION}/insights/annotate
    Description

    Submit an annotation, given the insight_id. The request type must be application/x-www-form-urlencoded.

    Parameters

    • insight_id (string, required): ID of the insight
    • annotation (integer, required): Annotation of the prediction:
      • 1 to accept the prediction
      • 0 to refuse it
      • -1 for “unknown”.
    • update (integer, optional): Send the update to Open Food Facts if update=1. Otherwise, the update won’t be sent. This parameter is useful if the update is performed client-side.


    Query
    KeyValueDescription
    insight_id23541d80-02fc-4cd6-88eb-d93aa17e3386

    (str, required) - ID of the insight

    annotation0

    (int, required) - Annotation of the prediction: 1 to accept the prediction, 0 to refuse it, and -1 for “unknown”.

    updatefalse

    (int, optional) - Send the update to Openfoodfacts if update=1, don’t send the update otherwise. This parameter is useful if the update is performed client-side.

    Get questions  |  GET   -https://robotoff.openfoodfacts.org/api/{{ROBOTOFF_API_VERSION}/questions/

    Description

    You can get questions for a given product or get random questions.

    Parameters to be used to get questions for a given product

    • barcode: Product barcode
    • lang (string, optional): the language of the question/value. Default: en.
    • count (integer, optional): Number of questions to return. Default: 1.
    • server_domain (string, optional): server domain. Default: ‘api.openfoodfacts.org’

    Parameters to be used to get random questions

    • lang (string, optional): the language of the question/value. Default: en.
    • count (integer, optional): Number of questions to return. Default: 1.
    • insight_types (list, optional): comma-separated list, filter by insight types.
    • country (string, optional): filter by country tag.
    • brands (string, optional): filter by brands, comma-separated list of brand tags.
    • value_tag (string, optional): filter by value tag, i.e the value that is going to be sent to Openfoodfacts.
    • server_domain (string, optional): server domain. Default: api.openfoodfacts.org.


    Query
    KeyValueDescription
    langfr

    (str, optional) - the language of the question/value. ‘en’ by default.

    count10

    (int, optional) - Number of questions to return. Default to 1.

    server_domainapi.openfoodfacts.org

    (str, optional) - server domain. Default to ‘api.openfoodfacts.org’

    barcode0021000123803

    Product barcode

    Get statistics for a user  |  +https://robotoff.openfoodfacts.net/api/{{ROBOTOFF_API_VERSION}/questions/

    Description

    You can get questions for a given product or get random questions.

    Parameters to be used to get questions for a given product

    • barcode: Product barcode
    • lang (string, optional): the language of the question/value. Default: en.
    • count (integer, optional): Number of questions to return. Default: 1.
    • server_domain (string, optional): server domain. Default: ‘api.openfoodfacts.org’

    Parameters to be used to get random questions

    • lang (string, optional): the language of the question/value. Default: en.
    • count (integer, optional): Number of questions to return. Default: 1.
    • insight_types (list, optional): comma-separated list, filter by insight types.
    • country (string, optional): filter by country tag.
    • brands (string, optional): filter by brands, comma-separated list of brand tags.
    • value_tag (string, optional): filter by value tag, i.e the value that is going to be sent to Openfoodfacts.
    • server_domain (string, optional): server domain. Default: api.openfoodfacts.org.


    Query
    KeyValueDescription
    langfr

    (str, optional) - the language of the question/value. ‘en’ by default.

    count10

    (int, optional) - Number of questions to return. Default to 1.

    server_domainapi.openfoodfacts.org

    (str, optional) - server domain. Default to ‘api.openfoodfacts.org’

    barcode0021000123803

    Product barcode

    Image Crop (Robotoff side)  |  GET   -https://robotoff.openfoodfacts.org/api/{{ROBOTOFF_API_VERSION}/images/crop

    Query
    KeyValueDescription
    image_urlhttps://static.openfoodfacts.org/images/products/317/718/000/0810/1.jpg
    y_min0.758063614
    x_min0.888398051
    y_max0.993165255
    x_max0.994514585

    Get insights for popular products  |  +https://robotoff.openfoodfacts.net/api/{{ROBOTOFF_API_VERSION}/images/crop

    Query
    KeyValueDescription
    image_urlhttps://static.openfoodfacts.org/images/products/317/718/000/0810/1.jpg
    y_min0.758063614
    x_min0.888398051
    y_max0.993165255
    x_max0.994514585

    Get insights for popular products  |  GET   https://robotoff.openfoodfacts.org/api/v1/questions/popular

    Description

    This API was a Christmas present from Raphael to Pierre

    Query
    KeyValueDescription
    count5


Generated at 2022-02-04 09:09:29 by docgen
\ No newline at end of file +return ''+match+'';});}

Generated at 2022-02-04 09:36:29 by docgen
\ No newline at end of file diff --git a/off-pm-collection.json b/off-pm-collection.json index 9e04613..a59ab4a 100644 --- a/off-pm-collection.json +++ b/off-pm-collection.json @@ -1,6 +1,6 @@ { "info": { - "_postman_id": "ec40dfb2-9041-4f7d-b930-0320f424e5e2", + "_postman_id": "35da6b52-6273-4213-abea-34ca58d7c3d3", "name": "Open Food Facts API Documentation", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, @@ -293,7 +293,7 @@ ] } ], - "description": "As a developer, the **Open Food Facts API** allows you to get information about existing products and contribute to the products database.\n\nUsing the API, you can create apps to help people make better food choices and also provide data to enhance the database.\n\nCheck out how others are making use of the API at [https://world.openfoodfacts.org/discover#reuses](https://world.openfoodfacts.org/discover#reuses).\n\n* * *\n\n#### Data Disclaimer\n\nThe data contained in the Open Food Facts database are collected by users willing to selflessly contribute to the Open Food Facts initiative.\n\nTherefore, no guarantees can be made for the accuracy, completeness, or reliability of the information provided. The user assumes the entire risk related to the use of data. You (or your users) are very welcome to provide fixes using the **WRITE** API.\n\n* * *\n\n#### Usage\n\nYou can use the Open Food Facts API for production use cases, as long as 1 API call equals 1 real scan by a user.\n\n* * *\n\n#### Do you know that we have ready-made SDKs for many programming languages ?\n\n\n\n* * *\n\n#### Domains\n\nYou can either use the global domain ({{PROTOCOL}}://world.{{DOMAIN_NAME}}) or the local domains ({{PROTOCOL}}://fr.{{DOMAIN_NAME}}, {{PROTOCOL}}://en.{{DOMAIN_NAME}} …) for your API queries.\n\n* * *\n\n#### Endpoint\n\nThe Open Food Facts base API endpoint is {{PROTOCOL}}://world.{{DOMAIN_NAME}}/api/{{API_VERSION}}\n\n* * *\n\n#### Version\n\nThe current version of the API is {{API_VERSION}} .\n\n* * *\n\n#### Authentication\n\n**READ and SEARCH operations**\n\nNo authentication is required.\n\nAdd a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.\n\nFor example: `User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com`\n\n**WRITE operations**\n\nNo authentication is required for adding new products or adding images.\n\nBasic authentication is required for editing existing products. You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site.\n\nSee: 1.2 Authentication\n\n* * *\n\n#### Environments\n\nYou can do READ / SEARCH operations on the `prod` environment running @ [https://world.openfoodfacts.org](https://world.openfoodfacts.org).\n\nYou can do WRITE operations tests on the `dev` environment running @ [https://world.openfoodfacts.net](https://world.openfoodfacts.net) (user:`off`, password:`off`).\n\n* * *\n\n#### Security\n\nUse the SSL version of the API: {{PROTOCOL}}://world.{{DOMAIN_NAME}}\n\n* * *\n\n#### Error Codes\n\n* **Product does not exist** - HTTP code 200 + \"status_verbose\" : \"product not found\" + \"Status\" : 0. \n The request format is correct, but the product code does not exist in the database.\n* **Wrong Password** - HTTP code 200 + an HTML page with a link to log in. \n The request format is correct, but basic authentication is missing or the password entered is not correct.\n* **Server down** - HTTP codes 502/503/500\n* **Redirect to another product** - HTTP code 301\n \n\n**Disclaimer:** The HTML code 404 is never thrown, even when a wrong password is entered. A feature request has been created and we are already working to fix this.\n\n* * *\n\n#### Rate limit\n\nThe API intended use is for apps, with one real user scan = one query. Automated queries are not supported. Please let us know in advance if you expect a high volume of calls.\n\nFor more information, see: [https://world.openfoodfacts.org/data](https://world.openfoodfacts.org/data)\n\n* * *\n\n#### Cache\n\nSome queries (facets) are caches. Should you need to disable the cache, you can pass the `nocache=1` parameter.\n\n#### Payload size reduction\n\nUsing the `fields=` parameter, you can reduce the response to only the fields you need.\n\n#### Preliminary Considerations\n\nThe API development is in progress. This has several implications:\n\n* Open Food Facts and food products are constantly evolving.\n* Assume that data is less reliable until the product is marked as complete. You might want to filter incomplete products to avoid issues (this is especially relevant for allergens or food intolerances). Let your end users know about this and encourage them to exercise caution. Be upfront about possible risks. You can use the following template to inform your users: *The data provided to you by this app are retrieved from the Open Food Facts database. No guarantees can be made for the accuracy, completeness, or reliability of the information provided. The data are provided “as is” and the originating source for the data (Open Food Facts) is not liable for any damages arising out of the use of the data.*\n* Join our Slack Channel ([https://slack-ssl-openfoodfacts.herokuapp.com](https://slack-ssl-openfoodfacts.herokuapp.com)) to get help, to share your thoughts, to let us know what you build with the API ([contact@openfoodfacts.org](mailto:contact@openfoodfacts.org) or in the #API channel) or if you want to use WRITE operations.\n* You can also join the mailing list to be notified when improvements or changes are made to the API (we send only relevant information and very few e-mails. Don't worry, you won't be spammed). To join the mailing list, send an empty e-mail to [api-subscribe@openfoodfacts.org](mailto:api-subscribe@openfoodfacts.org) to subscribe.\n \n\n* * *\n\n#### License\n\n* Do not send copyrighted photos or information using the API. Everything you send is OdBL for the data ([https://opendatacommons.org/licenses/odbl/summary/index.html](https://opendatacommons.org/licenses/odbl/summary/index.html)) and CC-BY-SA for the pictures ([https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)). If you don't own the data, you bear all the legal consequences.\n* Mention Open Food Facts as the source of the data.\n* Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk).\n* Share any additions under the OdBL with the community.\n* By using any part of the API you have read and understood the license.\n \n\n* * *\n\n#### API Conventions\n\n* Fields that end with `_t` are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)\n* Fields that end with `_datetime` are dates in the ISO8601 format: yyyy-mm-ddThh:mn:ssZ\n* Fields that end with `_tags` are comma-separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)\n* Fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language\n* Fields that end with `_100g` correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product\n \n\n* * *\n\n#### Bugs\n\nDo not hesitate to file a bug if you find an issue in the API or need an improvement. \nYou can fill out the issue report on GitHub:\n\n* General bugs: [https://github.com/openfoodfacts/openfoodfacts-server/issues](https://github.com/openfoodfacts/openfoodfacts-server/issues)\n* API bugs: [https://github.com/openfoodfacts/openfoodfacts-server/labels/api](https://github.com/openfoodfacts/openfoodfacts-server/labels/api)\n* API milestone: [https://github.com/openfoodfacts/openfoodfacts-server/milestone/8](https://github.com/openfoodfacts/openfoodfacts-server/milestone/8)\n \n\n* * *\n\n#### Downloading Data\n\nIt is recommended to use the live API to get updated data about products. However, in some cases, you may need a snapshot. \nThey are available at:\n\n* {{PROTOCOL}}://world.{{DOMAIN_NAME}}/data (all data)\n* {{PROTOCOL}}://\\[countrycode\\].{{DOMAIN_NAME}}/data (data for a specific country).\n Example: [https://us.openfoodfacts.org/data](https://us.openfoodfacts.org/data) - (See the list of countries in the **Countries** taxonomy)\n \n\n* * *\n\n#### Exporting Data\n\n* File Encoding: The file encoding is Unicode UTF-8.\n* CSV API: The character that separates fields is < tab > (tabulation).\n* JSON\n \n\n* * *\n\n#### API Roadmap\n\nAPI Redesign: The API is far from perfect. It's been decided to fix the most urgent bugs and start planning for a new version, more compliant with modern API standards. We need all the help we can get. Please join us on the #api Slack channel.\n\n* Project API: Additives\n* Project API: States\n* Project API: Statistics\n* Project API: Statistics Entry Dates\n \n\n* * *\n\n#### Other Projects\n\n* Open Pet Food Facts\n* Open Beauty Facts\n* Open Products Facts\n \n\n* * *\n\n#### More topics\n\n* See [**5\\. Filtering**](#5Filtering) section for a list of all available API parameters.\n* See [**6\\. Understanding responses**](#6Understanding_responses) to figure out the response data fields.\n \n\n* * *" + "description": "As a developer, the **Open Food Facts API** allows you to get information about existing products and contribute to the products database. \n\nUsing the API, you can create apps to help people make better food choices and also provide data to enhance the database. \n\nCheck out how others are making use of the API at https://world.openfoodfacts.org/discover#reuses.\n\n---\n\n#### Data Disclaimer\nThe data contained in the Open Food Facts database are collected by users willing to selflessly contribute to the Open Food Facts initiative. \n\nTherefore, no guarantees can be made for the accuracy, completeness, or reliability of the information provided. The user assumes the entire risk related to the use of data. You (or your users) are very welcome to provide fixes using the __WRITE__ API.\n\n----\n\n#### Usage\nYou can use the Open Food Facts API for production use cases, as long as 1 API call equals 1 real scan by a user.\n\n----\n\n#### Do you know that we have ready-made SDKs for many programming languages ?\n\n\n\n----\n\n#### Domains\nYou can either use the global domain ({{PROTOCOL}}://world.{{DOMAIN_NAME}}) or the local domains ({{PROTOCOL}}://fr.{{DOMAIN_NAME}}, {{PROTOCOL}}://en.{{DOMAIN_NAME}} …) for your API queries.\n\n----\n\n#### Endpoint\nThe Open Food Facts base API endpoint is {{PROTOCOL}}://world.{{DOMAIN_NAME}}/api/{{API_VERSION}}\n\n----\n\n#### Version\nThe current version of the API is {{API_VERSION}} .\n\n----\n\n#### Authentication\n\n__READ and SEARCH operations__\n\nNo authentication is required.\n\nAdd a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.\n\nFor example: `User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com`\n\n__WRITE operations__ \n\nNo authentication is required for adding new products or adding images.\n\nBasic authentication is required for editing existing products. You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site. \n\nParameters:\n* `user_id`: YourUserID\n* `password`: YourPassword\n\n__Checking you're authentified__\n\nhttps://world.openfoodfacts.org/cgi/auth.pl\n\nThis endpoint returns status 200 or 403 if the user is authentified, either through the \"session\" cookie, or with the user_id and password parameters.\n\n----\n\n#### Environments\nYou can do READ / SEARCH operations on the `prod` environment running @ https://world.openfoodfacts.org.\n\nYou can do WRITE operations tests on the `dev` environment running @ https://world.openfoodfacts.net (user:`off`, password:`off`).\n\n----\n\n#### Security\nUse the SSL version of the API: {{PROTOCOL}}://world.{{DOMAIN_NAME}}\n\n----\n\n#### Error Codes\n* __Product does not exist__ - HTTP code 200 + \"status_verbose\" : \"product not found\" + \"Status\" : 0.\n The request format is correct, but the product code does not exist in the database.\n* __Wrong Password__ - HTTP code 200 + an HTML page with a link to log in.\n The request format is correct, but basic authentication is missing or the password entered is not correct.\n* __Server down__ - HTTP codes 502/503/500\n* __Redirect to another product__ - HTTP code 301\n\n__Disclaimer:__ The HTML code 404 is never thrown, even when a wrong password is entered. A feature request has been created and we are already working to fix this.\n\n----\n\n#### Rate limit\nThe API intended use is for apps, with one real user scan = one query. Automated queries are not supported. Please let us know in advance if you expect a high volume of calls. \n\nFor more information, see: https://world.openfoodfacts.org/data\n\n----\n\n#### Cache\nSome queries (facets) are caches. Should you need to disable the cache, you can pass the `nocache=1` parameter.\n\n#### Payload size reduction\nUsing the `fields=` parameter, you can reduce the response to only the fields you need.\n\n#### Preliminary Considerations\nThe API development is in progress. This has several implications:\n\n* Open Food Facts and food products are constantly evolving.\n* Assume that data is less reliable until the product is marked as complete. You might want to filter incomplete products to avoid issues (this is especially relevant for allergens or food intolerances). Let your end users know about this and encourage them to exercise caution. Be upfront about possible risks. You can use the following template to inform your users: _The data provided to you by this app are retrieved from the Open Food Facts database. No guarantees can be made for the accuracy, completeness, or reliability of the information provided. The data are provided “as is” and the originating source for the data (Open Food Facts) is not liable for any damages arising out of the use of the data._\n* Join our Slack Channel (https://slack-ssl-openfoodfacts.herokuapp.com) to get help, to share your thoughts, to let us know what you build with the API (contact@openfoodfacts.org or in the #API channel) or if you want to use WRITE operations.\n* You can also join the mailing list to be notified when improvements or changes are made to the API (we send only relevant information and very few e-mails. Don't worry, you won't be spammed). To join the mailing list, send an empty e-mail to api-subscribe@openfoodfacts.org to subscribe. \n\n----\n\n#### License\n* Do not send copyrighted photos or information using the API. Everything you send is OdBL for the data (https://opendatacommons.org/licenses/odbl/summary/index.html) and CC-BY-SA for the pictures (https://creativecommons.org/licenses/by-sa/4.0/). If you don't own the data, you bear all the legal consequences.\n* Mention Open Food Facts as the source of the data.\n* Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk).\n* Share any additions under the OdBL with the community. \n* By using any part of the API you have read and understood the license.\n\n----\n\n#### API Conventions\n* Fields that end with `_t` are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)\n* Fields that end with `_datetime` are dates in the ISO8601 format: yyyy-mm-ddThh:mn:ssZ\n* Fields that end with `_tags` are comma-separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)\n* Fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language\n* Fields that end with `_100g` correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product\n\n----\n\n#### Bugs\nDo not hesitate to file a bug if you find an issue in the API or need an improvement.\nYou can fill out the issue report on GitHub:\n\n* General bugs: https://github.com/openfoodfacts/openfoodfacts-server/issues\n* API bugs: https://github.com/openfoodfacts/openfoodfacts-server/labels/api\n* API milestone: https://github.com/openfoodfacts/openfoodfacts-server/milestone/8\n\n----\n\n#### Downloading Data\nIt is recommended to use the live API to get updated data about products. However, in some cases, you may need a snapshot. \nThey are available at:\n\n* {{PROTOCOL}}://world.{{DOMAIN_NAME}}/data (all data)\n* {{PROTOCOL}}://[countrycode].{{DOMAIN_NAME}}/data (data for a specific country).\n\n Example: https://us.openfoodfacts.org/data - (See the list of countries in the __Countries__ taxonomy)\n\n----\n\n#### Exporting Data\n* File Encoding: The file encoding is Unicode UTF-8.\n* CSV API: The character that separates fields is < tab > (tabulation).\n* JSON\n\n----\n\n#### API Roadmap\nAPI Redesign: The API is far from perfect. It's been decided to fix the most urgent bugs and start planning for a new version, more compliant with modern API standards. We need all the help we can get. Please join us on the #api Slack channel.\n\n* Project API: Additives\n* Project API: States\n* Project API: Statistics\n* Project API: Statistics Entry Dates\n\n----\n\n#### Other Projects\n\n* Open Pet Food Facts\n* Open Beauty Facts\n* Open Products Facts\n\n----\n\n\n#### More topics\n\n* See [__5. Filtering__](#5Filtering) section for a list of all available API parameters.\n* See [__6. Understanding responses__](#6Understanding_responses) to figure out the response data fields.\n\n---" }, { "name": "2. READ requests", @@ -1329,7 +1329,8 @@ }, { "key": "id", - "value": "ingredients_fr" + "value": "ingredients_fr", + "description": "You can also pass packaging_fr if you want to extract recycling instructions." }, { "key": "process_image", @@ -1494,7 +1495,7 @@ "url": { "raw": "" }, - "description": "__General information:__\n\n* `code` : 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.\n* `url` : url of the product page on Open Food Facts.\n* `creator` : contributor who first added the product.\n* `created_t` : date when the product was added (UNIX timestamp format).\n* `created_datetime` : date when the product was added (ISO8601 format: yyyy-mm-ddThh:mn:ssZ).\n* `last_modified_t` : date when the product page was last modified.\n* `last_modified_datetime`: date and time when the product was last modified.\n* `product_name` : name of the product.\n* `generic_name`: legal name of the product as regulated by the European authorities.\n* `quantity` : quantity and unit.\n\n---\n\n__Ingredients:__\n\n* `ingredients_text`\n* `traces`: List of substances that might cause allergies that are present in trace amount in the product (this does not include the ingredients, as they are not only present in trace amount). It is taxonomized with the allergens taxonomy.\n* `traces_tags`\n\n---\n\n__Packages:__\n\n* `packaging` : shape, material. Example: Cardboard\n* `packaging_tags`\n* `emb_codes` : packager code. Example: EMB 2013330\n* `emb_codes_tags`\n\n---\n\n__Brands:__\n\n* `brands`\n* `brands_tags`\n\n---\n\n__Categories:__\n\n* `categories`\n* `categories_tags`\n\n---\n\n__Location:__\n\n* `origins` : origins of ingredients\n* `origins_tags`\n* `first_packaging_code_geo` : coordinates corresponding to the first packaging code.\n* `manufacturing_places` : places where the product was manufactured or transformed.\n* `manufacturing_places_tags`\n* `cities`\n* `cities_tags`\n* `purchase_places`: country, state and/or city where the product can be purchased. For example: Paris, France.\n* `stores`: distributor name. Example: Tesco, Walmart, Carrefour.\n* `countries` : list of countries where the product is sold.\n* `countries_tags`\n\n---\n\n__Labels__\n\n* `labels`: Example: vegan, fat free, Kosher.\n* `labels_tags`\n\n---\n\n__Producer__\n\n* `producer`\n* `producer_product_id`\n* `producer_version_id`\n\n---\n\n__Value and Weight__\n\n* `net_weight_value`\n* `net_weight_unit`\n* `drained_weight_value`\n* `drained_weight_unit`\n* `volume_value`\n* `volume_unit`\n\n---\n\n__Images__\n\n* `image_url`\n* `image_small_url`: simplified version of the url. \n\n---\n\n__Energy__\n\n- Legacy\n\n * `energy_unit`: (string). The unit used in the `energy_value` field (example in JSON: \"energy_unit\":\"kJ\"). Possible values are \"kJ\" or \"kcal\".\n * `energy_value`: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in the unit specified in the field `energy_unit` (example in JSON: \"energy_value\":\"190\").\n\n- Preferred method\n\n * `energy-kj_unit`: (string). The unit used in the field energy-kj_value (example in JSON: \"energy_unit\":\"kJ\"). The only possible value is \"kJ\";\n * `energy-kj_value`: (string).  The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kJ (example in JSON: \"energy-kj_value\":\"190\").\n * `energy-kcal_unit`: (string). The unit used in the field energy-kcal_unit (example in JSON: \"energy_unit\":\"kcal\"). The only possible value is \"kcal\";\n * `energy-kcal_value`: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kcal (example in JSON: \"energy-kcal_value\":\"190\").\n\nAccording to the European regulation, the ratio between values calculated in kJ and values calculated in kcal may differ from the standard conversion ratio of 4.184 (because of carried rounding errors). Both values might appear on the same product. In that case, the value in kJ will be the one returned in the legacy `energy_unit` and `energy_value` fields. If only one unit was provided (kJ or kcal), this unit will be returned in the legacy `energy_unit` and `energy_value` fields.\n\n---\n\n__Additives:__\n\n* `additives_n` : number of food additives\n* `additives`\n* `additives_tags`\n\n---\n\n__Miscellaneous:__\n\n* `serving_size` : serving size in g (or ml)\n* `serving_quantity`\n* `no_nutriments` : indicates if the nutrition facts are shown on the product label.\n* `ingredients_text`\n* `allergens`\n* `traces`\n* `ingredients_from_palm_oil_n`\n* `ingredients_from_palm_oil`\n* `ingredients_from_palm_oil_tags`\n* `ingredients_that_may_be_from_palm_oil_n`\n* `ingredients_that_may_be_from_palm_oil`\n* `ingredients_that_may_be_from_palm_oil_tags`\n* `nutrition_grade_fr` : nutrition grade ('a' to 'e'). see https://world.openfoodfacts.org/nutriscore\n* `main_category`\n* `other_information`\n* `conservation_conditions`: Example: Keep in a dry place.\n* `recycling_instructions_to_recycle`\n* `recycling_instructions_to_discard`\n* `nutrition_grade_fr_producer`: declarative (printed on the packaging)\n* `recipe_idea`\n* `customer_service`: contact info of customer service.\n* `preparation`: how to cook the food: microwave, oven, which temperature...\n* `warning`: regulatory warning. Example: contains sorbitol.\n* `data_sources`: source of data imported from producers.\n* `nova_group`: system of grades for comparing the degree of processing of products. For more information, see: https://world.openfoodfacts.org/nova\n* `pnns_groups_1`: disregard. Used to improve the nutriscore calculation.\n* `pnns_groups_2`: disregard. Used to improve the nutriscore calculation.\n* `states`: if the product is complete or if there is any information missing.\n\n---\n\n__Environment__\nThe Eco-Score needs to be queried according to the country of the user. \nDue to the recent nature of the Eco-Score, the full APIs are documented in a separate document. \nhttps://docs.google.com/document/d/1_5AeofpXbaKY9Rd3eeWmHIrhJE8GiPQ-Mfx1SCvpzME/edit?usp=sharing\n\n__Other nutrition keys__\n\n* `carbon-footprint_100g` : carbon footprint (indicated on some products). The unit is absolute grams of C02. \n* `ph_100g` : pH (no unit)\n* `cocoa` : minimal cacao content of the product in %. __Important!__: Note the typo.\n* `fruits-vegetables-nuts_100g` : % of fruits, vegetables and nuts (excluding potatoes, yams, manioc)\n* `nutrition-score-fr_100g` : experimental nutrition score derived from the UK FSA score and adapted for the French market (formula defined by the team of Professor Hercberg)\n* `nutrition-score-uk_100g` : nutrition score defined by the UK Food Standards Administration (FSA).\nFor more information about the difference between the `fr` and `uk` nutri-scores see the __FAQ__ section of this documentation." + "description": "**General information:**\n\n* `code` : 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.\n* `url` : url of the product page on Open Food Facts.\n* `creator` : contributor who first added the product.\n* `created_t` : date when the product was added (UNIX timestamp format).\n* `created_datetime` : date when the product was added (ISO8601 format: yyyy-mm-ddThh:mn:ssZ).\n* `last_modified_t` : date when the product page was last modified.\n* `last_modified_datetime`: date and time when the product was last modified.\n* `product_name` : name of the product.\n* `generic_name`: legal name of the product as regulated by the European authorities.\n* `quantity` : quantity and unit.\n \n\n* * *\n\n**Ingredients:**\n\n* `ingredients_text`: Raw list of ingredients. This will get automatically parsed and get used to compute the Eco-Score. You can either request if (if it exists) or send it in a specific language, e.g: `ingredients_text_en`\n* `traces`: List of substances that might cause allergies that are present in trace amount in the product (this does not include the ingredients, as they are not only present in trace amount). It is taxonomized with the allergens taxonomy.\n* `traces_tags`\n \n\n* * *\n\n**Packages:**\n\n* `packaging` : shape, material. Example: Cardboard\n* `packaging_tags`\n* `packaging_text` : Recycling instructions as raw text eg: “Plastic bottle to recycle, Plastic cap to recycle”. This will get automatically parsed and get used to compute the Eco-Score. You can either request if (if it exists) or send it in a specific language, e.g: `packaging_text_en` for the above example\n* `emb_codes` : packager code. Example: EMB 2013330\n* `emb_codes_tags`\n \n\n* * *\n\n**Brands:**\n\n* `brands`\n* `brands_tags`\n \n\n* * *\n\n**Categories:**\n\n* `categories`\n* `categories_tags`\n \n\n* * *\n\n**Location:**\n\n* `origins` : origins of ingredients\n* `origins_tags`\n* `first_packaging_code_geo` : coordinates corresponding to the first packaging code.\n* `manufacturing_places` : places where the product was manufactured or transformed.\n* `manufacturing_places_tags`\n* `cities`\n* `cities_tags`\n* `purchase_places`: country, state and/or city where the product can be purchased. For example: Paris, France.\n* `stores`: distributor name. Example: Tesco, Walmart, Carrefour.\n* `countries` : list of countries where the product is sold.\n* `countries_tags`\n \n\n* * *\n\n**Labels**\n\n* `labels`: Example: vegan, fat free, Kosher.\n* `labels_tags`\n \n\n* * *\n\n**Producer**\n\n* `producer`\n* `producer_product_id`\n* `producer_version_id`\n \n\n* * *\n\n**Value and Weight**\n\n* `net_weight_value`\n* `net_weight_unit`\n* `drained_weight_value`\n* `drained_weight_unit`\n* `volume_value`\n* `volume_unit`\n \n\n* * *\n\n**Images**\n\n* `image_url`\n* `image_small_url`: simplified version of the url.\n \n\n* * *\n\n**Energy**\n\n* Legacy\n * `energy_unit`: (string). The unit used in the `energy_value` field (example in JSON: \"energy_unit\":\"kJ\"). Possible values are \"kJ\" or \"kcal\".\n * `energy_value`: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in the unit specified in the field `energy_unit` (example in JSON: \"energy_value\":\"190\").\n* Preferred method\n * `energy-kj_unit`: (string). The unit used in the field energy-kj_value (example in JSON: \"energy_unit\":\"kJ\"). The only possible value is \"kJ\";\n * `energy-kj_value`: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kJ (example in JSON: \"energy-kj_value\":\"190\").\n * `energy-kcal_unit`: (string). The unit used in the field energy-kcal_unit (example in JSON: \"energy_unit\":\"kcal\"). The only possible value is \"kcal\";\n * `energy-kcal_value`: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kcal (example in JSON: \"energy-kcal_value\":\"190\").\n\nAccording to the European regulation, the ratio between values calculated in kJ and values calculated in kcal may differ from the standard conversion ratio of 4.184 (because of carried rounding errors). Both values might appear on the same product. In that case, the value in kJ will be the one returned in the legacy `energy_unit` and `energy_value` fields. If only one unit was provided (kJ or kcal), this unit will be returned in the legacy `energy_unit` and `energy_value` fields.\n\n* * *\n\n**Additives:**\n\n* `additives_n` : number of food additives\n* `additives`\n* `additives_tags`\n \n\n* * *\n\n**Miscellaneous:**\n\n* `serving_size` : serving size in g (or ml)\n* `serving_quantity`\n* `no_nutriments` : indicates if the nutrition facts are shown on the product label.\n* `ingredients_text`\n* `allergens`\n* `traces`\n* `ingredients_from_palm_oil_n`\n* `ingredients_from_palm_oil`\n* `ingredients_from_palm_oil_tags`\n* `ingredients_that_may_be_from_palm_oil_n`\n* `ingredients_that_may_be_from_palm_oil`\n* `ingredients_that_may_be_from_palm_oil_tags`\n* `nutrition_grade_fr` : nutrition grade ('a' to 'e'). see [https://world.openfoodfacts.org/nutriscore](https://world.openfoodfacts.org/nutriscore)\n* `main_category`\n* `other_information`\n* `conservation_conditions`: Example: Keep in a dry place.\n* `recycling_instructions_to_recycle`\n* `recycling_instructions_to_discard`\n* `nutrition_grade_fr_producer`: declarative (printed on the packaging)\n* `recipe_idea`\n* `customer_service`: contact info of customer service.\n* `preparation`: how to cook the food: microwave, oven, which temperature...\n* `warning`: regulatory warning. Example: contains sorbitol.\n* `data_sources`: source of data imported from producers.\n* `nova_group`: system of grades for comparing the degree of processing of products. For more information, see: [https://world.openfoodfacts.org/nova](https://world.openfoodfacts.org/nova)\n* `pnns_groups_1`: disregard. Used to improve the nutriscore calculation.\n* `pnns_groups_2`: disregard. Used to improve the nutriscore calculation.\n* `states`: if the product is complete or if there is any information missing.\n \n\n* * *\n\n**Environment** \nThe Eco-Score needs to be queried according to the country of the user. \nDue to the recent nature of the Eco-Score, the full APIs are documented in a separate document. \n[https://docs.google.com/document/d/1_5AeofpXbaKY9Rd3eeWmHIrhJE8GiPQ-Mfx1SCvpzME/edit?usp=sharing](https://docs.google.com/document/d/1_5AeofpXbaKY9Rd3eeWmHIrhJE8GiPQ-Mfx1SCvpzME/edit?usp=sharing)\n\n**Other nutrition keys**\n\n* `carbon-footprint_100g` : carbon footprint (indicated on some products). The unit is absolute grams of C02.\n* `ph_100g` : pH (no unit)\n* `cocoa` : minimal cacao content of the product in %. **Important!**: Note the typo.\n* `fruits-vegetables-nuts_100g` : % of fruits, vegetables and nuts (excluding potatoes, yams, manioc)\n* `nutrition-score-fr_100g` : experimental nutrition score derived from the UK FSA score and adapted for the French market (formula defined by the team of Professor Hercberg)\n* `nutrition-score-uk_100g` : nutrition score defined by the UK Food Standards Administration (FSA). \n For more information about the difference between the `fr` and `uk` nutri-scores see the **FAQ** section of this documentation." }, "response": [] }, @@ -3610,9 +3611,6 @@ "request": { "method": "GET", "header": [], - "url": { - "raw": "" - }, "description": "* If you can't get the information on a specific product, you can get your user to send photos and data.\n* That will then be processed by Open Food Facts to get the computed result you want to show them.\n* You can implement the complete flow so that they get immediately the result with some effort on their side.\n* That will ensure user satisfaction\n\nhttps://docs.google.com/document/d/1_Y3tdgB8w3VkL6tXgjzPVmkmFiXsBfy0UfS6Mg3MkLs/edit" }, "response": [ @@ -3620,15 +3618,12 @@ "name": "New Request", "originalRequest": { "method": "GET", - "header": [], - "url": { - "raw": "" - } + "header": [] }, - "_postman_previewlanguage": "Text", - "header": [], + "_postman_previewlanguage": null, + "header": null, "cookie": [], - "body": "" + "body": null } ] }, @@ -3637,9 +3632,6 @@ "request": { "method": "GET", "header": [], - "url": { - "raw": "" - }, "description": "* If you can't get the information on a specific product, you can get your user to send photos and data.\n* That will then be processed by Open Food Facts to get the computed result you want to show them.\n* You can implement the complete flow so that they get immediately the result with some effort on their side.\n* That will ensure user satisfaction\n\nhttps://docs.google.com/document/d/1_5AeofpXbaKY9Rd3eeWmHIrhJE8GiPQ-Mfx1SCvpzME/edit?usp=sharing" }, "response": [] @@ -3649,9 +3641,6 @@ "request": { "method": "GET", "header": [], - "url": { - "raw": "" - }, "description": "* If you can't get the information on a specific product, you can get your user to send photos and data.\n* That will then be processed by Open Food Facts to get the computed result you want to show them.\n* You can implement the complete flow so that they get immediately the result with some effort on their side.\n* That will ensure user satisfaction\n\nhttps://docs.google.com/document/d/1avnxJr8_m6OjRBt0vgwBzlzaZB7Q6z14t0taMKIrkp0/edit" }, "response": [] @@ -3814,10 +3803,10 @@ ] } }, - "_postman_previewlanguage": "Text", - "header": [], + "_postman_previewlanguage": null, + "header": null, "cookie": [], - "body": "" + "body": null } ] },