ProductOpener::Attributes - Generate product attributes that can be requested through the API
Apps can request through the API product attributes that are returned in the same structured format for all attributes.
See https://wiki.openfoodfacts.org/Product_Attributes
If new attributes are added, make sure *to update the list of fields* fetched from MongoDB in Display.pm (in search_and_display_products subroutine).
The list of attribute groups ids and the attribute ids they contained is defined in the Config.pm file
e.g.
$options{attribute_groups} = [ [ "nutritional_quality", ["nutriscore"] ], [ "processing", ["nova","additives"] ], [..]
List all available attribute groups and attributes, with strings (names, descriptions etc.) in a specific language, and return them in an array of attribute groups.
This is used in particular for clients of the API to know which preferences they can ask users for, and then use for personalized filtering and ranking.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
The return value is a reference to an array of attribute groups that contains individual attributes.
The return value is cached for each language in the %localized_attribute_groups hash.
Create a new attribute group and initialize some fields (e.g. strings like description, description_short etc.)
The initialization values for the fields are not dependent on a specific product.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
If $target_lc is equal to "data", no strings are returned.
A reference to the created attribute group object.
- Name - e.g. "Allergens" - Warning - Short description - Description
Create a new attribute and initialize attributes fields (e.g. strings like description, description_short etc.) for a specific attribute if the corresponding values are defined in the .po translation files.
The initialization values for the fields are not dependent on a specific product.
Some of them may be overridden later (e.g. the title and description) based on how the attribute matches for the specific product.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
If $target_lc is equal to "data", no strings are returned.
A reference to the created attribute object.
- name: e.g. "Nutri-Score" - setting_name: e.g. "Good nutritional quality (Nutri-Score)" - icon_url - panel_id: Linked knowledge panel (optional)
Attributes fields (e.g. strings like description, description_short etc.) can be defined in the .po translation files for a given attribute regardless of the attribute value, or can be specific to a particular value.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
e.g. description, description_short
String id from the msgctxt field in the .po files e.g. "attribute_labels_fair_trade_yes_description_short"
Computes a nutritional quality attribute based on the Nutri-Score.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
Different countries can have different versions of the Nutri-Score at a given time. e.g. in early 2024, France does not use the new Nutri-Score 2023 yet, while other countries do.
The return value is a reference to the resulting attribute data structure.
To differentiate products more finely, the match is based on the Nutri-Score score that is used to define the Nutri-Score grade from A to E.
- Nutri-Score A: 80 to 100% - Nutri-Score B: 61 to 80%
Computes an environmental impact attribute based on the Eco-Score.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
The Eco-Score depends on the country of the consumer (as the transport bonus/malus depends on it)
The return value is a reference to the resulting attribute data structure.
To differentiate products more finely, the match is based on the Eco-Score score that is used to define the Eco-Score grade from A to E.
- Eco-Score A: 80 to 100 - Eco-Score B: 60 to 79 - Eco-Score C: 40 to 59 - Eco-Score D: 20 to 39 - Eco-Score E: 0 to 19
Computes an environmental impact attribute based on the Forest Footprint.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
The return value is a reference to the resulting attribute data structure.
The match is based on the forest footprint that is used to define the forest footprint grade from A to E.
- Forest footprint A: < 0.5 m² / kg of food - Forest footprint B: < 1 m² / kg of food - Forest footprint C: < 1.5 m² / kg of food - Forest footprint D: < 2 m² / kg of food - Forest footprint E: >= 2 m² / kg of food
If the forest footprint is not computed, we mark it as non-computed and make the match 100%.
Computes a processing attribute based on the Nova group.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
The return value is a reference to the resulting attribute data structure.
- NOVA 1: 100% - NOVA 2: 100% - NOVA 3: 75% - NOVA 4: 0%
Computes a processing attribute based on the number of additives.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
The return value is a reference to the resulting attribute data structure.
- 0 additive: 100% - 1 to 4 additives: 80% to 20% - 5 or more additives: 0%
Checks if the product has a specific tag (e.g. a label)
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
e.g. labels, categories, origins
e.g. en:organic
The return value is a reference to the resulting attribute data structure.
- 100% if the product has the requested tag - 0% if the product does not have the requested tag
Checks if the product has a nutrient in a low or high quantity.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
"low" or "high"
e.g. "salt", "sugars", "fat", "saturated-fat"
The return value is a reference to the resulting attribute data structure.
For "low" levels:
- 100% if the nutrient quantity is 0% - 80% if the nutrient quantity is the upper threshold for the low traffic light - 20% if the nutrient quantity is the lower threshold for the high traffic light - 0% if the nutrient quantity is twice the lower threshold for the high traffic light
Traffic lights levels are defined in Food.pm:
@nutrient_levels = ( ['fat', 3, 20 ], ['saturated-fat', 1.5, 5], ['sugars', 5, 12.5], ['salt', 0.3, 1.5], );
Checks if the product contains or may contain traces of an allergen.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
"en:gluten", "en:sulphur-dioxide-and-sulphites" : allergen ids from the allergens taxonomy
The return value is a reference to the resulting attribute data structure.
100: no indication of the allergen or trace of the allergen 20: may contain the allergen as a trace 0: contains allergen
Checks properties derived from ingredients analysis (e.g. vegetarian, vegan, palm oil free)
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
There are currently 2 types of ingredients analysis:
- if $analysis contains "-free" at the end (e.g. palm-oil-free), ingredients_analysis_tags contains values like: contains-palm-oil, may-contain-palm-oil, palm-oil-free and palm-oil-content-unknown
- otherwise, for values like vegan and vegetarian, it contains values like: vegan, non-vegan, maybe-vegan, vegan-status-unknown
The return value is a reference to the resulting attribute data structure.
For "low" levels:
- 100% if the property matches - 20% if the property may match - 0% if the property does not match
Add an attribute to a given attribute group, if the attribute is defined.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
e.g. nutritional_quality, allergens, labels
Compute all attributes for a product, with strings (descriptions, recommendations etc.) in a specific language, and return them in an array of attribute groups.
Loaded from the MongoDB database, Storable files, or the OFF API.
Returned attributes contain both data and strings intended to be displayed to users. This parameter sets the desired language for the user facing strings.
If $target_lc is equal to "data", no strings are returned.
Needed for some country specific attributes like the Eco-Score.
Defines how some attributes should be computed (or not computed)
- skip_[attribute_id] : do not compute a specific attribute
Attributes are returned in the "attribute_groups_[$target_lc]" array of the product reference passed as input.
The array contains attribute groups, and each attribute group contains individual attributes.