How to search articles by entity

Named Entity Recognition (NER) in News API lets you find articles mentioning specific people, organizations, locations, or other named entities. Entity search provides more precise results than keyword searches and works across all languages using English entity names.

Before you begin

Make sure you have the following:

An active News API key
NLP functionality enabled in your subscription plan
The Newscatcher SDK installed for your language, or cURL for quick testing

Steps

Understand entity types

News API recognizes four entity types, each available as a separate request parameter:

Parameter	Entity type	Examples
`PER_entity_name`	Person names	`"Tim Cook"`, `"Elon Musk"`
`ORG_entity_name`	Organization names	`"Apple"`, `"European Union"`
`LOC_entity_name`	Location names	`"California"`, `"Brussels"`
`MISC_entity_name`	Other entities	Products, events, nationalities

All entity parameters support boolean operators (AND, OR, NOT), proximity search with NEAR, and count-based filtering.

Search by entity

Combine keywords with entity recognition in a single request. This example finds AI articles that mention OpenAI or Microsoft as organizations:

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "\"artificial intelligence\"",
    "ORG_entity_name": "OpenAI OR Microsoft",
    "include_nlp_data": true,
    "lang": "en"
  }'

from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")

response = client.search.post(
    q="\"artificial intelligence\"",
    org_entity_name="OpenAI OR Microsoft",
    include_nlp_data=True,
    lang="en",
)

for article in response.articles:
    print(article.title)

import { NewscatcherApiClient } from "newscatcher-sdk";

const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });

const response = await client.search.post({
  q: '"artificial intelligence"',
  orgEntityName: "OpenAI OR Microsoft",
  includeNlpData: true,
  lang: "en",
});

response.articles?.forEach((article) => console.log(article.title));

import com.newscatcher.api.NewscatcherApiClient;
import com.newscatcher.api.resources.search.requests.PostSearchRequest;

NewscatcherApiClient client = NewscatcherApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();

var response = client.search().post(
    PostSearchRequest.builder()
        .q("\"artificial intelligence\"")
        .orgEntityName("OpenAI OR Microsoft")
        .includeNlpData(true)
        .lang("en")
        .build()
);

response.getArticles().forEach(a -> System.out.println(a.getTitle()));

Review the NLP fields in the response

The response includes entity information in the nlp object for each article:

{
  "status": "ok",
  "total_hits": 325,
  "articles": [
    {
      "title": "OpenAI Backs California Bill for AI Content Labeling",
      "language": "en",
      "nlp": {
        "ner_PER": [],
        "ner_ORG": [
          { "entity_name": "OpenAI", "count": 8 },
          { "entity_name": "Microsoft", "count": 2 }
        ],
        "ner_LOC": [
          { "entity_name": "California", "count": 2 }
        ],
        "ner_MISC": [
          { "entity_name": "AB 3211", "count": 7 }
        ]
      }
    }
  ]
}

The ner_* fields show entities found in the original content with their mention counts.

Search entities across languages

To find entities in non-English articles, include translated content in your search. This example finds European Central Bank coverage in four languages using English entity names:

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "\"monetary policy\"",
    "ORG_entity_name": "\"European Central Bank\" OR \"Federal Reserve\"",
    "search_in": "title_content,title_content_translated",
    "countries": ["DE", "FR", "IT", "ES"],
    "include_nlp_data": true,
    "include_translation_fields": true
  }'

from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")

response = client.search.post(
    q="\"monetary policy\"",
    org_entity_name="\"European Central Bank\" OR \"Federal Reserve\"",
    search_in="title_content,title_content_translated",
    countries=["DE", "FR", "IT", "ES"],
    include_nlp_data=True,
    include_translation_fields=True,
)

for article in response.articles:
    print(article.title)

import { NewscatcherApiClient } from "newscatcher-sdk";

const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });

const response = await client.search.post({
  q: '"monetary policy"',
  orgEntityName: '"European Central Bank" OR "Federal Reserve"',
  searchIn: "title_content,title_content_translated",
  countries: ["DE", "FR", "IT", "ES"],
  includeNlpData: true,
  includeTranslationFields: true,
});

response.articles?.forEach((article) => console.log(article.title));

import com.newscatcher.api.NewscatcherApiClient;
import com.newscatcher.api.resources.search.requests.PostSearchRequest;
import java.util.List;

NewscatcherApiClient client = NewscatcherApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();

var response = client.search().post(
    PostSearchRequest.builder()
        .q("\"monetary policy\"")
        .orgEntityName("\"European Central Bank\" OR \"Federal Reserve\"")
        .searchIn("title_content,title_content_translated")
        .countries(List.of("DE", "FR", "IT", "ES"))
        .includeNlpData(true)
        .includeTranslationFields(true)
        .build()
);

response.getArticles().forEach(a -> System.out.println(a.getTitle()));

The response includes translation_ner_* fields with entities extracted from the translated content:

{
  "articles": [
    {
      "title": "EZB senkt Leitzins auf 3,25 Prozent",
      "title_translated_en": "ECB cuts key interest rate to 3.25 percent",
      "language": "de",
      "nlp": {
        "ner_ORG": null,
        "translation_ner_ORG": [
          { "entity_name": "European Central Bank", "count": 3 }
        ]
      }
    }
  ]
}

Combine multiple entity types

Combine multiple entity parameters and advanced operators for complex searches:

{
  "q": "\"trade policy\" OR tariffs",
  "ORG_entity_name": "\"World Trade Organization\" OR \"European Commission\"",
  "PER_entity_name": "\"Ursula von der Leyen\"",
  "LOC_entity_name": "\"Brussels\" OR \"Geneva\"",
  "search_in": "title_content,title_content_translated",
  "include_nlp_data": true,
  "include_translation_fields": true
}

Use COUNT for frequency-based filtering:

{
  "q": "\"tech industry\"",
  "ORG_entity_name": "COUNT(\"Apple\", 2, \"gt\") OR COUNT(\"Microsoft\", 2, \"gt\")",
  "include_nlp_data": true
}

Combine entity search with proximity operators:

{
  "q": "NEAR(\"artificial intelligence\", \"regulation\", 10)",
  "ORG_entity_name": "OpenAI OR Google",
  "search_in": "title_content,title_content_translated",
  "include_nlp_data": true
}

For comprehensive global coverage, always include both title_content and title_content_translated in your search_in parameter when searching entities across languages.

Get started

Guides and concepts

How to

Troubleshooting

API Reference

Libraries

How to search articles by entity

Before you begin

Steps

See also

​Before you begin

​Steps

​See also

Before you begin

Steps

See also