> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How to search articles by entity

> Find articles mentioning specific people, organizations, locations, or other named entities.

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](/news-api/libraries/python) installed for your language,
  or cURL for quick testing

## Steps

<Steps>
  <Step title="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.
  </Step>

  <Step title="Search by entity">
    Combine keywords with entity recognition in a single request. This example
    finds AI articles that mention OpenAI or Microsoft as organizations:

    <CodeGroup>
      ```bash cURL theme={null}
      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"
        }'
      ```

      ```python Python theme={null}
      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)
      ```

      ```typescript TypeScript theme={null}
      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));
      ```

      ```java Java theme={null}
      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()));
      ```
    </CodeGroup>
  </Step>

  <Step title="Review the NLP fields in the response">
    The response includes entity information in the `nlp` object for each
    article:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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:

    <CodeGroup>
      ```bash cURL theme={null}
      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
        }'
      ```

      ```python Python theme={null}
      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)
      ```

      ```typescript TypeScript theme={null}
      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));
      ```

      ```java Java theme={null}
      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()));
      ```
    </CodeGroup>

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

    ```json theme={null}
    {
      "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 }
            ]
          }
        }
      ]
    }
    ```
  </Step>

  <Step title="Combine multiple entity types">
    Combine multiple entity parameters and advanced operators for complex
    searches:

    ```json theme={null}
    {
      "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:

    ```json theme={null}
    {
      "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:

    ```json theme={null}
    {
      "q": "NEAR(\"artificial intelligence\", \"regulation\", 10)",
      "ORG_entity_name": "OpenAI OR Google",
      "search_in": "title_content,title_content_translated",
      "include_nlp_data": true
    }
    ```
  </Step>
</Steps>

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

## See also

* [Search in translations](/news-api/how-to/search-in-translations)
* [Build search queries](/news-api/how-to/build-search-queries)
* [NLP features](/news-api/guides-and-concepts/nlp-features)