Changes

Jump to navigation Jump to search
1,828 bytes added ,  13:12, 27 September 2021
Line 23: 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 30: Line 32:  
** Nutri-Score (A = 100%, E = 0%)
 
** 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.
 
** 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.
* climate gas emissions
  −
** in t CO2-eq per kg
   
* Transformation
 
* Transformation
 
** No ultra-processed foods (NOVA 1 & 2 = 100%, 4 = 0%)
 
** No ultra-processed foods (NOVA 1 & 2 = 100%, 4 = 0%)
 
** 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 44: Line 44:  
** Organic
 
** Organic
 
** Fair trade
 
** Fair trade
* Origin Country
+
* Environment
** in percent of weight of the final product
+
** 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.
 +
 +
e.g. [https://world.openfoodfacts.org/api/v0/attribute_groups]
 +
 +
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 ==
 
== Request ==
   −
Apps can request Product Attributes through API queries (/product or /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.
+
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 ==
 
== Response ==
Line 71: 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"
* details - explains how the match was computed, what triggered the match value (e.g. for vegan, list of ingredients that may not be vegan)
+
* 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 - very short description - e.g. "Bad nutritional quality"
+
* description_short (optional) - very short description - e.g. "Bad nutritional quality"
* description_long - small text (1 or 2 paragraphs, possibly with bullet points introduced by dashes)
+
* 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 - "Reduce"
+
* recommendation_short (optional) - "Reduce"
* recommendation_long
+
* recommendation_long (optional)
* official_link_title - "Nutri-Score page on Santé publique France"
+
* official_link_title (optional) - "Nutri-Score page on Santé publique France"
* official_link_url
+
* official_link_url (optional)
* off_link_title
+
* off_link_title (optional)
* off_link_url
+
* off_link_url (optional)
    
=== Example ===
 
=== Example ===
   −
* Request: https://world.openfoodfacts.org/api/v0/product/3700214614266?fields=product_name,code,attribute_groups_en
+
* Request: https://world.openfoodfacts.org/api/v2/product/3700214614266?fields=product_name,code,attribute_groups_en
 
* Response:
 
* Response:
   Line 165: Line 185:     
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.
 +
 +
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.
 
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:
+
Client-side (Open Food Facts website + Smoothie app) algorithm to compute a user defined sort key:
    
* for each requirement in user preferences
 
* for each requirement in user preferences
Line 195: Line 217:     
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.
 
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