---
title: "Get Taxonomy Suggestions"
method: GET
path: "/api/v3/taxonomy_suggestions"
tags: ["Taxonomy"]
---

# Get Taxonomy Suggestions

`GET /api/v3/taxonomy_suggestions`

## Request

- Base URL: `https://world.openfoodfacts.org`
- URL: `https://world.openfoodfacts.org/api/v3/taxonomy_suggestions`
- Auth: API key in header `User-Agent`

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.

## Query parameters

- `tagtype` string, required
- `cc` string
- `lc` string
- `string` string
- `categories` string
- `shape` string
- `limit` string
- `get_synonyms` string
- `term` string

## Response `200`

OK

- object: 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.
  - `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.
  - `result` object: Overall result of the request (e.g. a product has been created)
    - `id` string: Identifier of a response result entry
    - `name` string: Name of the response result entry in English.
    - `lc_name` string: Name of the response result entry in the language specified in tags_lc, if supplied.
  - `warnings` WarningOrError[]: 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).
    - `message` object
      - `id` string: Identifier of a response message.
      - `name` string: Name of the response message entry in English.
      - `lc_name` string: Name of the response message entry in the language specified in tags_lc, if supplied.
      - `description` string: Description of the problem specific to the request, in English.
      - `lc_description` string: Description of the problem specific to the request, in the language specified in tags_lc, if supplied.
    - `field` object: Field that triggered the warning or error.
      - `id` string: Name of the field that triggered the warning or error.
      - `value` string: Value of the field that triggered the warning or error.
    - `impact` object
      - `id` string
      - `name` string
      - `lc_name` string
      - `description` string
      - `lc_description` string
  - `errors` WarningOrError[]: List of errors. Errors are used to alert about something that is definitely wrong (e.g. a nutrient value that is impossibly high).
    - `message` object
      - `id` string: Identifier of a response message.
      - `name` string: Name of the response message entry in English.
      - `lc_name` string: Name of the response message entry in the language specified in tags_lc, if supplied.
      - `description` string: Description of the problem specific to the request, in English.
      - `lc_description` string: Description of the problem specific to the request, in the language specified in tags_lc, if supplied.
    - `field` object: Field that triggered the warning or error.
      - `id` string: Name of the field that triggered the warning or error.
      - `value` string: Value of the field that triggered the warning or error.
    - `impact` object
      - `id` string
      - `name` string
      - `lc_name` string
      - `description` string
      - `lc_description` string
  - `suggestions` string[]: Array of sorted strings suggestions in the language requested in the "lc" field.
  - `matched_synonyms` object: 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.

## Changes

- **2026-11-18** (v3) `ab04ff78cb83`: 1 breaking, 4 info
  - added the new required `query` request parameter `tagtype`
  - added the new optional `query` request parameter `cc`
  - added the new optional `query` request parameter `lc`
  - added `#/components/schemas/response_status` to the response body `allOf` list for the response status `200`
  - …1 more
- **2025-11-07** (v3) `2d4fe0da438a`: 2 warning
  - deleted the `query` request parameter `cc`
  - deleted the `query` request parameter `lc`
- **2025-07-02** (v3) `a82fb856bebd`: 2 info
  - api tag `Taxonomy` added
  - api tag `Read Requests` removed

[Operation history](https://skmtc.dev/openfoodfacts/apis/open-food-facts-open-api-v3-under-development/changes/api/v3/taxonomy_suggestions/get.md)

---

[API](https://skmtc.dev/openfoodfacts/apis/open-food-facts-open-api-v3-under-development.md) - [All operations](https://skmtc.dev/openfoodfacts/apis/open-food-facts-open-api-v3-under-development/llms.txt) - [OpenAPI document](https://skmtc.dev/openfoodfacts/apis/open-food-facts-open-api-v3-under-development/revisions/ab04ff78cb83?raw)
