Key concepts: articles, sources, entities, sentiment, stories#

Five concepts make up the APITube News API data model. An article is one news item; a source is the website that published it; entities are the people, companies and places the article mentions; sentiment is the tone of the text; and a story is the group of articles that cover the same event across different sources. Every search you run returns articles, and each article carries its source, entities and sentiment inside it — so understanding these five terms is enough to read any response.

If you have not made a call yet, start with how to run your first news search; this article explains what the fields in that response actually mean.

What is an article?#

An article is the central object — one published news item, returned as one element of the results array. Each article object carries the content (title, description, body), where and when it ran (href, published_at, language), and a block of NLP enrichment computed by APITube: entities, sentiment, keywords, summary, categories, topics and industries. It also includes practical flags such as is_duplicate, is_breaking and read_time, plus a media list for images and video. The id field is the article’s unique identifier — you reuse it to fetch the full article or its related story.

What is a source?#

A source is the publisher an article came from. Every article has a source object describing that publisher: its domain (for example reuters.com), home_page_url, type, political bias (such as left, center or right), a location with the publisher’s country, and a rankings.opr value. OPR (Open Page Rank) is APITube’s authority score for the site — a higher OPR means a more established, widely-referenced publisher. Sources are how you separate a wire service from a personal blog: you can filter or sort by source domain, bias and OPR to keep results to outlets you trust.

What is an entity?#

An entity is a real-world thing APITube detected in the article text — a person, company, place, product and more. Each entry in an article’s entities array has a name, a type, a frequency (how often it appears), its own sentiment, and links to its Wikipedia and Wikidata pages so you can disambiguate “Apple the company” from “apple the fruit.” APITube recognizes nine entity types:

• person, location, organization, brand, product
• natural-disaster, disease, event, sport

Entities are what let you ask “show me every article that mentions this company” instead of guessing keywords — see how to find news mentioning a person or company.

What is sentiment?#

Sentiment is the emotional tone of the text, scored by APITube’s NLP. Each article has a sentiment object with three angles — overall, title and body — and each one carries a polarity (positive, negative or neutral) plus a numeric score. Sentiment is also computed per entity, so an article can be broadly positive overall while being negative toward one company it names. That entity-level sentiment lives inside each entity’s own sentiment block, with a count of positive, neutral and negative mentions. Use the article-level value to gauge a headline’s mood, and the entity-level value to track how one brand or person is being portrayed.

What is a story?#

A story is a group of articles that cover the same real-world event from different outlets. The same news — a product launch, an election result, a disaster — gets written up by dozens of sources, and the story concept ties that coverage together. Each article carries a story reference, and you fetch the rest of the coverage with the /v1/news/story/:id endpoint, which finds other articles whose headlines share the source article’s keywords and ranks them by overlap. Stories are how you go from one article to the full picture of an event — see how to get all articles covering the same story. The related is_duplicate flag marks near-identical re-posts so you can collapse them.

Common Questions#

• What is the difference between an article and a story?
• What types of entities does APITube detect?
• Is sentiment scored for the whole article or per entity?
• What is the difference between categories, topics and industries?

What is the difference between an article and a story?#

An article is a single news item from one source — one row in your results. A story is the set of articles, usually from many sources, that report the same event. One story contains many articles; one article belongs to one story. Use an article when you want a specific piece of coverage, and a story when you want every outlet’s take on the same event.

What types of entities does APITube detect?#

APITube classifies each detected entity as one of nine types: person, location, organization, brand, product, natural-disaster, disease, event and sport. The type field on each entity tells you which one it is, so you can, for example, pull only the organizations mentioned in an article or only the locations.

Is sentiment scored for the whole article or per entity?#

Both. Every article has an overall sentiment (with separate title and body readings), and APITube also scores sentiment toward each individual entity it detects. So a single article can read as neutral overall yet carry clearly negative sentiment toward one company it names — the per-entity score captures that, which the article-level score alone would miss.

What is the difference between categories, topics and industries?#

They are three separate classification layers attached to every article. Categories are the standardized IPTC news taxonomy (such as politics or health), topics are finer-grained subject tags, and industries map an article to a business sector. Each is its own array on the article and its own filter, so you can narrow a search by any of the three independently.