Looking for news mentioning a specific Person, Company or Product is a common application for our users.

Use the following recommendations to maximize your chances of getting the most relevant results using our News API.

Advice #1: Always use double quotes (") in q parameter

Use double quotes (") for the exact match.

Example of the search intent

I am looking for articles about Elon Musk.

Query to do it

When you want to search for articles that mention Elon Musk you should do the following query:

If you write q=Elon Musk then, it will be treated as q=Elon AND Musk. In that case, every article that mentions both elon and musk somewhere in the text will match.

Here are the Operators that can help you narrow down your search.

AND

AND operator makes tokens from both sides to be present in the text of an article.

AND is the default operator. When your **q** input is more than 1 word, **AND** operator is added between each word behind the scenes.

Example of the search intent

I am looking for articles where all three Apple, Microsoft, and Tesla company names are mentioned

Query to do it

q=Apple AND Microsoft AND Tesla

Since AND is the default operator, these two queries are exactly the same:

q=Apple AND Microsoft AND Tesla

q=Apple Microsoft Tesla

OR

OR operator means that either the left or the right sides of OR have to be satisfied.

Example of the search intent

I am looking for an article where at least one of these wealthy men Elon Musk, Tim Cook, Bill Gates is mentioned.

Query to do it

q="Elon Musk" OR "Tim Cook" OR "Bill Gates"

Round brackets ()

AND and OR operators can be used together. You can also logically group a set of words or phrases by using round brackets ()

Example of the search intent

I am looking for articles where either Elon Musk is mentioned with either Starlink or Tesla.

Query to do it

q="Elon Musk" AND (Starlink OR Tesla)

NOT

Use NOT operator when you want the token from its right to not be present.

Example of the search intent

I am looking for articles about Apple and MacBook product series, but I do not want any news related to iPhone or IPad

Query to do it

q=Apple AND MacBook NOT (IPhone OR IPad)

More examples

The more operator and logical combinations you use, the more relevant results you get.

Let’s look at some more examples

Example of the search intent

I am looking for articles about Apple company. “Apple” as a word, can have multiple definitions. So, when I search for the word “Apple”, I want to have some other words related to Apple in this case, like their products: MacBook, iPhone, IPad, or executive Chiefs, like Tim Cook, Katherine Adams, Eddy Cue. I add to the search “Apple Inc” as well because I am pretty sure it is about Apple company. I do not want to have any other big tech company mentioned in the article, so I filter out Microsoft, Amazon, Tencent, and Facebook.

Query to do it

q=(Apple AND (MacBook OR iPhone OR IPad OR "Tim Cook" OR "Katherine Adams" OR "Eddy Cue")) OR "Apple Inc" NOT (Microsoft OR Amazon OR Tencent OR Facebook)

We have around 60 000 news sources, but not all of them are relevant to you.

[sources]

Use [sources] parameter to filter down your search to the articles coming only from mentioned news sources.

Example of the search intent

I am looking for business-related articles about “Elon Musk”. Personally, I have already seen relevant news coming from businessinsuder.com, businessjournaldaily.com, businessreport.com. I want to have articles only from these sources.

Parameters to use

q="Elon Musk"
sources=businessinsider.com,businessjournaldaily.com,businessreport.com

[not_sources]

Use [not_sources] parameter to exclude concrete news domains from your search.

Example of the search intent

I am looking for business-related articles about “Elon Musk”. I am not aware of any business-related news source. But, I am sure that news coming from gossipbucket.com, hollywoodlife.com, or hollywoodreporter.com is not the type of news I would like to get. So I exclude these news domains.

Parameters to use

q="Elon Musk"
sources=gossipbucket.com,hollywoodlife.com,hollywoodreporter.com

/v2/sources endpoint

Use our /v2/sources endpoint to get a list of news sources available in our database. So, this can give you a hint of where to look for. On this page, you will find more info about this endpoint.

Example of the search intent

I would like to search for “Elon Musk” in business-related news sources. But I do not know any business-oriented source.

Make a call with /v2/sources endpoint

Check the Quickstart guide to know how to make a call.

https://api.newscatcherapi.com
/v2/sources?topic=business&lang=en&countries=US

Results from the call

{
    "message": "Maximum sources displayed according to your plan is set to 100",
    "sources": [
        "forbes.com",
        "yahoo.com",
        "apnews.com",
        "businessinsider.com",
        "cnbc.com",
         ...
    ],
    "user_input": {
        "lang": [
            "en"
        ],
        "countries": [
            "US"
        ],
        "topic": "business"
    }
}

Parameters to use

Get the first five sources a put them into the sources parameter

q="Elon Musk"
sources=forbes.com,yahoo.com,apnews.com,businessinsider.com,cnbc.com

In /v2/sources endpoint the list of news sources is sorted by the number of articles for the last 24 hours.

Advice #4: Use to_rank Or from_rank To Vary From Global News Sources To More Local Once

Our rank parameter is based on the Majestic Million Rank system. The smaller the rank, the more popular the news domain. The “popularity” is measured by the number of backlinks and referrers on the web. Some examples of ranks:

  • nytimes.com => 40
  • reuters.com => 86
  • china.com.cn => 962
  • stthomassource.com => 120496

Example of the search intent

I am looking for articles about Microsoft Patents. I trust only global media.

Parameters to use

q=Microsoft AND patent
to_rank=10000

Example of the search intent

I am looking for articles about Microsoft Patents. I am not interested in the most popular news sources like Forbes or Washington Post. I am curious to know what other small media posted.

Parameters to use

q=Microsoft AND patent
ranked_only=False
from_rank=100000

By default, ranked_only parameter is set to True. It means that if a news domain is not in the Majestic List, we will attribute the value 999,999 to this domain. If you want to get articles from these unranked domains, you should set ranked_only=False

Contact us to get help

A well-configured query is the best way to get the most relevant results.

If you need any private suggestions or advice, do not hesitate to contact us at team@newscatcherapi.com.