openapi: 3.1.0 info: title: Open Food Facts Open API V3 - under development 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](https://openfoodfacts.github.io/openfoodfacts-server/api/) 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](../ref-api-and-product-schema-change-log.md) 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" paths: "/api/v3/product/{code}": get: tags: - Products summary: Get Product Data parameters: - name: code in: path description: | The barcode of the product to be fetched required: true style: simple explode: false schema: type: string example: "3017620422003" - $ref: "./parameters/requested_product_type.yaml#/components/parameters/RequestedProductType" - $ref: "./parameters/cc.yaml#/components/parameters/Cc" - $ref: "./parameters/lc.yaml#/components/parameters/Lc" - $ref: "./parameters/tags_lc.yaml#/components/parameters/TagsLc" - schema: type: string in: query name: fields description: |- Comma separated list of fields requested in the response. Special values: * "none": returns no fields * "raw": returns all fields as stored internally in the database * "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels". Defaults to "all" for READ requests. The "all" value can also be combined with fields like "attribute_groups" and "knowledge_panels". - $ref: "./parameters/knowledge_panels_options.yaml#/components/parameters/KnowledgePanelClient" - $ref: "./parameters/knowledge_panels_options.yaml#/components/parameters/ActivateKnowledgePanelsSimplified" - $ref: "./parameters/knowledge_panels_options.yaml#/components/parameters/ActivateKnowledgePanelPhysicalActivities" - $ref: "./parameters/knowledge_panels_options.yaml#/components/parameters/KnowledgePanelsIncluded" - $ref: "./parameters/knowledge_panels_options.yaml#/components/parameters/KnowledgePanelsExcluded" responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: product: $ref: ./schemas/product_v3.yaml "302": description: Redirect to the correct server for the product type of the requested product headers: Location: schema: type: string description: URL to the correct server examples: redirect: value: "https://world.openbeautyfacts.org/api/v3/product/8710447445990" "404": description: Product not found description: |- Retrieve information for a product with a specific barcode. The fields parameter allows to specify what fields to retrieve. operationId: get-api-v3-product-code patch: tags: - Products summary: Create or Update Product operationId: patch-api-v3-product-code description: |- This API allows to create or update a product (if the product already exists, its data is updated, otherwise it is created), or to analyze a test product (in which case no product is created or updated). To analyze a product, the "code" path component needs to contain the value "test" instead of a barcode. New API to send structured product data in a JSON format instead of in a flattened list of key / value pairs field as-in the current product add / edit API that relies on a multipart/form-data format. Important: this new Product WRITE API has been deployed in production, but it is still under development, and it may change. This new API is used in particular to send structured packaging data: https://openfoodfacts.github.io/openfoodfacts-server/dev/explain-packaging-data/ The new API is gradually being extended to support other product fields. Currently supported fields are: - language specific fields (e.g. product name, ingredients text) - tags fields (e.g. categories, labels) - packaging fields (e.g. packagings, packagings_add, packagings_complete) - image selection of uploaded images (e.g. front, ingredients, nutrition, packaging) for specific languages parameters: - name: code in: path description: | The barcode of the product to create or update, or "test" to analyze the product data sent without creating or updating a product. required: true style: simple explode: false schema: type: string example: "3017620422003" requestBody: content: application/json: schema: allOf: - $ref: ./requestBodies/lc_cc.yaml - $ref: ./requestBodies/fields_tags_lc.yaml - type: object properties: user_id: type: string password: type: string description: Password for login format: password product: $ref: ./schemas/product_update_api_v3.yaml examples: example-1: value: lc: fr cc: fr fields: "product_name,packagings" tags_lc: fr userid: string password: string code: string product: packagings: - number_of_units: 6 shape: id: "en:bottle" material: id: "en:plastic" recycling: id: "en:recycle" quantity_per_unit: 25 cl weight_measured: 10 packagings_add: - number_of_units: 6 shape: id: "en:bottle" material: id: "en:plastic" recycling: id: "en:recycle" quantity_per_unit: 25 cl weight_measured: 10 product: $ref: ./schemas/product_update_api_v3.yaml application/xml: schema: type: object properties: {} description: | Structured data for the product is passed in the product field. For complex structures such as the packagings object, it is possible to replace pre-existing data, or completing it: - an object sent in the packagings field will replace any pre-existing data. - an object sent in the field suffixed with _add (e.g. packagings_add) will be merged with any pre-existing data. responses: "200": description: |- The response will include a "product" structure. The fields returned in this structure will depend on the value of the "fields" input field: - "updated" (default): all fields updated by the query will be returned, including fields that are directly generated from the updated fields. For instance, sending "packagings" or "packagings_add" will return the "packagings" field. - "none": no fields are returned. - "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels". The "fields" values can also be concatenated: "all,knowledge_panels" content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: product: $ref: ./schemas/product_v3.yaml examples: Update of packagings: value: status: success_with_errors result: id: "en:product-updated" en_name: Product updated lc_name: Produit mis à jour errors: - message: id: "en: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: "en: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. product: packagings: - material: "en:pp-polypropylene" number: "2" recycling: "en:discard" shape: "en:lid" - material: "en:non-corrugated-cardboard" number: "1" recycling: "en:recycle" shape: "en:box" weight: 120 - material: "en:paper-and-fibreboard-aluminium" number: "2" recycling: "en:recycle" shape: "en:seal" - material: "en:clear-glass" number: "2" recycling: "en:recycle" shape: "en:jar" quantity: 200 ML quantity_value: 200 quantity_unit: ml weight: 80 security: - cookieAuth: [] userAgentAuth: [] "/api/v3/product/{code}/images": post: tags: - Images summary: Upload Product Image operationId: post-api-v3-product-code-images description: |- This endpoint allows to upload an image for a product. The image is uploaded in the request body as a base64 encoded string. Optionally, it is possible to select the uploaded image for specific information (e.g. front, ingredients, nutrition, packaging) for specific languages. Each selected image is a cropped version of the uploaded image. If the product does not exist, it will be created. parameters: - name: code in: path description: | The barcode of the product corresponding to the image. required: true style: simple explode: false schema: type: string example: "3017620422003" requestBody: content: application/json: schema: allOf: - $ref: ./requestBodies/lc_cc.yaml - type: object properties: user_id: type: string description: | Username for login Note: you must always use the username (and not the email) as it is far less brittle. password: type: string description: Password for login format: password image_data_base64: type: string description: |- Base64 encoded image data (supported formats: JPEG, PNG, GIF, HEIC) selected: description: | Optional instructions to select (and possibly crop) the uploaded image for specific information (e.g. front, ingredients, nutrition, packaging) for specific languages. $ref: "./schemas/image_selected.yaml#/components/schemas/ImagesSelected" application/xml: schema: type: object properties: {} description: | Image data for the product is passed in the image_data_base64 field as a base64 encoded string. security: - cookieAuth: [] userAgentAuth: [] responses: "200": description: |- The response will include a "product" structure. The fields returned in this structure will depend on the value of the "fields" input field: - "updated" (default): all fields updated by the query will be returned, including fields that are directly generated from the updated fields. For instance, sending "packagings" or "packagings_add" will return the "packagings" field. - "none": no fields are returned. - "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels". The "fields" values can also be concatenated: "all,knowledge_panels" content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: product: properties: images: type: object properties: uploaded: description: | List with only the image just uploaded by the user. The key is the image id (imgid) and the value is an object with the image data. type: object title: images_uploaded patternProperties: '(?\d+)': $ref: "./schemas/image_uploaded.yaml#/components/schemas/ImageUploaded" "/api/v3/product/{code}/images/uploaded/{imgid}": delete: tags: - Images summary: Delete Product Image operationId: delete-api-v3-product-code-images-uploaded-imgid description: |- This endpoint allows to delete an uploaded image for a product. Selected images that are cropped from it will also be deleted. Image deletion is allowed only for moderators and admins, so the request must be authenticated with a session cookie or userid and password. parameters: - name: code in: path description: | The barcode of the product corresponding to the image. required: true style: simple explode: false schema: type: string example: "3017620422003" - name: imgid in: path description: | The id of the image to be deleted. required: true style: simple explode: false schema: type: integer example: 2 responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml "403": description: User not authenticated or not allowed to delete the image "404": description: Product or image not found security: - cookieAuth: [] userAgentAuth: [] /api/v3/taxonomy_canonicalize_tags: get: summary: Get canonical tags for a list of local tags description: | Open Food Facts uses multilingual [taxonomies](https://wiki.openfoodfacts.org/Global_taxonomies) to normalize entries for categories, labels, ingredients, packaging shapes / materials / recycling instructions and many more fields. This API returns the canonical tags corresponding to a list of local tags in a given language. For instance, the local French ingredient tag "sucre" corresponds to the canonical tag "en:sugar". tags: - Taxonomy operationId: get-api-v3-taxonomy-canonicalize-tags parameters: - name: tagtype in: query required: true description: The type of taxonomy to canonicalize tags for (e.g., ingredients, categories). schema: type: string example: "ingredients" - name: local_tags_list in: query required: true description: A comma-separated list of local tags to canonicalize. schema: type: string example: "sucre,eau" - name: lc in: query required: false description: | 2-letter code of the language of the user. Used for localizing some fields in returned values. If not passed, the language may be inferred by the subdomain of the request. schema: type: string example: "fr" responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: canonical_tags_list: type: string example: "en:sugar,en:water" /api/v3/taxonomy_display_tags: get: summary: Get display tags in a specific language for a list of taxonomy tags description: | Open Food Facts uses multilingual [taxonomies](https://wiki.openfoodfacts.org/Global_taxonomies) to normalize entries for categories, labels, ingredients, packaging shapes / materials / recycling instructions and many more fields. This API returns display tags in a specific language for a list of canonical taxonomy tags. For instance, the canonical ingredient tag "en:sugar" corresponds to the French display tag "sucre". tags: - Taxonomy operationId: get-api-v3-taxonomy-display-tags parameters: - name: tagtype in: query required: true description: The type of taxonomy to retrieve display tags for (e.g., ingredients, categories). schema: type: string example: "ingredients" - name: canonical_tags_list in: query required: true description: A comma-separated list of canonical taxonomy tags to retrieve display tags for. schema: type: string example: "en:sugar,en:water" - name: lc in: query required: false description: | 2-letter code of the language to return display tags in. schema: type: string example: "fr" responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: display_tags: type: array items: type: string example: "sucre, eau" /api/v3/taxonomy_suggestions: parameters: [] get: summary: Get Taxonomy Suggestions tags: - Taxonomy responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: suggestions: type: array description: Array of sorted strings suggestions in the language requested in the "lc" field. items: type: string matched_synonyms: type: object description: | Dictionary of strings associating canonical names (as seen in suggestions field) with the synonym that best matches the query. An entry is present for all suggestions, even when the synonym is the same with the canonical name. This value is present only if get_synonyms parameter is present. additionalProperties: type: string operationId: get-api-v3-taxonomy_suggestions-taxonomy description: |- Open Food Facts uses multilingual [taxonomies](https://wiki.openfoodfacts.org/Global_taxonomies) to normalize entries for categories, labels, ingredients, packaging shapes / materials / recycling instructions and many more fields. This API returns taxonomy entries suggestions that can be used in product edit forms, search forms etc. (for instance in autocomplete dropdowns using libraries like Tagify or select2 on the Web). Suggestions filtering: The string parameter allows to get only suggestions that contain a specific string (useful for autocomplete suggestions). Suggestions ordering: - For packaging shapes and materials, suggestions are ordered first by the number of packaging components they appear in (restricted by country, categories and shape (for materials) if they are passed as parameters). - for all other taxonomies, results are ordered alphabetically If a string is passed, an additional sort is done to put first suggestions that start with the string, followed by suggestions with a word that start with the string, and then suggestions that contain the string anywhere. parameters: - $ref: "./parameters/tagtype.yaml#/components/parameters/Tagtype" - $ref: "./parameters/cc.yaml#/components/parameters/Cc" - $ref: "./parameters/lc.yaml#/components/parameters/Lc" - schema: type: string example: pe in: query name: string description: "Optional string used to filter suggestions (useful for autocomplete). If passed, suggestions starting with the string will be returned first, followed by suggestions matching the string at the beginning of a word, and suggestions matching the string inside a word." - schema: type: string example: yougurts in: query name: categories description: 'Comma separated list of categories tags (e.g. "en:fats,en:unsalted-butters" or categories names in the language indicated by the "lc" field (e.g. "graisses, beurres salés" in French)' - schema: type: string example: bottle in: query name: shape description: 'Shape of packaging component (tag identified in the packaging_shapes taxonomy, or plain text tag name in the language indicated by the "lc" field)' - schema: type: string in: query name: limit description: "Maximum number of suggestions. Default is 25, max is 400." - schema: type: string in: query name: get_synonyms description: 'Whether or not to include "matched_synonyms" in the response. Set to 1 to include.' - schema: type: string in: query name: term description: Alias for the "string" parameter provided for backward compatibility. "string" takes precedence. "/api/v3/tag/{tagtype}/{tag_or_tagid}": parameters: - $ref: "./parameters/cc.yaml#/components/parameters/Cc" - $ref: "./parameters/lc.yaml#/components/parameters/Lc" - schema: type: string example: categories name: tagtype in: path required: true description: Type of the tag - schema: type: string name: tag_or_tagid in: path required: true description: "Tag name (e.g. yogurts) or tag id (e.g. en:yogurts)" get: summary: Get Tag Knowledge Panels tags: - Knowledge Panels responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: tagtype: type: string description: | Input tagtype tagid: type: string description: | Input tagid tag: type: object properties: tagid: type: string description: Canonicalized tagid corresponding to the input tag_or_tagid tagtype: type: string description: Canonicalized tagtype knowledge_panels: $ref: ./schemas/knowledge_panels/panels.yaml description: Knowledge panels for the tag application/xml: schema: type: object properties: {} operationId: get-api-v3-tag-tagtype-tag_or_tagid description: |- Return knowledge panels for a tag. Currently the knowledge panels returned are: Categories: - Packaging stats for a category /api/v3/product_revert: parameters: [] post: summary: Revert Product to Previous Revision tags: - Products responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml operationId: post-api-v3-product_revert description: |- For moderators only, revert a product to a previous revision. requestBody: content: application/json: schema: allOf: - $ref: ./requestBodies/fields_tags_lc.yaml - type: object properties: code: type: string description: Barcode of the product rev: type: integer description: Revision number to revert to description: | The code and rev fields are mandatory. parameters: [] security: - cookieAuth: [] userAgentAuth: [] /api/v3/external_sources: get: operationId: get-api-v3-external-sources tags: - Knowledge Panels summary: List external knowledge panel sources (JSON) description: | Returns the ordered list of external knowledge panel sources configured on the server. Providers can use the `knowledge_panel_url` field to point to their own API. The URL may contain **template variables** that the frontend will expand before calling: - `$code` → product barcode - `$lc` → UI language (2 letters) - `$cc` → user/device country (2 letters) Example: `https://provider.example.com/off/v1/knowledge-panel/$code?lang=$lc&country=$cc` The frontend percent-encodes the variable values when substituting them into the URL. responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - type: object properties: external_sources: $ref: "#/components/schemas/ExternalKnowledgePanelList" /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](https://openfoodfacts.github.io/documentation/docs/Product-Opener/api/explain-product-attributes/)" tags: - Product Attributes operationId: get-api-v3-preferences responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - 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](https://openfoodfacts.github.io/documentation/docs/Product-Opener/api/explain-product-attributes/)" tags: - Product Attributes operationId: get-api-v3-4-attribute-groups responses: "200": description: OK content: application/json: schema: allOf: - $ref: ./responses/response-status/response_status.yaml - 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 schemas: ExternalKnowledgePanelList: type: array description: Ordered list of external knowledge panel sources. items: $ref: "./schemas/external_knowledge_panel.yaml" security: - userAgentAuth: [] # No authentication required by default (for read requests), but we recommend sending a User-Agent header in all requests. tags: - name: Products description: Endpoints for managing product data, creating, updating, and reverting products. - name : Product Attributes description: Endpoints for retrieving product attribute groups and user preference importance values. - name: Images description: Endpoints for uploading, managing, and deleting product images. - name: Taxonomy description: Endpoints for retrieving taxonomy suggestions and data. - name: Knowledge Panels description: Endpoints for retrieving knowledge panels for tags and categories.