Documentation / API / taxonomy_categories
taxonomy_categories
POSThttps://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 shows. To find categories by their names, also send query.
Use a category_id as a target of taxonomy_semantic_content_analyzer, or in a preset of campaigns_set_taxonomy_presets. taxonomy_taxonomies gives the names of the taxonomies.
Authentication
Send your token in the Authorization: Bearer header. Authentication and Limits explains the tokens.
Parameters
taxonomystring, 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_limitint, 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_limitof them. querystring, 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
queryinto 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:
hotelfinds "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_limitof the categories that match.
Response
The answer has three fields:
taxonomystring- The taxonomy that you sent.
totalint- The number of categories that match
query, or of all categories of the taxonomy when you do not sendquery. returnedint- The number of categories in
categories, in this answer. Whentotalis more thanreturned, send a higherresults_limitor more words inquery. categorieslist- The categories, sorted by name. Each entry has three fields:
category_idint- The id of the category. Send it as a target of
taxonomy_semantic_content_analyzer, or as thecategory_idof a taxonomy preset. category_labelstring- The name of the category, with its path, for example "Travel > Travel Type > Hotels and Motels".
depthint- The level of the category in its taxonomy. 1 is the top level.
Example
Request
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
{
"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,queryis empty or holds no word, ortaxonomyis not a taxonomy name. The error names the field. 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 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.