openapi: 3.2.0 info: title: Open Food Facts Open API V3 - under development Product… description: 'As a developer, the Open Food Facts API allows you to get information and contribute to the products database. You can create great apps to help people make better food choices and also provide data to enhance the database. **IMPORTANT**: Please read the API introduction before using this API. **WARNING** v3 is under development and you should expect changes The current version of API v3 is v3.4 See the change log for the API and product schema' termsOfService: https://world.openfoodfacts.org/terms-of-use contact: name: Open Food Facts url: https://slack.openfoodfacts.org/ email: reuse@openfoodfacts.org license: name: License (MIT, Apache 2.0, etc) url: https://opendatacommons.org/licenses/odbl/summary/index.html version: '3' servers: - url: https://world.openfoodfacts.org description: prod - description: dev url: https://world.openfoodfacts.net security: - userAgentAuth: [] tags: - name: Product Attributes description: Endpoints for retrieving product attribute groups and user preference importance values. paths: /api/v3/preferences: get: summary: Get List of Preference Importance Values description: 'These parameters are used to compute the product preferences score. for an overview see Explanation on Product Attributes"' tags: - Product Attributes operationId: get-api-v3-preferences responses: '200': description: OK content: application/json: schema: allOf: - title: Response status type: object description: A response object to describe if a READ or WRITE request was successful or not, and if there were errors or warnings, and what the impact of those errors or warnings was. examples: - status: success_with_errors result: id: product_updated name: Product updated lc_name: Produit mis à jour errors: - message: id: sugars_higher_than_carbohydrates name: Sugars higher than carbohydrates lc_name: Sucres plus élevés que les glucides description: Sugars (40g) are higher than carbohydrates (35g). lc_description: Les sucres (40g) sont plus élévés que les glucdes. field: id: nutriment.sugars value: '40' impact: id: nutrients_not_updated name: Nutrients not updated lc_name: Nutriments non mis à jour description: The nutrients were not updated. lc_description: Les nutriments n'ont pas été mis à jour. properties: status: type: string enum: - success - success_with_warnings - success_with_errors - failure description: 'Overall status of the request: whether it failed or succeeded, with or without warnings or errors.' result: type: object description: 'Overall result of the request (e.g. a product has been created)' properties: id: type: string description: Identifier of a response result entry name: type: string description: Name of the response result entry in English. lc_name: type: string description: Name of the response result entry in the language specified in tags_lc, if supplied. warnings: type: array description: List of warnings. Warnings are used to alert about something that may be wrong, but is not necessarily wrong (e.g. a nutrient value that is unexpectedly high). items: title: Warning or error message x-stoplight: id: eakkz8p7qfoj0 type: object description: Describes a warning or error for a READ or WRITE request, which field triggered it, and what the impact was (e.g. the field was ignored). examples: - message: id: sugars_higher_than_carbohydrates name: Sugars higher than carbohydrates lc_name: Sucres plus élevés que les glucides description: Sugars (40g) are higher than carbohydrates (35g). lc_description: Les sucres (40g) sont plus élévés que les glucdes. field: id: nutriment.sugars value: '40' impact: id: nutrients_not_updated name: Nutrients not updated lc_name: Nutriments non mis à jour description: The nutrients were not updated. lc_description: Les nutriments n'ont pas été mis à jour. properties: message: type: object properties: id: type: string description: 'Identifier of a response message. ' name: type: string description: Name of the response message entry in English. lc_name: type: string description: Name of the response message entry in the language specified in tags_lc, if supplied. description: type: string description: Description of the problem specific to the request, in English. lc_description: type: string description: Description of the problem specific to the request, in the language specified in tags_lc, if supplied. field: type: object description: Field that triggered the warning or error. properties: id: type: string description: Name of the field that triggered the warning or error. value: type: string description: Value of the field that triggered the warning or error. impact: type: object properties: id: type: string name: type: string lc_name: type: string description: type: string lc_description: type: string errors: type: array description: List of errors. Errors are used to alert about something that is definitely wrong (e.g. a nutrient value that is impossibly high). items: title: Warning or error message x-stoplight: id: eakkz8p7qfoj0 type: object description: Describes a warning or error for a READ or WRITE request, which field triggered it, and what the impact was (e.g. the field was ignored). examples: - message: id: sugars_higher_than_carbohydrates name: Sugars higher than carbohydrates lc_name: Sucres plus élevés que les glucides description: Sugars (40g) are higher than carbohydrates (35g). lc_description: Les sucres (40g) sont plus élévés que les glucdes. field: id: nutriment.sugars value: '40' impact: id: nutrients_not_updated name: Nutrients not updated lc_name: Nutriments non mis à jour description: The nutrients were not updated. lc_description: Les nutriments n'ont pas été mis à jour. properties: message: type: object properties: id: type: string description: 'Identifier of a response message. ' name: type: string description: Name of the response message entry in English. lc_name: type: string description: Name of the response message entry in the language specified in tags_lc, if supplied. description: type: string description: Description of the problem specific to the request, in English. lc_description: type: string description: Description of the problem specific to the request, in the language specified in tags_lc, if supplied. field: type: object description: Field that triggered the warning or error. properties: id: type: string description: Name of the field that triggered the warning or error. value: type: string description: Value of the field that triggered the warning or error. impact: type: object properties: id: type: string name: type: string lc_name: type: string description: type: string lc_description: type: string - type: object properties: preferences: type: array description: A list of user preference importance values. items: type: object properties: id: type: string description: The ID of the preference importance. example: important name: type: string description: The name of the preference importance. example: Important factor: type: integer description: The factor associated with the preference importance (optional, not set for not_important). Indicates that the product attribute score should be multiplied by this factor when this importance is selected. example: 1 minimum_match: type: integer description: The minimum match percentage required for the preference (optional, set for mandatory). Indicates that product with a lesser score for this attribute should not be considered a match. example: 20 /api/v3.4/attribute_groups: get: summary: Get List of Attribute Groups and Attributes description: for an overview see Explanation on Product Attributes" tags: - Product Attributes operationId: get-api-v3-4-attribute-groups responses: '200': description: OK content: application/json: schema: allOf: - title: Response status type: object description: A response object to describe if a READ or WRITE request was successful or not, and if there were errors or warnings, and what the impact of those errors or warnings was. examples: - status: success_with_errors result: id: product_updated name: Product updated lc_name: Produit mis à jour errors: - message: id: sugars_higher_than_carbohydrates name: Sugars higher than carbohydrates lc_name: Sucres plus élevés que les glucides description: Sugars (40g) are higher than carbohydrates (35g). lc_description: Les sucres (40g) sont plus élévés que les glucdes. field: id: nutriment.sugars value: '40' impact: id: nutrients_not_updated name: Nutrients not updated lc_name: Nutriments non mis à jour description: The nutrients were not updated. lc_description: Les nutriments n'ont pas été mis à jour. properties: status: type: string enum: - success - success_with_warnings - success_with_errors - failure description: 'Overall status of the request: whether it failed or succeeded, with or without warnings or errors.' result: type: object description: 'Overall result of the request (e.g. a product has been created)' properties: id: type: string description: Identifier of a response result entry name: type: string description: Name of the response result entry in English. lc_name: type: string description: Name of the response result entry in the language specified in tags_lc, if supplied. warnings: type: array description: List of warnings. Warnings are used to alert about something that may be wrong, but is not necessarily wrong (e.g. a nutrient value that is unexpectedly high). items: title: Warning or error message x-stoplight: id: eakkz8p7qfoj0 type: object description: Describes a warning or error for a READ or WRITE request, which field triggered it, and what the impact was (e.g. the field was ignored). examples: - message: id: sugars_higher_than_carbohydrates name: Sugars higher than carbohydrates lc_name: Sucres plus élevés que les glucides description: Sugars (40g) are higher than carbohydrates (35g). lc_description: Les sucres (40g) sont plus élévés que les glucdes. field: id: nutriment.sugars value: '40' impact: id: nutrients_not_updated name: Nutrients not updated lc_name: Nutriments non mis à jour description: The nutrients were not updated. lc_description: Les nutriments n'ont pas été mis à jour. properties: message: type: object properties: id: type: string description: 'Identifier of a response message. ' name: type: string description: Name of the response message entry in English. lc_name: type: string description: Name of the response message entry in the language specified in tags_lc, if supplied. description: type: string description: Description of the problem specific to the request, in English. lc_description: type: string description: Description of the problem specific to the request, in the language specified in tags_lc, if supplied. field: type: object description: Field that triggered the warning or error. properties: id: type: string description: Name of the field that triggered the warning or error. value: type: string description: Value of the field that triggered the warning or error. impact: type: object properties: id: type: string name: type: string lc_name: type: string description: type: string lc_description: type: string errors: type: array description: List of errors. Errors are used to alert about something that is definitely wrong (e.g. a nutrient value that is impossibly high). items: title: Warning or error message x-stoplight: id: eakkz8p7qfoj0 type: object description: Describes a warning or error for a READ or WRITE request, which field triggered it, and what the impact was (e.g. the field was ignored). examples: - message: id: sugars_higher_than_carbohydrates name: Sugars higher than carbohydrates lc_name: Sucres plus élevés que les glucides description: Sugars (40g) are higher than carbohydrates (35g). lc_description: Les sucres (40g) sont plus élévés que les glucdes. field: id: nutriment.sugars value: '40' impact: id: nutrients_not_updated name: Nutrients not updated lc_name: Nutriments non mis à jour description: The nutrients were not updated. lc_description: Les nutriments n'ont pas été mis à jour. properties: message: type: object properties: id: type: string description: 'Identifier of a response message. ' name: type: string description: Name of the response message entry in English. lc_name: type: string description: Name of the response message entry in the language specified in tags_lc, if supplied. description: type: string description: Description of the problem specific to the request, in English. lc_description: type: string description: Description of the problem specific to the request, in the language specified in tags_lc, if supplied. field: type: object description: Field that triggered the warning or error. properties: id: type: string description: Name of the field that triggered the warning or error. value: type: string description: Value of the field that triggered the warning or error. impact: type: object properties: id: type: string name: type: string lc_name: type: string description: type: string lc_description: type: string - type: object properties: attribute_groups: type: array description: A list of attribute groups. items: type: object properties: id: type: string description: The ID of the attribute group. example: nutritional_quality name: type: string description: The name of the attribute group. example: Nutritional quality warning: type: string description: A warning message related to the attribute group (optional). example: There is always a possibility that data about allergens may be missing, incomplete, incorrect or that the product's composition has changed. attributes: type: array description: A list of attributes in the group. items: type: object properties: id: type: string description: The ID of the attribute. example: nutriscore name: type: string description: The name of the attribute. example: Nutri-Score icon_url: type: string description: The URL of the icon representing the attribute. example: http://static.openfoodfacts.org/images/attributes/dist/nutriscore-a.svg setting_name: type: string description: The name of the setting for the attribute. example: Good nutritional quality (Nutri-Score) setting_note: type: string description: Additional notes about the setting (optional). example: The Nutri-Score is computed and can be taken into account for all products, even if it is not displayed on the packaging. panel_id: type: string description: The panel ID associated with the attribute (optional). example: nutriscore description: type: string description: A detailed description of the attribute (optional). example: Organic farming aims to protect the environment and to conserve biodiversity by prohibiting or limiting the use of synthetic fertilizers, pesticides and food additives. description_short: type: string description: A short description of the attribute (optional). example: Organic products promote ecological sustainability and biodiversity. default: type: string description: The default value for the attribute (optional). example: very_important values: type: array description: The possible values for the attribute. Some attributes like allergens have only values "not_important" and "mandatory". items: type: string example: not_important parameters: type: array description: Additional parameters for the attribute (optional, used for specific attributes like Unwanted ingredients). items: type: object properties: id: type: string description: The ID of the parameter. example: attribute_unwanted_ingredients_tags name: type: string description: The name of the parameter. example: Unwanted ingredients tagtype: type: string description: The tag type of the parameter. example: ingredients type: type: string description: The type of the parameter. "tags" indicates a comma-separated list of canonical tags is expected. enum: - tags example: tags components: securitySchemes: cookieAuth: type: apiKey in: cookie name: session description: 'Session cookie containing user ID, username, and session token. The value is structured as: user_id&username&user_session&session_token e.g. "user_id&exampleuser&user_session&abcdefghijklmnopqrstuvwxyz123456789ABCDEFGHIJKLM". The session token is obtained after successful login via the `/cgi/session.pl` endpoint. ' userAgentAuth: description: Identification using the User-Agent header. This is recommended in all requests so that we can contact you if there are issues. If we cannot identify the source of problematic API queries, we may have to block them. User-Agent header in the format 'app_name/app_version (URL or contact info)' type: apiKey in: header name: User-Agent