What’s inside a news article?#

Every article APITube returns is a single JSON object with the same fixed shape, whether it comes from a search, a stream, or a single-article lookup. Alongside the obvious content fields — title, description, body, href, image, published_at — each object carries machine-readable enrichment: categories, topics, industries, entities, three levels of sentiment, a source profile, readability scores, social shares, and status flags. That enrichment is what turns a raw headline into something you can filter, score, and act on.

If you are new to the vocabulary here (article vs source vs entity vs story), start with key concepts, then come back for the field-by-field breakdown.

What does a news article object look like?#

Here is a trimmed example showing the overall structure (most arrays and nested fields are abbreviated):

{
  "id": 1234567,
  "href": "https://www.example-news.com/markets/...",
  "published_at": "2026-06-28T09:15:00.000Z",
  "title": "Central bank holds rates steady",
  "description": "The decision was widely expected by markets...",
  "language": "en",
  "author": { "id": 88, "name": "Jane Doe" },
  "categories": [
    { "id": 5012, "name": "Sport", "score": 0.92, "taxonomy": "iptc_mediatopics",
      "links": { "self": "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:15000000" } }
  ],
  "entities": [
    { "id": 4521, "name": "Federal Reserve", "type": "organization", "frequency": 3,
      "sentiment": { "score": 0.1, "polarity": "neutral",
        "mentions": { "positive": 1, "neutral": 2, "negative": 0 } } }
  ],
  "sentiment": { "overall": { "score": 0.2, "polarity": "positive" }, "title": {}, "body": {} },
  "source": { "id": 77, "domain": "example-news.com", "type": "news", "bias": "center",
    "rankings": { "opr": 8 }, "location": { "country_name": "United States", "country_code": "US" } },
  "readability": { "flesch_reading_ease": 55.3, "automated_readability_index": 9.4, "reading_age": 14 },
  "shares": { "total": 120, "facebook": 80, "twitter": 30, "reddit": 10 },
  "read_time": 4, "words_count": 812,
  "is_breaking": false, "is_duplicate": false,
  "story": { "id": 1234567, "uri": "https://api.apitube.io/v1/news/story/1234567" }
}

What are the core content fields?#

These are the human-readable parts of the article:

• id — the numeric article identifier, stable across endpoints.
• title — the headline.
• description — a short summary, stripped of HTML.
• body — the full article text as plain text, while body_html keeps the original HTML markup. They hold the same content in two forms; for retrieving the raw body and HTML directly, see how to get the raw article body and HTML.
• href — the canonical URL of the original article, and image — its lead image URL.
• published_at — the publish time in ISO 8601 (UTC), and language — the detected language code, such as en.
• author — an { id, name } object when a byline was detected.

How are categories, topics and entities structured?#

Classification fields are arrays of objects, not bare strings, so each tag carries context:

• categories — IPTC Media Topics, each with an id, name, a relevance score, the taxonomy, and a self link to that category’s feed.
• topics and industries — additional thematic tags, each with an id, name and self link (topics also carry a score).
• keywords — a flat array of salient terms.
• entities — the people, organizations, places and things mentioned. Each entity has an id, name, a type (one of person, location, organization, brand, product, natural-disaster, disease, event, sport), a frequency count, links to Wikipedia and Wikidata where known, and its own sentiment block. The title.pos and body.pos arrays mark where the entity appears.
• locations_mentioned — a convenience array distilled from location entities, each with a name, country code, and lat/lng when available.

What sentiment, source and quality data is included?#

Beyond classification, every article is scored and attributed:

• sentiment — three views of tone: overall, title and body, each with a numeric score and a polarity label. Entities additionally carry sentiment toward that entity, so you can tell whether a company was mentioned favourably even in a neutral article.
• source — a profile of the publisher: domain, home_page_url, type, political bias, rankings.opr (the source’s OPR authority score), location (country name and code), and a favicon.
• readability — reading-difficulty metrics including flesch_reading_ease, flesch_kincaid_grade, automated_readability_index, a difficulty_level, target_audience, and an estimated reading_age.
• Length counters — words_count, sentences_count, paragraphs_count, characters_count, and read_time (an estimated reading time).

Which fields tell you about engagement and status?#

A few fields describe an article’s reach and state:

• shares — social-share counts (total, facebook, twitter, reddit). For very fresh articles these ramp up over roughly the first two hours after publication, so counts on a brand-new article are partial by design.
• media and links — arrays of { url, type } for attached media and outbound links; summary is an array of key sentences, each with its own sentiment.
• story — the cluster this article belongs to, with an id and a uri to fetch every article covering the same event.
• Flags — is_breaking marks high-importance news, is_duplicate marks near-identical reprints, and is_free reports whether the original article is freely readable at its source (the opposite of paywalled). Note is_free is about the source article, not your subscription.

Common Questions#

Why are some fields shortened with a marker?#

Long fields such as body, description, href, image and source URLs are truncated when the response is a preview rather than full content. On the Free plan the cut-off value is tagged ...[Upgrade subscription plan]; with a test key the same preview is tagged ...[Test mode — use a live key for full content] instead. Either way the schema is identical to a paid response — the field names and structure do not change, only the values are shortened. Use a paid plan with a live key to receive full content.

How do I get only the fields I need?#

Use the fl parameter to request a subset of fields, which shrinks the response and speeds up parsing — for example fl=id,title,source.domain,sentiment.overall. See how to select specific response fields. The field names you pass are exactly the ones described on this page.

What’s the difference between body and body_html?#

body is the article text as plain text with HTML stripped out, which is what you want for NLP, search indexing, or display in a plain context. body_html preserves the original HTML markup (paragraphs, links, formatting), which is useful when you want to render the article as it appeared. Both contain the same article content.

What does locations_mentioned contain?#

locations_mentioned is built from the location entities in the article that have a known country. Each item gives a place name, a country code, and lat/lng coordinates when available — a quick way to map where an article is about without walking the full entities array yourself.