Get Taxonomy Suggestions

Open Food Facts uses multilingual 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.

Query Parameters

tagtype?string

cc?string

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request.

lc?string

2 letter code of the language of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the Accept-Language header of the request.

string?string

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.

categories?string

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)

shape?string

Shape of packaging component (tag identified in the packaging_shapes taxonomy, or plain text tag name in the language indicated by the "lc" field)

limit?string

Maximum number of suggestions. Default is 25, max is 400.

get_synonyms?string

Whether or not to include "matched_synonyms" in the response. Set to 1 to include.

term?string

Alias for the "string" parameter provided for backward compatibility. "string" takes precedence.

Response Body

curl -X GET "https://world.openfoodfacts.org/api/v3/taxonomy_suggestions?tagtype=additives&cc=us&lc=fr&string=pe&categories=yougurts&shape=bottle&limit=string&get_synonyms=string&term=string"

{
  "status_id": "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."
      }
    }
  ],
  "suggestions": [
    "string"
  ],
  "matched_synonyms": {
    "property1": "string",
    "property2": "string"
  }
}

Get Taxonomy Suggestions

Query Parameters

Response Body

200