How to filter news by sentiment#

To return only articles with a given tone, add the sentiment.overall.polarity parameter with positive, negative or neutral. The APITube News API tags every article with a sentiment polarity, and this filter keeps only the articles that match. This returns positive-toned coverage:

curl "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=positive&api_key=YOUR_API_KEY"

You can pass the key as the api_key query parameter or as an X-API-Key header. If you omit any sentiment parameter, no sentiment filter is applied and articles of every tone are returned.

What sentiment values can I filter by?#

sentiment.overall.polarity accepts three values: positive, negative and neutral. The value is case-insensitive. Polarity is the simplest sentiment filter — it answers “is the overall tone good, bad or flat?” without you having to reason about numbers.

Sentiment is measured on three separate layers, and each has its own polarity parameter:

• sentiment.overall.polarity — the article’s overall tone.
• sentiment.title.polarity — the tone of the headline only.
• sentiment.body.polarity — the tone of the article body only.

This matters because a headline and the body it sits on do not always agree. The split lets you target, for example, articles whose body reads negative even when the headline is neutral.

How to filter by a numeric sentiment score#

For finer control than positive/negative/neutral, filter by the numeric score. Every sentiment layer is also scored on a scale from -1 (most negative) to 1 (most positive), where values near 0 are neutral. Use .score.min and .score.max to set a range. This returns only strongly positive articles:

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

The score parameters are sentiment.overall.score, sentiment.overall.score.min and sentiment.overall.score.max, with matching sentiment.title.* and sentiment.body.* variants. A value outside the -1 to 1 range, or a non-numeric value, returns HTTP 400 with a sentiment validation error (for example ER0095 for an out-of-range sentiment.overall.score.min). Combine a minimum and a maximum to bracket a band, such as mildly negative coverage:

curl "https://api.apitube.io/v1/news/everything?sentiment.overall.score.min=-0.5&sentiment.overall.score.max=-0.1&api_key=YOUR_API_KEY"

How to find articles where the headline and body disagree#

Two boolean helpers compare the title tone against the body tone. sentiment.mixed=1 returns articles where the title polarity differs from the body polarity, and sentiment.consistent=1 returns articles where they match. Both accept only 0 or 1 (an invalid value returns ER0243 for mixed or ER0244 for consistent):

curl "https://api.apitube.io/v1/news/everything?sentiment.mixed=1&api_key=YOUR_API_KEY"

A mismatch between an emotionally charged headline and a flatter body is a common signal of clickbait. For a purpose-built filter on that pattern, see How to detect and filter clickbait.

How to combine sentiment with other filters#

Sentiment is part of the shared filter chain, so it stacks with any other filter and with sorting. This returns the newest positive English articles about a company:

curl "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=positive&language.code=en&organization.name=Netflix&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

The same sentiment parameters work on /v1/news/everything, /v1/news/top-headlines, /v1/news/story, /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity. To narrow by subject at the same time, pair sentiment with a category filter.

What does the sentiment data look like in the response?#

Every article carries a sentiment object with all three layers, so you can read the exact score and polarity behind the filter:

{
    "sentiment": {
        "overall": { "score": 0.62, "polarity": "positive" },
        "title": { "score": 0.10, "polarity": "neutral" },
        "body": { "score": 0.71, "polarity": "positive" }
    }
}

Each layer reports a score from -1 to 1 and a polarity label. These are the same values the filters act on: sentiment.overall.polarity matches sentiment.overall.polarity in this object, and sentiment.body.score.min matches sentiment.body.score.

Common Questions#

• What is the difference between polarity and score?
• Can I filter the headline and body separately?
• What sentiment score range does the API use?
• Which endpoints support sentiment filtering?

Can I filter the headline and body separately?#

Yes. sentiment.title.polarity and sentiment.title.score(.min/.max) filter on the headline alone, while sentiment.body.polarity and sentiment.body.score(.min/.max) filter on the article body. Use sentiment.overall.* when you want one combined tone, and the title or body variants when the two parts of an article may disagree.

What sentiment score range does the API use?#

Every sentiment score runs from -1 to 1: -1 is the most negative, 1 is the most positive, and values near 0 are neutral. Any .score, .score.min or .score.max value outside that range is rejected with an HTTP 400 sentiment error, so keep your thresholds within -1 to 1.

Which endpoints support sentiment filtering?#

The sentiment parameters work on /v1/news/everything, /v1/news/top-headlines, /v1/news/story, /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity. Because they run in the shared filter chain, they combine freely with other filters such as language.code, published_at.start and category.id, and with sort.by.