Taxonomy

Get Taxonomy Suggestions

Changed on

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.

get/api/v3/taxonomy_suggestions

Request

  • Base URL
    https://world.openfoodfacts.org
  • Auth
    API key in header User-Agent

Query parameters

tagtypestring required
Example:additives

Type of a tag / id of a tags taxonomy (e.g. categories, labels, ingredients, etc.)

ccstring
Example:us

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.

lcstring
Example:fr

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 domain name prefix.

stringstring
Example:pe

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.

categoriesstring
Example:yougurts

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)

shapestring
Example:bottle

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

limitstring

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

get_synonymsstring

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

termstring

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

Response

OK

status'success' | 'success_with_warnings' | 'success_with_errors' | 'failure'

Overall status of the request: whether it failed or succeeded, with or without warnings or errors.

suggestionsstring[]

Array of sorted strings suggestions in the language requested in the "lc" field.

matched_synonymsobject

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.

Example response

{
  "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."
      }
    }
  ]
}

Changes

    • breaking

      added the new required query request parameter tagtype

    • info

      added the new optional query request parameter cc

    • info

      added the new optional query request parameter lc

    2 more changes in this revision