Understanding entities: people, companies, locations#

An entity in the APITube News API is a named thing that appears in an article — a person, a company, a place, a brand, and more. When APITube processes an article, it detects these names, resolves them to a known record, and stores them with the article. Every result you read back carries an entities array where each item describes one named thing: its id, its type, how often it was mentioned, where it was mentioned, and the sentiment expressed toward it.

Because entities are precomputed and stored per article, you can both read them on any result and filter by them at query time — for example, pull only articles that mention a specific company, or only articles that speak negatively about a person.

What is an entity in the APITube News API?#

An entity is a single named thing extracted from the article’s text — not a keyword, but a resolved record with a stable numeric id. The same real-world company keeps the same entity id across every article that mentions it, which is what lets you track one name over time instead of chasing spelling variants. Each entity also links out to external references: a self link to the entity on the API, plus wikipedia and wikidata links when APITube has matched the name to those knowledge bases.

Entities are distinct from categories, topics and industries. Those classify the subject of the article; entities are the concrete names mentioned inside it.

What entity types does APITube recognize?#

Every entity carries a type label. APITube recognizes nine types:

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

If a type cannot be determined, it is returned as unknown. The type is what tells “Apple the company” apart from “apple the fruit,” and it is also how you target a name filter: a person name filter only matches person entities, an organization filter only matches organization entities, and so on.

What does an entity look like in an article?#

Each item in the entities array is a self-contained object. Here is a real location entity as returned by the API:

{
    "id": 1034399,
    "name": "Germany",
    "type": "location",
    "links": {
        "self": "https://api.apitube.io/v1/news/entity/1034399",
        "wikipedia": "https://en.wikipedia.org/wiki/Germany",
        "wikidata": "https://www.wikidata.org/wiki/Q183"
    },
    "frequency": 3,
    "sentiment": {
        "score": -0.42,
        "polarity": "negative",
        "mentions": { "positive": 1, "neutral": 0, "negative": 2 }
    },
    "title": { "pos": [{ "start": 7, "end": 14 }] },
    "body": { "pos": [{ "start": 113, "end": 120 }, { "start": 852, "end": 859 }] },
    "metadata": { "type": "country", "country": { "code": "DE" }, "coordinates": { "lat": 51.1657, "lng": 10.4515 } }
}

Read in plain terms: id is the stable numeric identifier and name is the display name. frequency is how many times the entity was mentioned in the article. The title.pos and body.pos arrays give the exact character offsets of each mention as start and end pairs, so you can highlight the name in place. The sentiment block is the tone directed at this entity, with a score from -1 to 1, a polarity of positive, negative or neutral, and a mentions breakdown counting how many references were positive, neutral and negative. The metadata object holds extra detail that varies by type — for a location it can include the country code and coordinates, and for an organization it can include headquarters and key people.

Locations get a second, flattened view: the article also returns a locations_mentioned array built from its location entities that have a country, giving each one as name, country, lat, lng and type. For a field-by-field breakdown of the whole article object, see the official response structure reference.

How do I find articles that mention a specific entity?#

You filter by entity in two ways. If you know the numeric identifier, pass entity.id — it accepts up to three comma-separated IDs and must be numeric:

curl "https://api.apitube.io/v1/news/everything?entity.id=1034399&api_key=YOUR_API_KEY"

If you only have a name, use the type-specific name filter: person.name, organization.name, location.name or brand.name. APITube resolves the name to its entity record before searching, so the name must match a known entity — if it doesn’t, the request returns a 400 error rather than silently matching text:

curl "https://api.apitube.io/v1/news/everything?organization.name=Netflix&api_key=YOUR_API_KEY"

Each name filter also accepts up to three comma-separated names. For a fuller walkthrough of entity search, see how to find news mentioning a person or company.

How do I read sentiment toward a single entity?#

Because every entity carries its own sentiment, an article can be positive overall while being negative about one company inside it. To act on that, filter with entity.sentiment.polarity (positive, negative or neutral) and narrow the range with entity.sentiment.score.min and entity.sentiment.score.max, both on the -1 to 1 scale. Combine it with an entity selector to ask “articles that speak negatively about this company”:

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

For how entity tone is scored versus article-level tone, see how to get sentiment toward a company or person and how sentiment analysis works.

Common Questions#

• Are entity IDs numeric and stable?
• What is the difference between entities and locations_mentioned?
• Can I filter on more than three entities at once?
• What does the entity frequency count?

Are entity IDs numeric and stable?#

Yes. Each entity has a numeric id, and the entity.id filter parses it as an integer — non-numeric values are rejected. The same entity keeps the same id across articles, so an entity ID is the reliable way to track one exact company, person or place over time, without depending on how the name was spelled in a given article.

What is the difference between entities and locations_mentioned?#

The entities array holds every named thing of any type, including location entities. The locations_mentioned array is a convenience view derived from those location entities that carry a country: it flattens each one to name, country, lat, lng and type. Use entities for the full picture and per-entity sentiment; use locations_mentioned when you just need clean geographic points for a map.

Can I filter on more than three entities at once?#

No. Both entity.id and the name filters (person.name, organization.name, location.name, brand.name) take at most three comma-separated values per request; extra values beyond the first three are ignored. To cover more entities, run separate requests or combine an entity filter with broader filters such as category or topic.

What does the entity frequency count?#

The frequency value is how many times that entity was mentioned in the single article you are reading — not how many articles mention it across the archive. A higher frequency means the name is more central to that specific piece. To find which entities are trending across many articles instead, aggregate with the trends endpoint on the entity.id field.