How to find news mentioning a person or company#

To return only articles that mention a specific person or company, add person.name for people or organization.name for companies — for example person.name=Elon Musk or organization.name=Netflix. APITube looks each name up against the entities it already tracks and returns only articles where that entity is actually mentioned. For an exact, unambiguous match, use the numeric entity.id instead.

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

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. If you omit every entity parameter, no entity filter is applied and articles mentioning anyone are returned.

What is entity filtering?#

APITube tags every article with the named entities it mentions — people, companies, brands, locations and more. Entity filtering keeps only the articles linked to the entity you ask for, instead of matching loose keywords. That means organization.name=Apple returns coverage about the company Apple, not articles that happen to contain the word “apple”.

Each entity has a type, and the parameter you use picks the type:

• person.name matches people (type person).
• organization.name matches companies and organizations.
• brand.name matches brands.
• location.name matches places.

Use the parameter that matches what you are tracking. A company name passed to person.name will not be found, because that parameter only looks at people.

How to find news about a person, company or brand#

Pass the exact name to the matching parameter. Each accepts up to three values separated by commas, and articles mentioning any of them are returned (OR logic):

curl "https://api.apitube.io/v1/news/everything?person.name=Elon Musk&api_key=YOUR_API_KEY"

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

Spaces in a name should be URL-encoded (Elon%20Musk). Each name must be 1 to 120 characters long. The name has to match an entity APITube already tracks: an unknown person.name returns HTTP 400 with error ER0216, an unknown organization.name returns ER0220, and an unknown brand.name returns ER0222. Because the request stops on the first name it cannot resolve, confirm the spelling before filtering — the easiest way is to read it from a response or from entity autocomplete (below).

How to filter by a precise entity ID#

Names can be ambiguous, so APITube gives every entity a stable numeric entity.id. Filtering by ID is the most reliable way to pin results to one entity, and it works for any type — person, company, brand or location — without choosing a type-specific parameter:

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

entity.id accepts up to three IDs, comma-separated, with OR logic. Each value must be an integer of 1 to 30 characters; a non-numeric value returns error ER0127 and an out-of-range length returns ER0128, both HTTP 400. Unlike a name, an entity.id is not checked against the directory, so a valid-looking ID that matches no entity simply returns no articles instead of failing the request.

To discover the right ID, use entity autocomplete: GET /v1/suggest/entities with a prefix returns matching entities, each with its id, name and type. A missing prefix returns error ER0346.

curl "https://api.apitube.io/v1/suggest/entities?prefix=Tesla&api_key=YOUR_API_KEY"

How to combine and exclude entities#

Different entity parameters combine with AND, so listing a person and a company in the same request returns only articles that mention both. This is useful for narrowing to coverage about one person at one company:

curl "https://api.apitube.io/v1/news/everything?person.name=Elon Musk&organization.name=Tesla&api_key=YOUR_API_KEY"

To return everything except a given entity, use the ignore. variants — ignore.entity.id, ignore.person.name and ignore.organization.name — which follow the same rules (comma-separated, up to three). An unknown name in ignore.person.name returns ER0217, and ignore.organization.name returns ER0221. Entity filtering is part of the shared filter chain, so it also combines with author, language, date and sorting filters in one request.

How to get sentiment toward a specific company or person#

When you select an entity, you can also restrict results by the tone expressed toward that entity using entity.sentiment.polarity (positive, negative or neutral) and the numeric range entity.sentiment.score.min / entity.sentiment.score.max (each between -1 and 1):

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

A polarity other than the three allowed values returns ER0290; a score outside -1…1 returns ER0291 (min) or ER0292 (max). This is sentiment aimed at the entity itself, which is different from the article’s overall tone — see How to filter news by sentiment for the document-level filter.

What does the entities object in the response contain?#

Every article carries an entities array, so you can confirm the match and reuse the exact id in follow-up requests:

{
    "entities": [
        {
            "id": 314,
            "name": "Netflix",
            "type": "organization",
            "frequency": 4,
            "sentiment": { "score": 0.42, "polarity": "positive" }
        }
    ]
}

The id here is exactly the value you pass back into entity.id, the type tells you which name parameter applies, frequency is how many times the entity is mentioned, and sentiment is the tone toward that entity. For the full list of accepted names and values, see the official parameters reference.

Common Questions#

• How many people or companies can I filter by at once?
• Should I use a name or an entity.id?
• What is the difference between person.name and organization.name?
• How do I find an entity’s ID?

How many people or companies can I filter by at once?#

Up to three per parameter. entity.id, person.name, organization.name, brand.name and their ignore. variants each accept a comma-separated list, and only the first three values are applied. Multiple values inside one parameter use OR logic, so an article matches if it mentions any of them. Different parameters combine with AND, so adding a second parameter narrows the results.

Should I use a name or an entity.id?#

Both target the same entities. A name (person.name, organization.name, brand.name) is easier to read, but it must exactly match a tracked entity or the request fails — for example ER0216 for an unknown person or ER0220 for an unknown organization. A numeric entity.id is more robust: it is a fixed identifier, is not validated against the directory, and never blocks the request — an unknown ID just returns no articles. Read either value from an article’s entities array.

What is the difference between person.name and organization.name?#

They look up different entity types. person.name only matches people, and organization.name only matches companies and organizations, so passing a company to person.name returns “not found”. If you are unsure of the type, filter by entity.id instead, which is type-agnostic and matches the exact entity regardless of whether it is a person, company, brand or location.

How do I find an entity’s ID?#

Call GET /v1/suggest/entities?prefix= with the start of the name. The response lists matching entities with their id, name and type, which you can drop straight into entity.id. You can also read the id from the entities array of any article in a normal search response and reuse it in your next request.