1,083
edits
Changes
Jump to navigation
Jump to search
mLine 1:
Line 1: − = Product Attributes = − == Introduction ==+ Line 7:
Line 6: − == What it is ==+ Line 15:
Line 14: − == Benefits ==+ Line 24:
Line 23: − == Examples of Product Attributes ==+ Line 50:
Line 49: − == API ==+ − === Request ===+ − === Response ===+ − ==== Attribute group format ====+ Line 66:
Line 65: − ==== Attribute format ====+ Line 84:
Line 83: − ==== Example ====+ Line 157:
Line 156: − == Example uses ==+ − === Personalized search ===+ Line 177:
Line 176: − === Information and recommendations ===+ Line 185:
Line 184: − ==== Possible display ====+ Line 191:
Line 190: − === Personalized information and recommendations ===+
no edit summary
= 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.
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 =
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.
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 =
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.
* 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 =
Product Attributes are organized in sections:
Product Attributes are organized in sections:
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 =
== 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 (/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.
== 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.
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
* attributes - Array of attributes
* attributes - Array of attributes
=== Attribute format ===
* id - e.g. nutriscore
* id - e.g. nutriscore
* off_link_url
* off_link_url
=== Example ===
* Request: https://world.openfoodfacts.org/api/v0/product/3700214614266?fields=product_name,code,attribute_groups_en
* Request: https://world.openfoodfacts.org/api/v0/product/3700214614266?fields=product_name,code,attribute_groups_en
</pre>
</pre>
= 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:
On the client, users are being asked to enter preferences for each attribute (or a specific subset of attributes), for instance:
** if requirement is important, score = score + match
** 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.
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).
=== 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.
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).
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.