Open Food Facts - Dart

Dart package for the Open Food Facts API. Free and Easy access to more than 2.9 million food products information from all around the world. Open Food Facts is powered by contributors from around the world and is constantly growing thanks to them.

General principles, how does it work ?

We use the ability of the Open Food Facts API to return products results in JSON, we then generate easily understandable objects structures to make it simple for you to use.

This plugin also allows you to edit a product or upload a new one to Open Food Facts. Using the same simple product structure you can create a product object or edit an existing one and send it to the API using a single function.

Migrating from 2.x.x to 3.x.x (breaking changes)

• Starting with version 3.0.0, we now enforce all clients to provide a valid user agent. For this, please ensure to set the SDK before using any other functionality:

OpenFoodAPIConfiguration.userAgent = UserAgent(
  name: '<Name of your app>',
);

• QueryType has been deleted. Now, for API calls you have to provide a UriProductHelper parameter. By default it will point you to openfoodfacts/prod.

• For RobotoffAPIClient.getRandomInsights and RobotoffAPIClient.getQuestions, a list of countries instead of a single country as parameter.

• Use OpenFoodFactsCountry.fromOffTag instead of CountryHelper.fromJson.

• OpenFoodAPIClient.getOrderedNutrients now uses a OpenFoodFactsCountry parameter instead of a 2-letter country code.

• Methods getProductImageRootUrl and getBarcodeSubPath are moved to UriProductHelper from ImageHelper

• Method buildUrl renamed as getLocalizedProductImageUrl in ImageHelper

• Removal of deprecated code.

Migrating from 1.x.x to 2.x.x (breaking changes)

• Now the only entry point is import 'package:openfoodfacts/openfoodfacts.dart';
  • replace all your instances of import 'package:openfoodfacts/...'; with a single import 'package:openfoodfacts/openfoodfacts.dart';
• If you used State from product_state.dart, you have to rename it to ProductState
• If you used Level from nutrient_levels.dart, you have to rename it to NutrientLevel
• Removed deprecated classes:
  • Page
  • ProductListQueryConfiguration
  • ToBeCompletedConfiguration
• Removed deprecated fields and methods in Nutriments
  • all the single nutrient value fields were removed - use getValue and setValue instead
  • instead of getUnit use nutrient.typicalUnit

Usage

Installation

Follow the installing instructions on pub.dev.

How to authenticate

For most queries no authentication is required! :) Though we recommend to set a User-Agent to not to be blocked by mistake.

Setup (Optional)

At the beginning of the app you can define some global settings so that they don't need to be specified in each query. You can override these static values at any time in the app lifecycle.

import 'package:openfoodfacts/openfoodfacts.dart';

OpenFoodAPIConfiguration.userAgent = UserAgent(name: 'Your app name', url: 'Your url, if applicable');

OpenFoodAPIConfiguration.globalLanguages = <OpenFoodFactsLanguage>[
  OpenFoodFactsLanguage.ENGLISH
];

OpenFoodAPIConfiguration.globalCountry = OpenFoodFactsCountry.FRANCE;

All possible configurations can be found here.

Features

Code examples for the following tasks:

Reading data

• Querying a product
• Recommended Daily Intakes
• Search for products
  • By name
  • By brand, stores, ingredients, All filter
  • By category (Pnns2)
  • By vegan, vegetarian or/and palm oil status
• Autocompletion for user inputs, by giving suggestions for (Labels, categories, ingredients, additives, traces and other TagType's)
• Get the nutrient hierarchy specific to a country, localized
• Get product freshness
• Notes on advanced languages mechanics

Writing data

• Managing user accounts guide (Read this first)
  • Let your users login
  • Let your users register on Open Food Facts
  • Reset user password
  • Get contribution data about a user
• Save product to Open Food Facts (edit or add)
• Images
  • Send images
  • rotate
  • crop
  • select, unselect with language awareness
  • extract Ingredients
  • extract Packaging

Robotoff support

Robotoff it the Open Food Facts AI which analyze every new pictures to extract new data.

• get Insights
  • random
  • for a product
• get Questions to confirm
  • random
  • for a product
• post Insight Annotation

Folksonomy Engine

Folksonomy is adding several kinds of new individual data properties to Open Food Facts or Open Products Facts.

• get Taxonomy Packagings
• get Taxonomy Packaging Shapes
• get Taxonomy Packaging Materials
• get Taxonomy Packaging Recycling
• get Taxonomy Nova
• get Taxonomy Categories
• get Taxonomy Additives
• get Taxonomy Allergens
• get Taxonomy Countries
• get Taxonomy Ingredients
• get Taxonomy Labels
• get Taxonomy Languages
• get Taxonomy Origins
• get general Taxonomy
• get taxonomy translation uri

Contributing data

Handle Open Food Facts accounts

Some queries which modify or enter data need a user account to validate this request. There are multiple ways to handle user accounts:

1. Let your users login / create Open Food Facts user accounts (Recommended)
2. Create a global user for your app through which all requests run

Currently there is no OAuth workflow, therefor a user is just a User object in this package. So you need to get the username as well as the password from the users and store it somewhere save. For Flutter apps we recommend using the flutter_secure_storage package

For the user to be taken into account you have mount a global user at one point in your app lifecycle:

  OpenFoodAPIConfiguration.globalUser = User(
    userId: 'myUsername',
    password: 'myPassword',
  );

Regardless if you are using a global app or accounts per user. After mounting this, the user will be added to queries where the user can be attributed.

Some methods in OpenFoodAPIClient require to pass a User, there you can access the before mounted user with:

 OpenFoodAPIClient.thisNeedsAnUser(
  user: OpenFoodAPIConfiguration.globalUser,
  ...
 );

Further examples:

• Create users
• Check if the user credentials are correct
• Request a password reset email

If your users do not expect a specific result immediately (eg. Inventory apps)

• Send photos (front/nutrition/ingredients/packaging): most painless thing for your users
• The Open Food Facts AI Robotoff will generate some derived data from the photos
• Overtime, other apps, and the Open Food Facts community will fill the data gaps

If your users do expect a result immediately (eg Nutrition apps, Scoring apps…)

• Send nutrition facts + category > get the Nutri-Score
• Send ingredients > get the NOVA group (about food ultra-processing), additives, allergens, normalized ingredients, vegan, vegetarian…
• Send category (strict minimum) + labels + origins of ingredients + packaging (photo and text) > get the Eco-Score (about environmental impact)

Open Data License

The database in under the OdBL. This means attributing the source and also contributing back any additions (photos, data), which this package makes easy to do. You can check the terms of use here : Terms of use.

Useful recourses

• List of new APIs to implement: github.com/openfoodfacts/api-documentation/issues
• New OpenAPI documentation: pub.dev/documentation/openfoodfacts/latest/index.html
• Most of our operations are coordinated through our Slack which you can join here : Open Food Facts Slack.

Contribute to the package

If found a bug or missing features in this package, please open an issue for it.

• Issue Tracker: github.com/openfoodfacts/openfoodfacts-dart/issues
• Source Code: github.com/openfoodfacts/openfoodfacts-dart

Support

If you are having issues, that go beyond the scope of this package, please write to us on Slack or send us an email at contact@openfoodfacts.org

Testing

Execute the following command from the root of the repository to run the tests:

dart test

Applications using this SDK

Official application

Open Food Facts (Codename Smoothie) is the official app developed by Open Food Facts, which is available on Android and iOS. The source code is also available on GitHub.

Third party applications

Feel free to open a PR to add your application in this list.

• Glutten Scan. Android / iOS
• Halal & Healthy. Android / iOS
• Fitness Tracker. Android
• All public repositories using this package

Authors

Thanks to Alexander Schacht and Primaël Quémerais for the initial creation of this package.

Contributors