Categories, topics and industries: what is the difference#

Every article in the APITube index carries three parallel classification systems: categories (the industry-standard IPTC Media Topics scheme, 1,085 entries with IDs like medtop:04000000), topics (69 finer-grained subject slugs such as industry.automotive_news), and industries (1,264 business sectors with plain numeric IDs). They answer different questions — “what kind of news is this”, “what recurring subject is this about” and “which business sector does it concern” — and each has its own filter parameter.

What are categories (IPTC Media Topics)?#

Categories place an article in the universal news classification maintained by the IPTC — the same scheme large news agencies use. APITube’s category list has 1,085 entries, each with an ID of the form medtop: followed by eight digits, for example medtop:04000000 for economy, business and finance. The scheme is a tree: broad top-level subjects branch into narrower children, and the full indented tree is published in the docs as the list of categories.

One behaviour to plan around: the category.id filter matches the exact ID you pass and does not automatically include a category’s children. If you want a parent subject plus two of its subtopics, pass the IDs explicitly — the filter accepts up to 3, comma-separated. See how to filter news by category for worked requests.

What are topics?#

Topics are APITube’s own, much smaller vocabulary of recurring news subjects: 69 slugs in two families — industry.* (26 slugs like industry.automotive_news) and market_news.* (43 slugs like market_news.commodities.crude_oil). Where a category tells you an article is business news in general, a topic pins it to a named, trackable beat. The topic ID is the slug itself, passed to topic.id; the complete vocabulary is in the docs list of topics.

What are industries?#

Industries map an article to the business sector it concerns — useful when you monitor a market rather than a subject. The industry reference is the largest flat list of the three: 1,264 sectors, numbered from 0 (Aerospace Defense) upward, so industry.id takes a plain number like industry.id=88. The full table with names and descriptions is the docs list of industries.

How do the three appear in an API response?#

Each article object carries three arrays. Their items look similar but differ in one detail worth knowing:

• categories[] — id, name, taxonomy (normally iptc_mediatopics), a links.self URL and a score — the confidence of the classification.
• topics[] — id, name, links.self and a score.
• industries[] — id, name and links.self. Industry assignments carry no score field.

All three filters follow the same rules: only IDs are accepted (there is no category.name-style parameter), up to 3 comma-separated values per parameter, and each has an ignore.* twin (ignore.category.id, ignore.topic.id, ignore.industry.id) for excluding instead of including. An ID that does not exist in the reference list is rejected with a 400 error rather than silently returning nothing.

Common Questions#

• Can I filter by category or topic name instead of ID?
• Which of the three should I use for monitoring?
• Do I have to memorise the ID lists?

Can I filter by category or topic name instead of ID?#

No. category.id, topic.id and industry.id are the only classification filters, and they take IDs. To translate a human-readable name into an ID at runtime, call the matching autocomplete endpoint — see how to autocomplete filter values with the Suggest API.

Which of the three should I use for monitoring?#

Start from the question you are answering. Broad editorial slicing (“all sports news”, “all politics”) — categories. A named market beat that APITube tracks as a slug (crude oil, automotive news) — topics. Coverage about companies in a sector, regardless of the story’s subject — industries. They combine freely in one request, so a crude-oil feed limited to business coverage can pass both topic.id and category.id.

Do I have to memorise the ID lists?#

No. The docs publish all three reference lists in full, and for interactive inputs the suggest endpoints turn a typed fragment into the right ID on the fly. Most integrations hard-code a handful of IDs once, verify them against the docs lists, and never touch the taxonomy again.