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

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

# taxonomy_semantic_content_analyzer

`POST https://api.oppalerts.com/v1/taxonomy/semantic_content_analyzer`

How closely a piece of writing matches your target taxonomy categories, and the phrases that would bring it closer.

## What it does

You send a piece of writing and 1 to 3 target categories, at most one from each taxonomy. The route returns the same data as the [Content Optimizer](https://oppalerts.com/docs/app/content/optimizer) page of the web app:

- For each target: its `similarity_score`, its rank in its taxonomy, and the 10 categories of that taxonomy that are nearest to the writing.
- For all targets together: the phrases of the targets that the writing does not use, most useful first, and the phrases that it already uses.

Get the category ids from [taxonomy_categories](https://oppalerts.com/docs/api/taxonomy_categories). A campaign keeps up to 3 targets as its taxonomy presets: [campaigns_settings](https://oppalerts.com/docs/api/campaigns_settings) returns them.

## Authentication

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

## Parameters

**`text`string, required**

The writing to analyze, at most 8,192 bytes of UTF-8. A letter with an accent or a symbol counts as 2 or more bytes. A longer text is refused, not cut: send it in parts. An empty text, and a text of spaces only, are refused.

**`target_category_ids`list of whole numbers, required, 1 to 3 items, each 1 to 9007199254740991**

1 to 3 category ids, as taxonomy_categories answers them, at most one from each taxonomy. Two ids of one taxonomy are refused, and so is an id that is not a category. The answer holds one entry in taxonomies for each id, in the order sent.

## 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.

## The text and the targets

- The text can have at most 8,192 bytes. A letter with an accent or a symbol counts as 2 or more bytes. A longer text is refused, not cut: send it in parts.
- An empty text, and a text of spaces only, are refused.
- Send at most one target of each taxonomy. Two targets of one taxonomy are refused: a rank is a place in one taxonomy.
- An id that is not a category is refused. The same id two times is refused.
- The answer has one entry in `taxonomies` for each target, in the order that you sent them.

## Response

The answer has three fields:

**`taxonomies`list**

One entry for each target, in the order sent. Each entry has three fields:  `taxonomy`string The name of the taxonomy of the target. `target`object The target category: `category_id`, `category_label`, `similarity_score` (how near the writing is to the category; 100 is the nearest, and 0 or less is no likeness), `rank` (its place in its taxonomy, 1 is the nearest), and `rank_of` (the number of categories in the taxonomy). `nearest`list The 10 categories of the taxonomy that are nearest to the writing, nearest first. Each has `category_id`, `category_label`, `similarity_score`, and `rank`. When the target is not in this list, its `rank` tells its place.

**`phrases_to_add`list**

The phrases of the target categories that the writing does not use, most useful first. Each has `phrase` and `relevance_weight`, a weight of the phrase for its category. The weight sets the order. It is not a percent. A phrase that two targets have is in the list one time, with the higher weight. Use the phrases that belong in the writing. Do not try to use all of them.

**`phrases_in_text`list of strings**

The phrases of the target categories that the writing already uses.

## Example

### Request

```bash
curl -X POST https://api.oppalerts.com/v1/taxonomy/semantic_content_analyzer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Our boutique hotel in Sedona puts every guest near the red rock trails. Each of our guest rooms has a private patio, and breakfast is free when you book direct.", "target_category_ids": [4074921791751665, 2358064203319202]}'
```

### Response

A shortened answer. A real answer has 10 entries in each `nearest` list and every phrase of the targets.

```json
{
  "taxonomies": [
    {
      "taxonomy": "google-merchant",
      "target": {
        "category_id": 4074921791751665,
        "category_label": "Business & Industrial > Hotel & Hospitality",
        "similarity_score": 31.47,
        "rank": 1,
        "rank_of": 5595
      },
      "nearest": [
        {
          "category_id": 4074921791751665,
          "category_label": "Business & Industrial > Hotel & Hospitality",
          "similarity_score": 31.47,
          "rank": 1
        },
        {
          "category_id": 3254328027992189,
          "category_label": "Home & Garden > Decor > Bird & Wildlife Houses > Butterfly Houses",
          "similarity_score": 26.15,
          "rank": 2
        }
      ]
    },
    {
      "taxonomy": "iab-content-taxonomy",
      "target": {
        "category_id": 2358064203319202,
        "category_label": "Travel > Travel Type > Hotels and Motels",
        "similarity_score": 38.01,
        "rank": 2,
        "rank_of": 704
      },
      "nearest": [
        {
          "category_id": 3875482560662752,
          "category_label": "Travel > Travel Type > Bed & Breakfasts",
          "similarity_score": 44.9,
          "rank": 1
        },
        {
          "category_id": 2358064203319202,
          "category_label": "Travel > Travel Type > Hotels and Motels",
          "similarity_score": 38.01,
          "rank": 2
        }
      ]
    }
  ],
  "phrases_to_add": [
    {
      "phrase": "hotels and motels",
      "relevance_weight": 13.0
    },
    {
      "phrase": "hotel booking",
      "relevance_weight": 12.7734
    },
    {
      "phrase": "luxury hotels",
      "relevance_weight": 10.1023
    }
  ],
  "phrases_in_text": [
    "hotel",
    "boutique hotels",
    "boutique hotel",
    "hotels",
    "guest rooms",
    "guest room"
  ]
}
```

## 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, the text is empty or has more than 8,192 bytes, two targets are of one taxonomy, the same id is sent two times, or an id is not a category. The error names the field.
- `backend_error` (HTTP 502): a server behind the route 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_semantic_content_analyzer` gives the same data. See [taxonomy_semantic_content_analyzer in MCP](https://oppalerts.com/docs/mcp/taxonomy_semantic_content_analyzer).

## Related pages

- [taxonomy_semantic_content_analyzer in MCP](https://oppalerts.com/docs/mcp/taxonomy_semantic_content_analyzer)
- [taxonomy_categories: the category ids of a taxonomy](https://oppalerts.com/docs/api/taxonomy_categories)
- [taxonomy_taxonomies: the names of the taxonomies](https://oppalerts.com/docs/api/taxonomy_taxonomies)
- [The Content Optimizer page](https://oppalerts.com/docs/app/content/optimizer)
- [Use case: check draft topic relevance](https://oppalerts.com/docs/how-to/check-draft-topic-relevance)
- [Use case: compare content to target audiences](https://oppalerts.com/docs/how-to/compare-content-to-target-audiences)
