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

[Documentation](https://oppalerts.com/docs/) / [API](https://oppalerts.com/docs/api/) / taxonomy_categories

# taxonomy_categories

`POST https://api.oppalerts.com/v1/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 route 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/api/taxonomy_semantic_content_analyzer), or in a preset of [campaigns_set_taxonomy_presets](https://oppalerts.com/docs/api/campaigns_set_taxonomy_presets). [taxonomy_taxonomies](https://oppalerts.com/docs/api/taxonomy_taxonomies) gives the names of the taxonomies.

## Authentication

Send your token in the `Authorization: Bearer` header. [Authentication and Limits](https://oppalerts.com/docs/api/) explains the tokens.

## 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 answer is HTTP 400 with the error code `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 route 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

### Request

```bash
curl -X POST https://api.oppalerts.com/v1/taxonomy/categories \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"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

- `bad_param` (HTTP 400): a field is not a field of this route, 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/api/taxonomy_taxonomies) names every taxonomy.
- `backend_error` (HTTP 502): the taxonomy server did not answer. Try again in a few minutes.
- `daily_limit` (HTTP 429): the account has used all its calls for this tool today. [account_calls_left](https://oppalerts.com/docs/api/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 tool in MCP

The MCP tool `taxonomy_categories` gives the same data. See [taxonomy_categories in MCP](https://oppalerts.com/docs/mcp/taxonomy_categories).

## Related pages

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