Changes

Jump to navigation Jump to search
4,690 bytes added ,  13:12, 27 September 2021
Line 1: Line 1: −
= Product Attributes =
     −
== Introduction ==
+
= 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.
 
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.
Line 7: Line 6:  
We are introducing Product Attributes to support [[Project:Personalized Search]], but it aims to enable many more uses.
 
We are introducing Product Attributes to support [[Project:Personalized Search]], but it aims to enable many more uses.
   −
== What it is ==
+
= 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.
 
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.
Line 15: Line 14:  
The human friendly data makes it easy to present the information to users, with translations.
 
The human friendly data makes it easy to present the information to users, with translations.
   −
== Benefits ==
+
= Benefits =
    
Product Attributes greatly simplifies how apps can use and display product information, while at the same time offering more flexibility.
 
Product Attributes greatly simplifies how apps can use and display product information, while at the same time offering more flexibility.
Line 24: Line 23:  
* If desired, apps can decide to use new product attributes added on the server without requiring app changes
 
* If desired, apps can decide to use new product attributes added on the server without requiring app changes
   −
== Examples of Product Attributes ==
+
= 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:
 
Product Attributes are organized in sections:
Line 35: Line 36:  
** Few additives (0 additives = 100%)
 
** Few additives (0 additives = 100%)
 
* Allergens
 
* Allergens
** for each allergen (not present = 100%, present = 0%, traces = 10% (low threshold that will exclude products if "No [allergen]" is marked as mandatory by the user)
+
** 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
 
* Ingredients
 
** Vegan
 
** Vegan
Line 43: Line 44:  
** Organic
 
** Organic
 
** Fair trade
 
** Fair trade
 +
* Environment
 +
** Eco-Score
    
The list can be quite long and new Product Attributes can be added over time.
 
The list can be quite long and new Product Attributes can be added over time.
   −
== API ==
+
= 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.
   −
=== Request ===
+
e.g. [https://world.openfoodfacts.org/api/v0/attribute_groups]
   −
Apps can request Product Attributes through API queries (/product or /search) by including "attributes_[language code]" (or "attributes_data" to get only the machine readable data) in the "fields" parameter.
+
It returns a JSON array of attribute groups that each contain an array of attributes.
   −
=== Response ===
+
Attribute groups keys:
 +
* id - e.g. nutritional_quality
 +
* name - e.g. Nutritional quality
 +
* warning (optional)
 +
* attributes: array of attributes
   −
For each product returned, a new "attributes_[language code]" or "attributes_data" field is added, containing an array of sections (to regroupe attributes, like all allergens) that each contain an 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
   −
==== Section format ====
+
== 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
 
* id - e.g. nutritional_quality
Line 62: Line 85:  
* attributes - Array of attributes
 
* attributes - Array of attributes
   −
==== Attribute format ====
+
=== Attribute format ===
    
* id - e.g. nutriscore
 
* id - e.g. nutriscore
Line 68: Line 91:  
* status - known, unknown, not-applicable : indicate if we have enough data to decide if the requirement is met
 
* 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)  
 
* match - 0 to 100 - indicate how well the product matches the requirement (100 = 100% match)  
* icon_url
+
* icon_url (optional)
 
* title - short title corresponding to the value of the attribute - e.g. "Nutri-Score D"
 
* title - short title corresponding to the value of the attribute - e.g. "Nutri-Score D"
* description_short - very short description - e.g. "Bad nutritional quality"
+
* 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_long - small text (1 or 2 paragraphs, possibly with bullet points introduced by dashes)
+
* description_short (optional) - very short description - e.g. "Bad nutritional quality"
* recommendation_short - "Reduce"
+
* description (optional) - small text (1 or 2 paragraphs, possibly with bullet points introduced by dashes) - intended to be displayed under the description_short
* recommendation_long
+
* recommendation_short (optional) - "Reduce"
* official_link_title - "Nutri-Score page on Santé publique France"
+
* recommendation_long (optional)
* official_link_url
+
* official_link_title (optional) - "Nutri-Score page on Santé publique France"
* off_link_title
+
* official_link_url (optional)
* off_link_url
+
* 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:
 +
 
 +
<pre>
 +
{
 +
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"
 +
}
 +
]
 +
}
 +
]
 +
}
 +
}
 +
</pre>
   −
== Example uses ==
+
= Example uses =
   −
=== Personalized search ===
+
== Personalized search ==
   −
Users are being asked to enter preferences for each attribute (or a specific subset of attributes), for instance:
+
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.
 
* The product is vegetarian - [ ] Not important, [ ] Important, [ ] Very important, [ ] Mandatory.
Line 89: Line 186:  
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.
 
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.
   −
=== Information and recommendations ===
+
For each attribute, the server computes a match that goes from 0 to 100 (perfect match).
 +
 
 +
The filtering and ranking is done on the client, the preferences are not sent to the server.
 +
 
 +
Client-side (Open Food Facts website + Smoothie app) 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.
 
Apps can use the returned human friendly data of each attribute to show some explanations and/or recommendations to users.
Line 97: Line 206:  
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).
 
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).
   −
=== Personalized information and recommendations ===
+
=== 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.
 
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
 +
 +
= Product Attributes for Contributors =
 +
 +
* Special [[Product Attributes for Contributors]]
    
[[Category:Project:Personalized_Search]]
 
[[Category:Project:Personalized_Search]]
 
[[Category:ProductOpener]]
 
[[Category:ProductOpener]]

Navigation menu