How to get sentiment toward a specific company or person#

To filter by the tone aimed at a specific company or person — not the article’s overall mood — pair an entity selector with the entity.sentiment.* parameters. For example, to return articles that speak negatively about Tesla:

curl "https://api.apitube.io/v1/news/everything?organization.name=Tesla&entity.sentiment.polarity=negative&api_key=YOUR_API_KEY"

The entity.sentiment.polarity constraint is matched against each entity’s own sentiment inside the article, so you get coverage where Tesla specifically is framed negatively — even if the rest of the article is upbeat.

What is entity-level sentiment versus article sentiment?#

Entity-level sentiment is the tone an article expresses toward one entity it mentions. It is different from article sentiment, which scores the whole piece. A single article can be broadly positive while still being negative about one company in it — for instance, a market roundup that praises the sector but criticizes one firm.

• Article sentiment — the overall tone of the article. Filter it with sentiment.overall.polarity. See How to filter news by sentiment.
• Entity sentiment — the tone toward a named company, person or brand in the article. Filter it with entity.sentiment.polarity plus a selector like organization.name.

Use entity sentiment when you are monitoring how a specific brand or person is portrayed; use article sentiment when you care about the mood of the coverage as a whole.

Which parameters set entity sentiment?#

Three parameters constrain the sentiment toward the selected entity:

• entity.sentiment.polarity — positive, negative or neutral. Any other value returns 400 with error code ER0290.
• entity.sentiment.score.min — a number from -1 to 1; the lower bound of the entity’s sentiment score. Out-of-range values return ER0291.
• entity.sentiment.score.max — a number from -1 to 1; the upper bound. Out-of-range values return ER0292.

You can use polarity on its own, a score range on its own, or combine them. This returns articles where Apple is strongly negative — a score between -1 and -0.3:

curl "https://api.apitube.io/v1/news/everything?organization.name=Apple&entity.sentiment.score.min=-1&entity.sentiment.score.max=-0.3&api_key=YOUR_API_KEY"

How to pick which entity the sentiment applies to#

The sentiment filter attaches to whichever entity selector you send. The selectors that work with entity.sentiment.* include:

• organization.name — a company, e.g. organization.name=Netflix
• person.name — a person, e.g. person.name=Elon Musk
• brand.name — a brand
• entity.id — a numeric entity ID (integer; use it when you already know the exact entity)

Each name selector accepts up to 3 comma-separated values. Names are resolved to entities before the query runs, so a name the system does not recognize returns an error (for example, an unknown organization.name returns ER0220) rather than silently empty results. Track a person’s portrayal like this:

curl "https://api.apitube.io/v1/news/everything?person.name=Elon%20Musk&entity.sentiment.polarity=negative&api_key=YOUR_API_KEY"

If you send entity.sentiment.* without any selector, it matches articles that contain any entity with that sentiment — useful for surfacing strongly negative coverage across the board, but far broader than a targeted brand check.

How does entity sentiment appear in the response?#

Every article in the response carries an entities array, and each entity reports its own sentiment block:

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

The score is a number from -1 to 1, polarity is the label your filter matched on, and mentions counts how many times the entity was referenced positively, neutrally and negatively. After filtering, read this block to confirm exactly how each result framed your entity.

Common Questions#

• Can I combine entity sentiment with other filters?
• What is the difference from sentiment.overall.polarity?
• Why did my request return an error instead of results?

Can I combine entity sentiment with other filters?#

Yes. entity.sentiment.* runs as part of the standard filter chain on /v1/news/everything, so you can add language.code, published_at.start, category.id and any other filter in the same request. For example, restrict negative Tesla coverage to English articles from the last week by adding language.code=en and a date range alongside the entity parameters.

What is the difference from sentiment.overall.polarity?#

sentiment.overall.polarity filters on the article’s overall tone, while entity.sentiment.polarity filters on the tone toward the entity you name. If you want “articles that are negative about Tesla,” use the entity version; if you want “articles that are negative overall,” use the overall version. They can be combined when you need both conditions.

Why did my request return an error instead of results?#

The most common causes are validation errors: an invalid entity.sentiment.polarity value returns ER0290, and a score outside -1 to 1 returns ER0291 (min) or ER0292 (max). If you used a name selector, an unrecognized name returns a “not found” error (such as ER0220 for an organization) — check the spelling or use the numeric entity.id instead. For the full parameter reference, see the News API parameters documentation.