How does sentiment analysis work?#

APITube runs sentiment analysis on every article when it is processed, and stores the result with the article — so each result you read back already carries a sentiment reading. That reading has two parts: a numeric score from -1 to 1, and a polarity label of positive, negative or neutral. Because the value is precomputed and stored, the News API does not re-analyze text at query time — it reads the stored sentiment, which is what lets you filter, sort and display it instantly.

Sentiment is measured at several levels of the same article: the overall article, the headline, the body, each key sentence, and each named entity. Each level gets its own score and polarity, so you can ask “what is the mood of this piece?” and “how is this one company framed inside it?” separately.

What is sentiment in the APITube News API?#

Sentiment is the automated assessment of the emotional tone of an article. APITube expresses it two ways at once:

• Polarity — a plain label: positive, negative or neutral. Use this when you just need the direction of the tone.
• Score — a number from -1 (most negative) to 1 (most positive), where values close to zero are neutral. Use this when you need a threshold, a ranking, or a band.

The polarity and the score describe the same tone at different resolutions: the score is the precise reading, and the polarity is the human-readable bucket it falls into. Every sentiment reading in the response gives you both.

What do the sentiment score and polarity mean?#

The score is a float on a fixed scale from -1 to 1. A value near 1 means strongly positive tone, a value near -1 means strongly negative tone, and a value close to 0 is treated as neutral. The polarity is the label for that value. Here is the article-level sentiment object as returned by the API, with real example values:

{
    "sentiment": {
        "overall": { "score": -0.01, "polarity": "neutral" },
        "title": { "score": -0.09, "polarity": "negative" },
        "body": { "score": 0.07, "polarity": "positive" }
    }
}

Notice that the overall, title and body layers can each land on a different polarity — a headline can read negative while the body reads mildly positive. That split is intentional and is what powers the disagreement filters described below.

Which parts of an article get their own sentiment?#

APITube attaches sentiment at five levels of the same article, each with a score and polarity:

• Overall — sentiment.overall — the tone of the whole article.
• Title — sentiment.title — the tone of the headline alone.
• Body — sentiment.body — the tone of the article text alone.
• Key sentences — each item in the article’s summary array carries its own sentiment object, so you can see the tone sentence by sentence.
• Entities — every entity in the entities array has its own sentiment, including a mentions breakdown that counts how often the entity was referenced positively, neutrally and negatively.

The entity-level block looks like this in the response:

{
    "entities": [
        {
            "name": "Tesla",
            "type": "organization",
            "sentiment": {
                "score": -0.62,
                "polarity": "negative",
                "mentions": { "positive": 1, "neutral": 2, "negative": 5 }
            }
        }
    ]
}

This is why “the article is positive overall” and “the article is negative about one company in it” can both be true at the same time. To act on entity tone, see how to get sentiment toward a company or person.

Why can the headline and the body have different sentiment?#

Because the title and body are scored separately, they do not always agree — and that gap is itself a useful signal. APITube exposes it three ways:

• sentiment.mixed=1 returns articles where the title polarity differs from the body polarity, and sentiment.consistent=1 returns articles where they match.
• sentiment_gap.min and sentiment_gap.max filter on the size of the gap between the title and body scores, on a scale from 0 to 2.
• is_clickbait=1 targets a specific pattern: a title whose polarity differs from the body and whose title score is strongly charged. It is a purpose-built shortcut for the “dramatic headline, flat article” case.

For example, to surface articles where the headline and body diverge sharply:

curl "https://api.apitube.io/v1/news/everything?sentiment_gap.min=0.5&api_key=YOUR_API_KEY"

How do I use sentiment in a request?#

Sentiment is part of the shared filter chain, so it stacks with any other filter and with sorting. Filter by tone with sentiment.overall.polarity, narrow to a numeric band with sentiment.overall.score.min/.max, or rank results with sort.by=sentiment.overall.score. This returns the most positive coverage of a company first:

curl "https://api.apitube.io/v1/news/everything?organization.name=Netflix&sort.by=sentiment.overall.score&sort.order=desc&api_key=YOUR_API_KEY"

You can pass the key as the api_key query parameter or as an X-API-Key header. For the full set of tone filters and score ranges, see how to filter news by sentiment, and for field-by-field detail see the official response structure reference.

Common Questions#

• What sentiment values does APITube use?
• Does every article have a sentiment score?
• Can I sort articles by how positive or negative they are?
• Is sentiment the same as the entity sentiment?

Does every article have a sentiment score?#

Every article in the response includes the sentiment object with the overall, title and body layers, so the structure is always present. When a value is not available for an article, that layer defaults to a score of 0 and an empty polarity string, rather than being dropped. If you rely on sentiment, it is safe to read the field on any result; just treat an empty polarity as “not scored” rather than as neutral.

Can I sort articles by how positive or negative they are?#

Yes. Set sort.by=sentiment.overall.score (or sentiment.title.score / sentiment.body.score) and choose the direction with sort.order=asc or sort.order=desc. Descending order puts the most positive articles first; ascending order puts the most negative first. Sorting works alongside any filter, so you can rank only positive English articles, or only articles about one company.

Is sentiment the same as the entity sentiment?#

No. sentiment.overall is the tone of the whole article, while each entity’s sentiment in the entities array is the tone directed at that specific company, person or brand. Use the overall value for “how does this article read?” and the entity value for “how is this one name framed?” — they are separate fields and can disagree within the same article.