</newscatcher>
Search…
Search News
Main endpoint that allows you to find news article by keyword, date, language, country, etc.
get
https://api.newscatcherapi.com
/v2/search?q=Tesla&page_size=2
Get News

Return Body Fields

Object
Sub Object
Description
status
​
Returns ok if everything went well.
Returns error in case of an error (plus 2 additional fields in case of error β€” error_code and message)
total_hits
​
How many news articles match your search criterion. Maximum is 10,000
page
​
The page where you are at
total_pages
​
How many pages you can access given your page_size parameter
page_size
​
How many news articles are in the returned JSON object
articles:
​
News articles found. list
​
title
The title of the article
​
author
The author of the article
​
published_date
Published date & time
​
published_date_precision
Accuracy of the published_date field.
​
There are 3 types of date precision we define:
​
full β€” day and time of an article is correctly identified with the appropriate timezone
​
timezone unknown β€” day and time of an article is correctly identified without timezone
​
date β€” only the day is identified without an exact time
​
link
Full URL where the article was originally published
​
clean_url
The URL of the article's source
​
excerpt
Short summary of the article provided by the publisher
​
summary
The full content of the article
​
rights
Copyright
​
rank
The page rank of the source website (which is given in the clean_url)
​
topic
The main topic of the news publisher. Important: This parameter is not deducted on a per-article level: it is deducted on the per-publisher level
​
country
The country of the publisher
​
language
The language of the article
​
authors
A list of article authors
​
media
A link to a thumbnail image of the article
​
is_opinion
True if the article is an "Opinion" article
​
twitter_account
The Twitter account of the publisher
​
_score
How well the article is matching your search criteria. _score is different for each search you make. The best matching article has the highest score
​
_id
Newscatcher API's unique identifier for each news article
user_input
​
An object that returns how our backend saw your request. It shows you which parameters have been used to perform a search. Useful for debugging, especially to check if there is any problem with URL encoding

Advanced Query [q] Parameter

In case you're not the type of developer who will read through the entire section, here're 3 most important rules that you have to follow:
  1. 1.
    Be aware that, by default, tokens (keywords you're searching for) passed into the q parameter are split with AND operator: meaning each token has to be present in the text at least once. For example, q=Apple Microsoft will be read as q=Apple AND Microsoft
  2. 2.
    Always use double-quotes (") when you search for companies, person name, etc. For example, if you want to find articles where Tim Cook is mentioned, you should pass q="Tim Cook" (not q=Tim Cook)
  3. 3.
    Make sure that what you pass into the q parameter is URL-encoded. While making your first calls, check the user_input list in the JSON that we return to you: make sure our backend saw your keywords as you intended.
​

Exact Match ("double quotes")

Use double quotes (") for the exact match.
When you want to search for articles that mention Tim Cook you should do the following query:
1
q="Tim Cook"
Copied!
If you write q=Tim Cook then, it will be treated as q=Tim AND Cook. In that case, every article that mentions tim and cook will match.
Moreover, if you specify lang=en that will also match the articles with cooking, cooked, and other stems of the word cook
​

Boolean: AND

AND operator makes tokens from both sides to be present in the text. AND is the default operator. When your q input is more than 1 word, AND operator is added between each word behind the scenes. Therefore, q=Apple Microsoft Tesla is the same as q=Apple AND Microsoft AND Tesla For example, if we want both Microsoft and Tesla to be present in the returned news articles, the q parameter should look as follows:
1
q=Microsoft AND Tesla
Copied!
or
1
q=Microsoft && Tesla
Copied!
​

Boolean: OR

OR can also be written as ||
OR operator means that either the left or the right sides of OR have to be satisfied.
You should use Grouping when you want to logically group a set of tokens. For example:
1
q=(Apple AND Cook) OR (Microsoft AND Gates)
Copied!
or
1
q=(Apple && Cook) || (Microsoft && Gates)
Copied!
​

Boolean: NOT

NOT can also be written as !
Use NOT operator when you want the token from its right to not be present. For example, if we want to search for articles about Microsoft and not about Tesla, the q parameter should look as follows:
1
q=Microsoft NOT Tesla
Copied!
or
1
q=Microsoft !Tesla
Copied!
​

MUST (MUST NOT)

Prepend a token with a + (plus sign) if it MUST appear in the searched text
Make sure that your API call is URL encoded. Check the user_input object in the Response Body to see how our back-end saw your request.
+ will be escaped by default in many situations.
Make sure that your API call is URL encoded. Check the user_input object in the Response Body to see how our back-end saw your request.
+ (plus sign) will be escaped by default in many situations. Therefore, we recommend using it's URL-encoded version: %2B
Prepend a token with a - (minus sign) if it MUST NOT appear in the searched text
For example, if we want to search for news articles that contain Elon Musk but not Grimes, we have to write:
1
q=Elon Musk -Grimes
Copied!
"But wait, the query above will also match the documents where only Elon or Musk are present" Shouldn't we write +Elon +Musk -Grimes ?
If we write +Elon +Musk -Grimes that will mean that Elon and Musk should be present in the text, however, not in that particular. The "correct" query should look like this:
1
q="Elon Musk" -Grimes
Copied!
In this case, we will search for an exact match of "Elon Musk" , plus, Grimes must not be present.
In general, you should always put person and company names into quotes
​

Wildcards (* and ?)

Use * to match any string in any quantity
Use ? to match any string exactly once
For example, we want to search for articles that mention Microsort and any C-level officers:
1
q=Microsoft +C?O
Copied!
​
​

language format

You should use ISO 639-1 β€” 2 letter code.
For example, English - en
Important: We distinguish Chinese (China) and Chinese (Taiwan) languages, cn and tw accordingly. That is the only difference between us and ISO 639-1 code.
The list of languages we support:
1
af,ar,bg,bn,ca,cs,cy,cn,da,de,el,en,es,et,fa,fi,fr,gu,he,hi,hr,hu,id,it,ja,kn,ko,lt,lv,mk,ml,mr,ne,nl,no,pa,pl,pt,ro,ru,sk,sl,so,sq,sv,sw,ta,te,th,tl,tr,tw,uk,ur,vi
Copied!

countries format

You should use ISO 3166-1 alpha-2 code.
For example, France - FR
You can find the entire list via the following link: https://www.iso.org/obp/ui/#search​
​

Debugging

While developing, look at user_input object that returns all of your parameters. If you made a mistake, or some characters were not correctly parsed because of the URL-encoding, you will see that.
Last modified 27d ago