Product Attributes

Introduction

Products Attributes is a new way to query the Open Food Facts API to make it easier for clients (like apps but also the OFF web site) to filter and rank search results according to the user preference, and to explain to users how well the products match their preferences.

We are introducing Product Attributes to support Project:Personalized Search, but it aims to enable many more uses.

What it is

Product Attributes is a standardized way to get information on how well a product matches a given requirement (e.g. the product has good nutritional quality, it is vegetarian, does not contain eggs, is organic etc.). The information is available as machine readable data (e.g. 100% match) and internationalized human friendly data ("This product has Nutri-Score E, it is recommended to reduce your consumption of products graded D and E"). For both the machine readable and the human friendly data, the format of the data is always the same, for all requirements.

The machine readable data makes it easy for apps to filter and rank search results in their own way, or according to the preferences of users.

The human friendly data makes it easy to present the information to users, with translations.

Benefits

Product Attributes greatly simplifies how apps can use and display product information, while at the same time offering more flexibility.

• Apps don't have to add special code to process each type of requirements (e.g. looking at the array of ingredients and additives, the values of nutrients etc.)
• Apps don't need to load and update taxonomies to interpret the returned data
• Translations are managed by the server, and we can use Crowdin to crowdsource them in many languages
• If desired, apps can decide to use new product attributes added on the server without requiring app changes

Current list of available Product Attributes

See also the list of proposed attributes at the end of this document.

Product Attributes are organized in sections:

• Nutritional quality
  • Nutri-Score (A = 100%, E = 0%)
  • Low salt / Low sugar / Low fat / Low saturated fat (based on the Nutrition Traffic Lights): 1 product attribute for each so that users who are concerned only by salt can specify it.
• Transformation
  • No ultra-processed foods (NOVA 1 & 2 = 100%, 4 = 0%)
  • Few additives (0 additives = 100%)
• Allergens
  • for each allergen (not present = 100%, present = 0%, traces = 20% (low threshold that will exclude products if "No [allergen]" is marked as mandatory by the user)
• Ingredients
  • Vegan
  • Vegetarian
  • Palm oil
• Labels
  • Organic
  • Fair trade
• Environment
  • Eco-Score

The list can be quite long and new Product Attributes can be added over time.

API

List and descriptions of available product attributes

App can get the list of all available product attributes at the /api/v2/attribute_groups or /api/v2/attribute_groups_[language code] endpoints.

e.g. [1]

It returns a JSON array of attribute groups that each contain an array of attributes.

Attribute groups keys:

• id - e.g. nutritional_quality
• name - e.g. Nutritional quality
• warning (optional)
• attributes: array of attributes

Attributes keys:

• id - e.g. "nutriscore",
• name - e.g. Nutri-Score"
• setting_name - e.g. "Good nutritional quality (Nutri-Score)" (in the form of a requirement)
• setting_note (optional) - e.g. extra detail that can be shown in user preferences

Request

Apps can request Product Attributes through API queries (/api/v2/product or /api/v2/search) by including "attribute_groups" or "attribute_groups_[language code]" (or "attribute_groups_data" to get only the machine readable data) in the "fields" parameter.

Response

For each product returned, the corresponding field is added, containing an array of groups (to regroup attributes, like all allergens) that each contain an array of attributes.

Attribute group format

• id - e.g. nutritional_quality
• name - Name of the group of attributes e.g. "Nutritional quality"
• attributes - Array of attributes

Attribute format

• id - e.g. nutriscore
• name - e.g. "Nutri-Score"
• status - known, unknown, not-applicable : indicate if we have enough data to decide if the requirement is met
• match - 0 to 100 - indicate how well the product matches the requirement (100 = 100% match)
• icon_url (optional)
• title - short title corresponding to the value of the attribute - e.g. "Nutri-Score D"
• details (optional) - explains how the match was computed, what triggered the match value (e.g. for vegan, list of ingredients that may not be vegan)
• description_short (optional) - very short description - e.g. "Bad nutritional quality"
• description (optional) - small text (1 or 2 paragraphs, possibly with bullet points introduced by dashes) - intended to be displayed under the description_short
• recommendation_short (optional) - "Reduce"
• recommendation_long (optional)
• official_link_title (optional) - "Nutri-Score page on Santé publique France"
• official_link_url (optional)
• off_link_title (optional)
• off_link_url (optional)

Example

• Request: https://world.openfoodfacts.org/api/v2/product/3700214614266?fields=product_name,code,attribute_groups_en
• Response:

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

Example uses

Personalized search

On the client, users are being asked to enter preferences for each attribute (or a specific subset of attributes), for instance:

• The product is vegetarian - [ ] Not important, [ ] Important, [ ] Very important, [ ] Mandatory.

Based on the users preferences and the "match" key of the Product Attributes, apps can exclude some results (e.g. if a mandatory requirement is not fully met) and re-rank search results.

The filtering and ranking is done on the client, the preferences are not sent to the server.

Sample client-side algorithm to compute a user defined sort key:

• for each requirement in user preferences
  • if requirement is mandatory, score = score + match * 4
    • and exclude product is match is less than 20%
  • if requirement is very important, score = score + match * 2
  • if requirement is important, score = score + match

Information and recommendations

Apps can use the returned human friendly data of each attribute to show some explanations and/or recommendations to users.

As the data is always returned in the same format for each attribute, apps can also decide to display all product attributes returned by the API (even if the app is not aware of them).

Apps can also decide to display some attributes in their own way (using the more attribute specific data that is returned by other fields in the API).

Possible display

Apps can display the attribute icon (that depends on both the attribute type and on how well the product matches the requirement) + the attribute short descriptions and recommendation, with an easy way to display the longer descriptions, recommendations and links.

Attributes icons should be cached if possible (and apps could also pre-cache existing icons in the install package).

Personalized information and recommendations

Based on users preferences, apps can filter and/or re-order the product attributes to first show the information that the user is the most interested in.

Apps can decide to keep the sections of attribute groups (e.g. keeping all allergens together) or not. In the former case, apps would thus first reorder the sections, and then the attributes in each section.

Proposals for new product attributes

You can add / discuss proposals for new product attributes below.

Notes:

• Product attributes need to be put in the form of a requirement that can be matched or not
  • e.g. "the product has good nutritional quality", "the product does not contain XYZ"
• Adding attributes has a price: to compute them, to return them (e.g for Personal Search the client needs to get all the attributes of potentially hundreds of products for every search query), and also to display attribute choices to users without confusing them.

Proposals:

• climate gas emissions
  • in t CO2-eq per kg
• Origin Country
  • in percent of weight of the final product
• Special Product Attributes for Contributors