<!-- The markdown copy of https://oppalerts.com/docs/mcp/taxonomy_categories . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [MCP](https://oppalerts.com/docs/mcp/) / taxonomy_categories

# taxonomy_categories

`POST https://mcp.oppalerts.com/mcp tool: taxonomy_categories`

The categories of one taxonomy: the id, the name, and the depth of each category, sorted by name.

## What it does

You send the name of one taxonomy. The tool returns the categories of that taxonomy: the `category_id`, the name, and the depth of each category, sorted by name. These are the categories that the category picker of the [Content Optimizer](https://oppalerts.com/docs/app/content/optimizer) shows. To find categories by their names, also send `query`.

Use a `category_id` as a target of [taxonomy_semantic_content_analyzer](https://oppalerts.com/docs/mcp/taxonomy_semantic_content_analyzer), or in a preset of [campaigns_set_taxonomy_presets](https://oppalerts.com/docs/mcp/campaigns_set_taxonomy_presets). [taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies) gives the names of the taxonomies.

## Connect

```bash
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
```

The first call opens a browser window for the OppAlerts login. [Connect an AI Agent](https://oppalerts.com/docs/mcp/) has the details.

## Parameters

**`taxonomy`string, required, at most 100 characters**

One taxonomy name, as taxonomy_taxonomies answers it, at most 100 characters. A name that is not in that list is refused.

**`results_limit`int, optional, 1 to 10000**

The maximum number of categories to return, a whole number from 1 to 10,000. Not sent: 100. The categories are sorted by name, and the answer holds the first `results_limit` of them.

**`query`string, optional, at most 200 characters**

Words to find in the category names, at most 200 characters. The words are split at the spaces. A category is returned only when its name contains every word. A word can be a part of a longer word: hotel finds Hotels and Motels. Upper case and lower case letters A to Z are the same, and every other character must be the same. Not sent: every category of the taxonomy.

## Strict Rules

- A field that is not in the list above is refused. The result then has `isError` true, and its text starts with `bad_param`. The error names the field: "<field> is not a field of this tool." The old name of a renamed field is refused in the same way.
- A bad value is refused, and the error names the field. A bad value is a value of the wrong type, a number with a fraction for a whole-number field, a value out of its range, or a value that is not in its list. A required field that you do not send is refused too. The tool never changes a value that you send.
- An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.

## How query finds a category

- The tool splits `query` into words at the spaces.
- A category is in the response only when its name contains every word.
- A word can be a part of a longer word: `hotel` finds "Hotels and Motels".
- Upper case and lower case letters A to Z are the same. Every other character must match exactly, including accented letters.
- The order does not change: the categories are sorted by name, and the answer holds the first `results_limit` of the categories that match.

## Response

The answer has three fields:

**`taxonomy`string**

The taxonomy that you sent.

**`total`int**

The number of categories that match `query`, or of all categories of the taxonomy when you do not send `query`.

**`returned`int**

The number of categories in `categories`, in this answer. When `total` is more than `returned`, send a higher `results_limit` or more words in `query`.

**`categories`list**

The categories, sorted by name. Each entry has three fields:  `category_id`int The id of the category. Send it as a target of `taxonomy_semantic_content_analyzer`, or as the `category_id` of a taxonomy preset. `category_label`string The name of the category, with its path, for example "Travel > Travel Type > Hotels and Motels". `depth`int The level of the category in its taxonomy. 1 is the top level.

## Example

### Call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "taxonomy_categories",
    "arguments": {
      "taxonomy": "iab-content-taxonomy",
      "results_limit": 10000,
      "query": "hotel"
    }
  }
}
```

### Response

```json
{
  "taxonomy": "iab-content-taxonomy",
  "total": 2,
  "returned": 2,
  "categories": [
    {
      "category_id": 289090960918637,
      "category_label": "Real Estate > Hotel Properties",
      "depth": 2
    },
    {
      "category_id": 2358064203319202,
      "category_label": "Travel > Travel Type > Hotels and Motels",
      "depth": 3
    }
  ]
}
```

## Errors

An error returns as a tool result with `isError` true. Its text starts with the error code, except for `daily_limit`, whose text is only the sentence. The HTTP status shown for each code is its API status.

- `bad_param` (HTTP 400 in the API): a field is not a field of this tool, a required field is not sent, a value has the wrong type or is out of its range, `query` is empty or holds no word, or `taxonomy` is not a taxonomy name. The error names the field. [taxonomy_taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies) names every taxonomy.
- `backend_error` (HTTP 502 in the API): the taxonomy server did not answer. Try again in a few minutes.
- `daily_limit` (HTTP 429 in the API): the account has used all its calls for this tool today. [account_calls_left](https://oppalerts.com/docs/mcp/account_calls_left) shows when the count resets.

This tool has its own daily count. Calls through the API, MCP, and the web app use this count. It is not an index search, so it does not use the shared count of the `news_` and `prospects_` tools, and the error `one_at_a_time` does not apply to it.

## Same data in the API

```http
POST /v1/taxonomy/categories HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{"taxonomy": "iab-content-taxonomy", "results_limit": 10000, "query": "hotel"}
```

See [POST /v1/taxonomy/categories](https://oppalerts.com/docs/api/taxonomy_categories).

## Related pages

- [POST /v1/taxonomy/categories in the API](https://oppalerts.com/docs/api/taxonomy_categories)
- [taxonomy_taxonomies: the names of the taxonomies](https://oppalerts.com/docs/mcp/taxonomy_taxonomies)
- [taxonomy_semantic_content_analyzer: analyze a text against your target categories](https://oppalerts.com/docs/mcp/taxonomy_semantic_content_analyzer)
- [campaigns_set_taxonomy_presets: the taxonomy presets of a campaign](https://oppalerts.com/docs/mcp/campaigns_set_taxonomy_presets)
- [The taxonomies](https://oppalerts.com/docs/the-data/taxonomies)
