v3 Search News

Main endpoint that allows you to find news article by keyword, date, language, country, etc.

Get News

GET https://v3-api.newscatcherapi.com/api/search?q=Apple&from_=1 day ago&countries=CA&page_size=1

Query Parameters

Name Type Description

Name	Type	Description
q*	string	Keyword/keywords you're searching for. This is the most important part of your query. You can set this to `''` if you don't want to look for specific keywords. Please, refer to the Advanced Querying* page for more examples and explanations.
lang	array	Specifies the languages of the search. For example, `en`. The only accepted format is ISO 639-1 — 2 letter code. Refer to the language format section for more details.
not_lang	array	Inverse to the `lang` parameter
published_date_precision	string	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
search_in	string	By default, we search what you specified in the `q` parameter in both `title` and `content` of the article. However, you can choose between: `-title` `-content` `-summary` (if enabled for your plan) `-title,summary` `-content,summary`
countries	array	Countries where the news publisher is located. Important: This parameter is not responsible for the countries mentioned in the news article. One or multiple countries can be used in the search. The only acceptable format is ISO 3166-1 alpha-2 For example, `US,CA,MX` or just `US`
not_countries	array	The inverse of the `countries` parameter.
sources	array	One or more news sources to narrow down your search. The format should be a domain url from your URL. Subdomains, like `finance.yahoo.com` are also accepted. Comma-separated string or a list/array. For example, `nytimes.com,theguardian.com,finance.yahoo.com`
not_sources	array	One or more sources to be excluded from the search. Comma-separated string or a list/array. For example, `cnn.com,wsj.com`
ranked_only	boolean	Default: `True` Limit the search only for the sources which are in the top 1 million online websites. Unranked sources are assigned a rank that equals `999999`
from_rank	integer	`[0:999999]` The lowest boundary of the rank of a news website to filter by. Important: lower rank means that a source is more popular
to_rank	integer	`[0:999999]` The upper boundary of the rank of a news website to filter by.
sort_by	string	`relevancy` (default value) — the most relevant results first `date` — the most recently published results first `rank` — the results from the highest-ranked sources first
page_size	integer	`[1:1000]` How many articles to return per page.
page	integer	The number of the page. Use it to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 1000 articles.
to_	string	Until which point in time to search for. The default timezone is UTC. Availabe formats : `YYYY/mm/dd` `YYYY/mm/dd HH:MM:SS` English phrases like`1 day ago`
from_	string	From which point in time to start the search. Defaults to the past week. Availabe formats : `YYYY/mm/dd` `YYYY/mm/dd HH:MM:SS` English phrases like `1 day ago`
by_parse_date	boolean	When set to `True`, transforms your from_ and to_ parameters to filter by parse_date instead of published_date Be aware that a new variable parse_date will be added to the output list with each article.
is_headline	boolean	When set to `True`, only articles that were posted on the home page of a given news domain will be shown.
parent_url	array	One or more categorical URL to filter your search. It should be the normal form of the URL, For example, `https://www.washingtonpost.com/politics,https://www.washingtonpost.com/technology,https://www.washingtonpost.com/business`
all_links	array	Search for desired URL mentioned in the article. Please, refer to the All Links And Domains Format pagefor more examples and explanations.
all_domain_links	array	Search for desired domain URL mentioned in the article. Please, refer to the All Links And Domains Format page for more examples and explanations.
word_count_min	integer	Set a minimum number of words that an article must contain. To be used for avoiding avoid articles with small content.
word_count_max	integer	Set a maximum number of words that an article must contain. To be used for avoiding avoid articles with big content.
include_nlp_data	boolean	When set to `True`, adds to each article a NLP layer. Not available for all plans. Please contact us to enable it.
theme	string	[Available only if NLP is enabled for your API key] A general topic of an article. Topic labelling is based on the actual content of an article. Accepted values: `Business`, `Economics`, `Entertainment`, `Finance`, `Health`, `Politics`, `Science`, `Sports`, `Tech`, `Crime`, `Lifestyle`, `Automotive` , `Travel`, `Weather`, `General` Comma-separated string or a list/array. Multiple themes can be selected. For example: `Business` `Business`, `Finance`
ORG_entity_name	string	[Available only if NLP is enabled for your API key] ORG stands for Organisation. We identify company names mentioned in articles and enable you to search for them. More information on Search By Entity
has_nlp	boolean	[Available only if NLP is enabled for your API key] When set to `True`, filter data only to those articles that have an NLP layer.
title_sentiment_min	float	[Available only if NLP is enabled for your API key] Narrow down your search to only positive or negative news based on the article's title sentiment. The value can vary from `-1` to `1`.
title_sentiment_max	float	[Available only if NLP is enabled for your API key] Narrow down your search to only positive or negative news based on the article's title sentiment. The value can vary from `-1` to `1`.
content_sentiment_min	float	[Available only if NLP is enabled for your API key] Narrow down your search to only positive or negative news based on the article's content sentiment. The value can vary from `-1` to `1`.
content_sentiment_max	float	[Available only if NLP is enabled for your API key] Narrow your search to only positive or negative news based on the article's content sentiment. The value can vary from `-1` to `1`.
is_paid_content	boolean	[Still in development phase] When set to `False`, only articles that publish full public available content will be shown. Some news publishers partially block content of their articles, so we get only several sentences from them. This filter will help you get full content.
clustering_enabled	boolean	[Available only if NLP is enabled for your API key] When set to True, enables clustering on articles. Instead of showing a list of articles, you will be given a list of clustering to put together similar articles. Please refer to the Clustering News Articles page for more examples and explanations.
clustering_threshold	float	[Available only if NLP is enabled for your API key] Set a threshold for an article to be similar. Default value: `0.6` The value can vary from `0` to `1`.
clustering_variable	string	[Available only if NLP is enabled for your API key] Select the data on which you want the similarity to be calculated on. Accepted values: `content`, `title`, `summary` Default value: `content`
PER_entity_name	string	[Available only if NLP is enabled for your API key] PER stands for Person. We identify people's names mentioned in articles and enable you to search for them. More information on Search By Entity
LOC_entity_name	string	[Available only if NLP is enabled for your API key] LOC stands for Location. We identify geographical locations mentioned in articles and enable you to search for them. More information on Search By Entity
MISC_entity_name	string	[Available only if NLP is enabled for your API key] MISC stands for Miscellaneous. We identify products and other names mentioned in articles and enable you to search for them. More information on Search By Entity
predefined_sources	string	Use our TOP predifined sources per country. Later we are going to improve it and add more functionality, like top categories etc. The format should be strictly like this: - starting with word `top` - put the number of desired sources top source - 2 letter country code ISO 3166-1 alpha-2 For example: `top 100 US` `top 33 AT` `top 5 GB` It is also possible to put multiple countries with custom number of top sources, should be comma separated. For example: `top 100 US, GB` `top 33 AT, 55 IT`
iptc_tags	string	[Available only if tags are enabled for your API key] We label articles with IPTC tags based on the content and enable you to filter articles based on the tags. Only IPTC tag IDs can be used in this parameter. For example, `20000183,20000199,20000188` or just `20000188`
not_iptc_tags	string	[Available only if tags are enabled for your API key] Inverse of the `iptc_tags` parameter; it enables you to filter articles based on their IPTC tags.
not_author_name	array	List of author names that you want to exclude from your search. Usually, you might want to exclude articles where one of the authors is Associated Press, or PRNewswire. For example: `PRNewswire, AOL Staff`
not_theme	string	[Available only if NLP is enabled for your API key] Inverse of the `theme` parameter; it enables you to filter articles based on their general topic.
source_name	array	NewsCatcher team does not suggest using source_name in Production. The best parameter to get data from a specific News Domain is sources. One or more news source names to narrow down your search. Comma-separated string or a list/array. For example: `CryptoPotato,thethings`

string

Keyword/keywords you're searching for. This is the most important part of your query. You can set this to '*' if you don't want to look for specific keywords. Please, refer to the Advanced Querying page for more examples and explanations.

lang

array

Specifies the languages of the search. For example, en. The only accepted format is ISO 639-1 — 2 letter code. Refer to the language format section for more details.

not_lang

array

Inverse to the lang parameter

published_date_precision

string

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

search_in

string

By default, we search what you specified in the q parameter in both title and content of the article. However, you can choose between:

-title

-content

-summary (if enabled for your plan)

-title,summary

-content,summary

countries

array

Countries where the news publisher is located. Important: This parameter is not responsible for the countries mentioned in the news article. One or multiple countries can be used in the search. The only acceptable format is ISO 3166-1 alpha-2 For example, US,CA,MX or just US

not_countries

array

The inverse of the countries parameter.

sources

array

One or more news sources to narrow down your search.

The format should be a domain url from your URL. Subdomains, like finance.yahoo.com are also accepted. Comma-separated string or a list/array. For example, nytimes.com,theguardian.com,finance.yahoo.com

not_sources

array

One or more sources to be excluded from the search. Comma-separated string or a list/array.

For example, cnn.com,wsj.com

ranked_only

boolean

Default: True Limit the search only for the sources which are in the top 1 million online websites. Unranked sources are assigned a rank that equals 999999

from_rank

integer

[0:999999] The lowest boundary of the rank of a news website to filter by. Important: lower rank means that a source is more popular

to_rank

integer

[0:999999] The upper boundary of the rank of a news website to filter by.

sort_by

string

relevancy (default value) — the most relevant results first date — the most recently published results first rank — the results from the highest-ranked sources first

page_size

integer

[1:1000] How many articles to return per page.

page

integer

The number of the page. Use it to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 1000 articles.

to_

string

Until which point in time to search for. The default timezone is UTC. Availabe formats : YYYY/mm/dd YYYY/mm/dd HH:MM:SS

English phrases like1 day ago

from_

string

From which point in time to start the search. Defaults to the past week. Availabe formats : YYYY/mm/dd YYYY/mm/dd HH:MM:SS English phrases like 1 day ago

by_parse_date

boolean

When set to True, transforms your from_ and to_ parameters to filter by parse_date instead of published_date

Be aware that a new variable parse_date will be added to the output list with each article.

is_headline

boolean

When set to True, only articles that were posted on the home page of a given news domain will be shown.

parent_url

array

One or more categorical URL to filter your search. It should be the normal form of the URL, For example, https://www.washingtonpost.com/politics,https://www.washingtonpost.com/technology,https://www.washingtonpost.com/business

all_links

array

Search for desired URL mentioned in the article.

Please, refer to the All Links And Domains Format pagefor more examples and explanations.

all_domain_links

array

Search for desired domain URL mentioned in the article.

Please, refer to the All Links And Domains Format page for more examples and explanations.

word_count_min

integer

Set a minimum number of words that an article must contain.

To be used for avoiding avoid articles with small content.

word_count_max

integer

Set a maximum number of words that an article must contain.

To be used for avoiding avoid articles with big content.

include_nlp_data

boolean

When set to True, adds to each article a NLP layer.

Not available for all plans. Please contact us to enable it.

theme

string

[Available only if NLP is enabled for your API key]

A general topic of an article. Topic labelling is based on the actual content of an article.

Accepted values:

Business, Economics, Entertainment, Finance, Health, Politics, Science, Sports, Tech, Crime, Lifestyle, Automotive , Travel, Weather, General

Comma-separated string or a list/array.

Multiple themes can be selected.

For example:

Business

Business, Finance

ORG_entity_name

string

[Available only if NLP is enabled for your API key]

ORG stands for Organisation.

We identify company names mentioned in articles and enable you to search for them.

More information on Search By Entity

has_nlp

boolean

[Available only if NLP is enabled for your API key]

When set to True, filter data only to those articles that have an NLP layer.

title_sentiment_min

float

[Available only if NLP is enabled for your API key]

Narrow down your search to only positive or negative news based on the article's title sentiment.

The value can vary from -1 to 1.

title_sentiment_max

float

[Available only if NLP is enabled for your API key]

Narrow down your search to only positive or negative news based on the article's title sentiment.

The value can vary from -1 to 1.

content_sentiment_min

float

[Available only if NLP is enabled for your API key]

Narrow down your search to only positive or negative news based on the article's content sentiment.

The value can vary from -1 to 1.

content_sentiment_max

float

[Available only if NLP is enabled for your API key]

Narrow your search to only positive or negative news based on the article's content sentiment.

The value can vary from -1 to 1.

is_paid_content

boolean

[Still in development phase]

When set to False, only articles that publish full public available content will be shown.

Some news publishers partially block content of their articles, so we get only several sentences from them. This filter will help you get full content.

clustering_enabled

boolean

[Available only if NLP is enabled for your API key]

When set to True, enables clustering on articles. Instead of showing a list of articles, you will be given a list of clustering to put together similar articles.

Please refer to the Clustering News Articles page for more examples and explanations.

clustering_threshold

float

[Available only if NLP is enabled for your API key]

Set a threshold for an article to be similar.

Default value: 0.6

The value can vary from 0 to 1.

clustering_variable

string

[Available only if NLP is enabled for your API key]

Select the data on which you want the similarity to be calculated on.

Accepted values:

content, title, summary

Default value:

content

PER_entity_name

string

[Available only if NLP is enabled for your API key]

PER stands for Person.

We identify people's names mentioned in articles and enable you to search for them.

More information on Search By Entity

LOC_entity_name

string

[Available only if NLP is enabled for your API key]

LOC stands for Location.

We identify geographical locations mentioned in articles and enable you to search for them.

More information on Search By Entity

MISC_entity_name

string

[Available only if NLP is enabled for your API key]

MISC stands for Miscellaneous.

We identify products and other names mentioned in articles and enable you to search for them.

More information on Search By Entity

predefined_sources

string

Use our TOP predifined sources per country.

Later we are going to improve it and add more functionality, like top categories etc.

The format should be strictly like this:

- starting with word top

- put the number of desired sources top source

- 2 letter country code ISO 3166-1 alpha-2

For example:

top 100 US

top 33 AT

top 5 GB

It is also possible to put multiple countries with custom number of top sources, should be comma separated.

For example:

top 100 US, GB

top 33 AT, 55 IT

iptc_tags

string

[Available only if tags are enabled for your API key]

We label articles with IPTC tags based on the content and enable you to filter articles based on the tags.

Only IPTC tag IDs can be used in this parameter.

For example, 20000183,20000199,20000188 or just 20000188

not_iptc_tags

string

[Available only if tags are enabled for your API key]

Inverse of the iptc_tags parameter; it enables you to filter articles based on their IPTC tags.

not_author_name

array

List of author names that you want to exclude from your search.

Usually, you might want to exclude articles where one of the authors is Associated Press, or PRNewswire.

For example:

PRNewswire, AOL Staff

not_theme

string

[Available only if NLP is enabled for your API key]

Inverse of the theme parameter; it enables you to filter articles based on their general topic.

source_name

array

NewsCatcher team does not suggest using source_name in Production. The best parameter to get data from a specific News Domain is sources.

One or more news source names to narrow down your search.

Comma-separated string or a list/array.

For example:

CryptoPotato,thethings

Headers

Name	Type	Description
x-api-token*	string	Your unique authentication token

Name

Type

Description

x-api-token*

string

Your unique authentication token

{
    "status": "ok",
    "total_hits": 6969,
    "page": 1,
    "total_pages": 70,
    "page_size": 100,
    "articles": [
       {
      "title": "Is Elon Musk Changing His Name? New Post On 'X' Sparks Rumour",
      "author": "Anjali Thakur",
      "authors": [
        "Anjali Thakur"
      ],
      "published_date": "2023-09-26 05:05:11",
      "published_date_precision": "full",
      "updated_date": null,
      "updated_date_precision": null,
      "link": "https://www.ndtv.com/world-news/is-elon-musk-changing-his-name-new-post-on-x-sparks-rumour-4424012#pfrom=home-ndtv_featured",
      "domain_url": "ndtv.com",
      "full_domain_url": "ndtv.com",
      "name_source": "NDTV",
      "is_headline": false,
      "paid_content": false,
      "parent_url": "https://www.ndtv.com",
      "country": "IN",
      "rights": "ndtv.com",
      "rank": 920,
      "media": "https://c.ndtvimg.com/2023-09/4dau661g_elon-musk-reuters_625x300_13_September_23.jpg",
      "language": "en",
      "description": "His post has since received more than 3 million views with a flurry of comments on X.",
      "content": "Billionaire Elon Musk, the founder and owner of Tesla, X.com, SpaceX, Neuralink and The Boring Company's recent post on 'X' is going viral. He wrote on X, \"Nobody-that's my name\". His post has since received more than 3 million views with a flurry of comments on X. See the post here: Nobody—that's my name — Elon Musk (@elonmusk) September 26, 2023 While some users asked Mr Musk if he was \"okay\", others started a meme fest. A user wrote, \"You good bro?\" Another user commented, \"Hi Nobody.\" \"When Elon makes a post, millions of phones ding around the world and people rush to respond and get his attention,\" the third user wrote. \"Tomorrow is another day,\" the fourth user wrote. \"Everybody - that's my name,\" the fifth user commented. Meanwhile, earlier, billionaire Elon Musk stated that he is buying the iPhone 15 and many of us would agree with his reason. Mr Musk said, \"The beauty of iPhone pictures & video is incredible.\" Elon Musk is ranked as the world's richest person by Forbes and Bloomberg Billionaires Index, with a total net worth of $236 billion. Unlike other billionaires and usual investment stories, Mr Musk undertook some risky investment options which ultimately made him the richest private citizen on the planet since 2021. Mr Musk's ownership share in electric vehicle manufacturer Tesla and his holdings in SpaceX and the Boring Company are responsible for his startling increase in fortune. However, Tesla has been the main source of his wealth, with the company's stock rising by more than 1,100 per cent in the last five years as investors rewarded it for its rise in vehicle sales.",
      "word_count": 275,
      "is_opinion": false,
      "twitter_account": "@ndtv",
      "all_links": [
        "https://www.jiosaavn.com/featured/new-music-this-week/Ns2UZo9qDvI",
        "https://www.ndtvgames.com/#pfrom=ndtv-globalnav",
        "https://www.gadgets360.com/mobiles/phone-finder",
        "https://mpcg.ndtv.in",
        "https://twitter.com/elonmusk/status/1706510175144649057?ref_src=twsrc%5Etfw",
        "https://ndtv.in/videos/live/channel/ndtvindia",
        "https://hotdeals360.com/beauty/best-glycolic-acid-toners-for-blemish-free-glowing-skin-4394322",
        "https://hotdeals360.com/beauty/best-glitter-lip-glosses-that-are-trending-in-the-world-of-beauty-4398727",
        "https://rajasthan.ndtv.in",
        "https://www.whatsapp.com/channel/0029Va4lixw7z4kcvZI9JM12",
        "https://twitter.com/ndtv",
        "https://www.instagram.com/ndtv/",
        "https://www.facebook.com/ndtv",
        "https://www.gadgets360.com/#pfrom=ndtv-globalnav",
        "https://rajasthan.ndtv.in/livetv-ndtvrajasthan",
        "https://www.jiosaavn.com",
        "https://www.whosthat360.com/finance/anushka-rathod-avoid-this-common-mistake-when-investing-in-mutual-funds-4408067",
        "https://www.gadgets360.com/internet/news/flipkart-big-billion-days-sale-2023-instant-bank-discount-details-teased-offers-deals-4417000",
        "https://ndtv.in/#pfrom=ndtv-globalnav",
        "https://mpcg.ndtv.in/livetv-ndtvmpcg",
        "https://www.gadgets360.com/internet/features/amazon-great-indian-festival-sale-date-october-10-leak-deals-discounts-offers-4420830"
      ],
      "all_domain_links": [
        "instagram.com",
        "whatsapp.com",
        "twitter.com",
        "gadgets360.com",
        "hotdeals360.com",
        "whosthat360.com",
        "ndtvgames.com",
        "jiosaavn.com",
        "ndtv.in",
        "facebook.com"
      ],
      "nlp": {
        "theme": "Business",
        "summary": "Elon Musk is the founder and owner of Tesla, X.com, SpaceX, Neuralink and The Boring Company. He wrote on X, \"Nobody-that's my name\". His post has since received more than 3 million views. He is ranked as the world's richest person with a net worth of $236 billion.",
        "sentiment": {
          "title": 0,
          "content": 0
        },
        "ner_PER": [
          {
            "entity_name": "Elon Musk",
            "count": 4
          },
          {
            "entity_name": "Musk",
            "count": 4
          },
          {
            "entity_name": "Elon",
            "count": 1
          }
        ],
        "ner_ORG": [
          {
            "entity_name": "Tesla",
            "count": 3
          },
          {
            "entity_name": "SpaceX",
            "count": 2
          },
          {
            "entity_name": "X.com",
            "count": 1
          },
          {
            "entity_name": "Neuralink",
            "count": 1
          },
          {
            "entity_name": "The Boring Company",
            "count": 1
          },
          {
            "entity_name": "Forbes",
            "count": 1
          },
          {
            "entity_name": "Boring Company",
            "count": 1
          }
        ],
        "ner_MISC": [
          {
            "entity_name": "iPhone 15",
            "count": 1
          },
          {
            "entity_name": "iPhone",
            "count": 1
          },
          {
            "entity_name": "Bloomberg Billionaires Index",
            "count": 1
          }
        ],
        "ner_LOC": []
      },
      "id": "c63576c21d9da5d27e13424f023d4ef8",
      "score": 23.87998
    },
    ...
    ],
    "user_input": {...}
}

{
    "status": "error",
    "error_code": "UnsupportedParameter",
    "message": "Found unsupported parameter(s)['sort_by', 'q']. Here are the parameters available for this endpoint => ['countries', 'topic', 'lang']"
}

{
    "status": "error",
    "error_code": "UnsupportedParameter",
    "message": "Request takes more than 30 seconds. Your search is too broad.Try to use more parameters to narrow down the request."
}

{
  "status": "error",
  "error_code": "ConcurrencyViolation",
  "message": "Max concurrency allowed 1 per 1 second"
}

{
    "message": "Forbidden",s
    "code": 403
}

{
    "message": "Param langs is not allowed for plan nlp"
}

Get News

POST https://v3-api.newscatcherapi.com/api/search?

Headers

Name	Type	Description
x-api-token*	string	Your unique authentication token

Name

Type

Description

x-api-token*

string

Your unique authentication token

Request Body

Name Type Description

Name	Type	Description
q*	string	Keyword/keywords you're searching for. This is the most important part of your query. Please, refer to the Advanced Query Parameter section for more examples and explanations.
lang	array	Specifies the languages of the search. For example, `en`. The only accepted format is ISO 639-1 — 2 letter code. Refer to the language format section for more details.
not_lang	array	Inverse to the `lang` parameter
published_date_precision	string	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
search_in	string	By default, we search what you specified in the `q` parameter in both `title` and `content` of the article. However, you can choose between: `-title` `-content` `-summary` (if enabled for your plan) `-title,summary` `-content,summary`
countries	array	Countries where the news publisher is located. Important: This parameter is not responsible for the countries mentioned in the news article. One or multiple countries can be used in the search. The only acceptable format is ISO 3166-1 alpha-2 For example, `US,CA,MX` or just `US`
not_countries	array	The inverse of the `countries` parameter.
sources	array	One or more news sources to narrow down your search. The format should be a domain url from your URL. Subdomains, like `finance.yahoo.com` are also accepted. Comma-separated string or a list/array. For example, `nytimes.com,theguardian.com,finance.yahoo.com`
not_sources	array	One or more sources to be excluded from the search. Comma-separated string or a list/array. For example, `cnn.com,wsj.com`
ranked_only	boolean	Default: `True` Limit the search only for the sources which are in the top 1 million online websites. Unranked sources are assigned a rank that equals `999999`
from_rank	integer	`[0:999999]` The lowest boundary of the rank of a news website to filter by. Important: lower rank means that a source is more popular
to_rank	integer	`[0:999999]` The upper boundary of the rank of a news website to filter by.
sort_by	string	`relevancy` (default value) — the most relevant results first `date` — the most recently published results first `rank` — the results from the highest-ranked sources first
page_size	integer	`[1:1000]` How many articles to return per page.
page	integer	The number of the page. Use it to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 1000 articles.
to_	string	Until which point in time to search for. The default timezone is UTC. Availabe formats : `YYYY/mm/dd` `YYYY/mm/dd HH:MM:SS` English phrases like`1 day ago`
from_	string	From which point in time to start the search. Defaults to the past week. Availabe formats : `YYYY/mm/dd` `YYYY/mm/dd HH:MM:SS` English phrases like `1 day ago`
by_parse_date	boolean	When set to `True`, transforms your from_ and to_ parameters to filter by parse_date instead of published_date Be aware that a new variable parse_date will be added to the output list with each article.
is_headline	boolean	When set to `True`, only articles that were posted on the home page of a given news domain will be shown.
parent_url	array	One or more categorical URL to filter your search. It should be the normal form of the URL, For example, `https://www.washingtonpost.com/politics,https://www.washingtonpost.com/technology,https://www.washingtonpost.com/business`
all_links	array	Search for desired URL mentioned in the article. Please, refer to the All Links And Domains Format section for more examples and explanations.
all_domain_links	array	Search for desired domain URL mentioned in the article. Please, refer to the All Links And Domains Format section for more examples and explanations.
word_count_min	integer	Set a minimum number of words that an article must contain. To be used for avoiding avoid articles with small content.
word_count_max	integer	Set a maximum number of words that an article must contain. To be used for avoiding avoid articles with big content.
include_nlp_data	boolean	When set to `True`, adds to each article a NLP layer. Not available for all plans. Please contact us to enable it.
theme	string	[Available only if NLP is enabled for your API key] A general topic of an article. Topic labelling is based on the actual content of an article. Accepted values: `Business`, `Economics`, `Entertainment`, `Finance`, `Health`, `Politics`, `Science`, `Sports`, `Tech`, `Crime`, `Lifestyle`, `Automotive` , `Travel`, `Weather`, `General` Comma-separated string or a list/array. Multiple themes can be selected. For example: `Business` `Business`, `Finance`
ORG_entity_name	string	[Available only if NLP is enabled for your API key] ORG stands for Organisation. We identify company names mentioned in articles and enable you to search for them. More information on Search By Entity
has_nlp	boolean	[Available only if NLP is enabled for your API key] When set to `True`, filter data only to those articles that have an NLP layer.
title_sentiment_min	float	[Available only if NLP enabled for your plan] Narrow down your search to only possitive or negative news based on article's title sentiment. The value can vary from `-1` to `1`.
title_sentiment_max	float	[Available only if NLP is enabled for your API key] Narrow down your search to only positive or negative news based on the article's title sentiment. The value can vary from `-1` to `1`.
content_sentiment_min	float	[Available only if NLP is enabled for your API key] Narrow down your search to only positive or negative news based on the article's content sentiment. The value can vary from `-1` to `1`.
content_sentiment_max	float	[Available only if NLP is enabled for your API key] Narrow down your search to only positive or negative news based on the article's content sentiment. The value can vary from `-1` to `1`.
is_paid_content	String	[Still in development phase] When set to `False`, only articles that publish full public available content will be shown. Some news publishers partially block content of their articles, so we get only several sentences from them. This filter will help you get full content.
clustering_enabled	boolean	[Available only if NLP is enabled for your API key] When set to True, it enables clustering on articles. Instead of showing a list of articles, you will be given a list of clustering to put together similar articles. Please refer to the Deduplicate Data With Clustering section for more examples and explanations.
clustering_threshold	float	[Available only if NLP is enabled for your API key] Set a threshold for an article to be similar. Default value: `0.6` The value can vary from `0` to `1`.
clustering_variable	string	[Available only if NLP is enabled for your API key] Select the data on which you want the similarity to be calculated. Accepted values: `content`, `title`, `summary` Default value: `content`
PER_entity_name	string	[Available only if NLP is enabled for your API key] PER stands for Person. We identify people's names mentioned in articles and enable you to search for them. More information on Search By Entity
LOC_entity_name	string	[Available only if NLP is enabled for your API key] LOC stands for Location. We identify geographical locations mentioned in articles and enable you to search for them. More information on Search By Entity
MISC_entity_name	string	[Available only if NLP is enabled for your API key] MISC stands for Miscellaneous. We identify products and other names mentioned in articles and enable you to search for them. More information on Search By Entity
predefined_sources	string	Use our TOP predifined sources per country. Later we are going to improve it and add more functionality, like top categories etc. The format should be strictly like this: - starting with word `top` - put the number of desired sources top source - 2 letter country code ISO 3166-1 alpha-2 For example: `top 100 US` `top 33 AT` `top 5 GB` It is also possible to put multiple countries with custom number of top sources, should be comma separated. For example: `top 100 US, GB` `top 33 AT, 55 IT`
not_iptc_tags	string	[Available only if tags are enabled for your API key] Inverse of the `iptc_tags` parameter; it enables you to filter articles based on their IPTC tags.
iptc_tags	string	[Available only if tags are enabled for your API key] We label articles with IPTC tags based on the content and enable you to filter articles based on the tags. Only IPTC tag IDs can be used in this parameter. For example, `20000183,20000199,20000188` or just `20000188`
not_author_name	array	List of author names that you want to exclude from your search. Usually, you might want to exclude articles where one of the authors is Associated Press, or PRNewswire. For example: `PRNewswire, AOL Staff`
not_theme	string	[Available only if NLP is enabled for your API key] Inverse of the `theme` parameter; it enables you to filter articles based on their general topic.
source_name	array	NewsCatcher team does not suggest using source_name in Production. The best parameter to get data from a specific News Domain is sources. One or more news source names to narrow down your search. Comma-separated string or a list/array. For example: `CryptoPotato,thethings`

string

Keyword/keywords you're searching for. This is the most important part of your query. Please, refer to the Advanced Query Parameter section for more examples and explanations.

lang

array

Specifies the languages of the search. For example, en. The only accepted format is ISO 639-1 — 2 letter code. Refer to the language format section for more details.

not_lang

array

Inverse to the lang parameter

published_date_precision

string

search_in

string

By default, we search what you specified in the q parameter in both title and content of the article. However, you can choose between:

-title

-content

-summary (if enabled for your plan)

-title,summary

-content,summary

countries

array

not_countries

array

The inverse of the countries parameter.

sources

array

One or more news sources to narrow down your search.

not_sources

array

One or more sources to be excluded from the search. Comma-separated string or a list/array.

For example, cnn.com,wsj.com

ranked_only

boolean

Default: True Limit the search only for the sources which are in the top 1 million online websites. Unranked sources are assigned a rank that equals 999999

from_rank

integer

[0:999999] The lowest boundary of the rank of a news website to filter by. Important: lower rank means that a source is more popular

to_rank

integer

[0:999999] The upper boundary of the rank of a news website to filter by.

sort_by

string

relevancy (default value) — the most relevant results first date — the most recently published results first rank — the results from the highest-ranked sources first

page_size

integer

[1:1000] How many articles to return per page.

page

integer

The number of the page. Use it to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 1000 articles.

to_

string

Until which point in time to search for. The default timezone is UTC. Availabe formats : YYYY/mm/dd YYYY/mm/dd HH:MM:SS

English phrases like1 day ago

from_

string

From which point in time to start the search. Defaults to the past week. Availabe formats : YYYY/mm/dd YYYY/mm/dd HH:MM:SS English phrases like 1 day ago

by_parse_date

boolean

When set to True, transforms your from_ and to_ parameters to filter by parse_date instead of published_date

Be aware that a new variable parse_date will be added to the output list with each article.

is_headline

boolean

When set to True, only articles that were posted on the home page of a given news domain will be shown.

parent_url

array

all_links

array

Search for desired URL mentioned in the article.

Please, refer to the All Links And Domains Format section for more examples and explanations.

all_domain_links

array

Search for desired domain URL mentioned in the article.

Please, refer to the All Links And Domains Format section for more examples and explanations.

word_count_min

integer

Set a minimum number of words that an article must contain.

To be used for avoiding avoid articles with small content.

word_count_max

integer

Set a maximum number of words that an article must contain.

To be used for avoiding avoid articles with big content.

include_nlp_data

boolean

When set to True, adds to each article a NLP layer.

Not available for all plans. Please contact us to enable it.

theme

string

[Available only if NLP is enabled for your API key]

A general topic of an article. Topic labelling is based on the actual content of an article.

Accepted values:

Business, Economics, Entertainment, Finance, Health, Politics, Science, Sports, Tech, Crime, Lifestyle, Automotive , Travel, Weather, General

Comma-separated string or a list/array.

Multiple themes can be selected.

For example:

Business

Business, Finance

ORG_entity_name

string

[Available only if NLP is enabled for your API key]

ORG stands for Organisation.

We identify company names mentioned in articles and enable you to search for them.

More information on Search By Entity

has_nlp

boolean

[Available only if NLP is enabled for your API key]

When set to True, filter data only to those articles that have an NLP layer.

title_sentiment_min

float

[Available only if NLP enabled for your plan]

Narrow down your search to only possitive or negative news based on article's title sentiment.

The value can vary from -1 to 1.

title_sentiment_max

float

[Available only if NLP is enabled for your API key]

Narrow down your search to only positive or negative news based on the article's title sentiment.

The value can vary from -1 to 1.

content_sentiment_min

float

[Available only if NLP is enabled for your API key]

Narrow down your search to only positive or negative news based on the article's content sentiment.

The value can vary from -1 to 1.

content_sentiment_max

float

[Available only if NLP is enabled for your API key]

Narrow down your search to only positive or negative news based on the article's content sentiment.

The value can vary from -1 to 1.

is_paid_content

String

[Still in development phase]

When set to False, only articles that publish full public available content will be shown.

Some news publishers partially block content of their articles, so we get only several sentences from them. This filter will help you get full content.

clustering_enabled

boolean

[Available only if NLP is enabled for your API key]

When set to True, it enables clustering on articles. Instead of showing a list of articles, you will be given a list of clustering to put together similar articles.

Please refer to the Deduplicate Data With Clustering section for more examples and explanations.

clustering_threshold

float

[Available only if NLP is enabled for your API key]

Set a threshold for an article to be similar.

Default value: 0.6

The value can vary from 0 to 1.

clustering_variable

string

[Available only if NLP is enabled for your API key]

Select the data on which you want the similarity to be calculated.

Accepted values:

content, title, summary

Default value:

content

PER_entity_name

string

[Available only if NLP is enabled for your API key]

PER stands for Person.

We identify people's names mentioned in articles and enable you to search for them.

More information on Search By Entity

LOC_entity_name

string

[Available only if NLP is enabled for your API key]

LOC stands for Location.

We identify geographical locations mentioned in articles and enable you to search for them.

More information on Search By Entity

MISC_entity_name

string

[Available only if NLP is enabled for your API key]

MISC stands for Miscellaneous.

We identify products and other names mentioned in articles and enable you to search for them.

More information on Search By Entity

predefined_sources

string

Use our TOP predifined sources per country.

Later we are going to improve it and add more functionality, like top categories etc.

The format should be strictly like this:

- starting with word top

- put the number of desired sources top source

- 2 letter country code ISO 3166-1 alpha-2

For example:

top 100 US

top 33 AT

top 5 GB

It is also possible to put multiple countries with custom number of top sources, should be comma separated.

For example:

top 100 US, GB

top 33 AT, 55 IT

not_iptc_tags

string

[Available only if tags are enabled for your API key]

Inverse of the iptc_tags parameter; it enables you to filter articles based on their IPTC tags.

iptc_tags

string

[Available only if tags are enabled for your API key]

We label articles with IPTC tags based on the content and enable you to filter articles based on the tags.

Only IPTC tag IDs can be used in this parameter.

For example, 20000183,20000199,20000188 or just 20000188

not_author_name

array

List of author names that you want to exclude from your search.

Usually, you might want to exclude articles where one of the authors is Associated Press, or PRNewswire.

For example:

PRNewswire, AOL Staff

not_theme

string

[Available only if NLP is enabled for your API key]

Inverse of the theme parameter; it enables you to filter articles based on their general topic.

source_name

array

NewsCatcher team does not suggest using source_name in Production. The best parameter to get data from a specific News Domain is sources.

One or more news source names to narrow down your search.

Comma-separated string or a list/array.

For example:

CryptoPotato,thethings

{
    "status": "ok",
    "total_hits": 6969,
    "page": 1,
    "total_pages": 70,
    "page_size": 100,
    "articles": [
       {
      "title": "Is Elon Musk Changing His Name? New Post On 'X' Sparks Rumour",
      "author": "Anjali Thakur",
      "authors": [
        "Anjali Thakur"
      ],
      "published_date": "2023-09-26 05:05:11",
      "published_date_precision": "full",
      "updated_date": null,
      "updated_date_precision": null,
      "link": "https://www.ndtv.com/world-news/is-elon-musk-changing-his-name-new-post-on-x-sparks-rumour-4424012#pfrom=home-ndtv_featured",
      "domain_url": "ndtv.com",
      "full_domain_url": "ndtv.com",
      "name_source": "NDTV",
      "is_headline": false,
      "paid_content": false,
      "parent_url": "https://www.ndtv.com",
      "country": "IN",
      "rights": "ndtv.com",
      "rank": 920,
      "media": "https://c.ndtvimg.com/2023-09/4dau661g_elon-musk-reuters_625x300_13_September_23.jpg",
      "language": "en",
      "description": "His post has since received more than 3 million views with a flurry of comments on X.",
      "content": "Billionaire Elon Musk, the founder and owner of Tesla, X.com, SpaceX, Neuralink and The Boring Company's recent post on 'X' is going viral. He wrote on X, \"Nobody-that's my name\". His post has since received more than 3 million views with a flurry of comments on X. See the post here: Nobody—that's my name — Elon Musk (@elonmusk) September 26, 2023 While some users asked Mr Musk if he was \"okay\", others started a meme fest. A user wrote, \"You good bro?\" Another user commented, \"Hi Nobody.\" \"When Elon makes a post, millions of phones ding around the world and people rush to respond and get his attention,\" the third user wrote. \"Tomorrow is another day,\" the fourth user wrote. \"Everybody - that's my name,\" the fifth user commented. Meanwhile, earlier, billionaire Elon Musk stated that he is buying the iPhone 15 and many of us would agree with his reason. Mr Musk said, \"The beauty of iPhone pictures & video is incredible.\" Elon Musk is ranked as the world's richest person by Forbes and Bloomberg Billionaires Index, with a total net worth of $236 billion. Unlike other billionaires and usual investment stories, Mr Musk undertook some risky investment options which ultimately made him the richest private citizen on the planet since 2021. Mr Musk's ownership share in electric vehicle manufacturer Tesla and his holdings in SpaceX and the Boring Company are responsible for his startling increase in fortune. However, Tesla has been the main source of his wealth, with the company's stock rising by more than 1,100 per cent in the last five years as investors rewarded it for its rise in vehicle sales.",
      "word_count": 275,
      "is_opinion": false,
      "twitter_account": "@ndtv",
      "all_links": [
        "https://www.jiosaavn.com/featured/new-music-this-week/Ns2UZo9qDvI",
        "https://www.ndtvgames.com/#pfrom=ndtv-globalnav",
        "https://www.gadgets360.com/mobiles/phone-finder",
        "https://mpcg.ndtv.in",
        "https://twitter.com/elonmusk/status/1706510175144649057?ref_src=twsrc%5Etfw",
        "https://ndtv.in/videos/live/channel/ndtvindia",
        "https://hotdeals360.com/beauty/best-glycolic-acid-toners-for-blemish-free-glowing-skin-4394322",
        "https://hotdeals360.com/beauty/best-glitter-lip-glosses-that-are-trending-in-the-world-of-beauty-4398727",
        "https://rajasthan.ndtv.in",
        "https://www.whatsapp.com/channel/0029Va4lixw7z4kcvZI9JM12",
        "https://twitter.com/ndtv",
        "https://www.instagram.com/ndtv/",
        "https://www.facebook.com/ndtv",
        "https://www.gadgets360.com/#pfrom=ndtv-globalnav",
        "https://rajasthan.ndtv.in/livetv-ndtvrajasthan",
        "https://www.jiosaavn.com",
        "https://www.whosthat360.com/finance/anushka-rathod-avoid-this-common-mistake-when-investing-in-mutual-funds-4408067",
        "https://www.gadgets360.com/internet/news/flipkart-big-billion-days-sale-2023-instant-bank-discount-details-teased-offers-deals-4417000",
        "https://ndtv.in/#pfrom=ndtv-globalnav",
        "https://mpcg.ndtv.in/livetv-ndtvmpcg",
        "https://www.gadgets360.com/internet/features/amazon-great-indian-festival-sale-date-october-10-leak-deals-discounts-offers-4420830"
      ],
      "all_domain_links": [
        "instagram.com",
        "whatsapp.com",
        "twitter.com",
        "gadgets360.com",
        "hotdeals360.com",
        "whosthat360.com",
        "ndtvgames.com",
        "jiosaavn.com",
        "ndtv.in",
        "facebook.com"
      ],
      "nlp": {
        "theme": "Business",
        "summary": "Elon Musk is the founder and owner of Tesla, X.com, SpaceX, Neuralink and The Boring Company. He wrote on X, \"Nobody-that's my name\". His post has since received more than 3 million views. He is ranked as the world's richest person with a net worth of $236 billion.",
        "sentiment": {
          "title": 0,
          "content": 0
        },
        "ner_PER": [
          {
            "entity_name": "Elon Musk",
            "count": 4
          },
          {
            "entity_name": "Musk",
            "count": 4
          },
          {
            "entity_name": "Elon",
            "count": 1
          }
        ],
        "ner_ORG": [
          {
            "entity_name": "Tesla",
            "count": 3
          },
          {
            "entity_name": "SpaceX",
            "count": 2
          },
          {
            "entity_name": "X.com",
            "count": 1
          },
          {
            "entity_name": "Neuralink",
            "count": 1
          },
          {
            "entity_name": "The Boring Company",
            "count": 1
          },
          {
            "entity_name": "Forbes",
            "count": 1
          },
          {
            "entity_name": "Boring Company",
            "count": 1
          }
        ],
        "ner_MISC": [
          {
            "entity_name": "iPhone 15",
            "count": 1
          },
          {
            "entity_name": "iPhone",
            "count": 1
          },
          {
            "entity_name": "Bloomberg Billionaires Index",
            "count": 1
          }
        ],
        "ner_LOC": []
      },
      "id": "c63576c21d9da5d27e13424f023d4ef8",
      "score": 23.87998
    },
    ...
    ],
    "user_input": {...}
}

{
    "status": "error",
    "error_code": "UnsupportedParameter",
    "message": "Found unsupported parameter(s)['sort_by', 'q']. Here are the parameters available for this endpoint => ['countries', 'topic', 'lang']"
}

{
    "status": "error",
    "error_code": "UnsupportedParameter",
    "message": "Request takes more than 30 seconds. Your search is too broad.Try to use more parameters to narrow down the request."
}

{
  "status": "error",
  "error_code": "ConcurrencyViolation",
  "message": "Max concurrency allowed 1 per 1 second"
}

{
    "message": "Forbidden",
    "code": 403
}

{
    "message": "Param langs is not allowed for plan nlp"
}

Successful Request Response

{
    "status": "ok",
    "total_hits": 6969,
    "page": 1,
    "total_pages": 70,
    "page_size": 100,
    "articles": [
       {
      "title": "Rabbit sells more than 10,000 units of its extremely interesting pocket AI companion",
      "author": "Jak Connor",
      "authors": [
        "Jak Connor"
      ],
      "journalists": [
        "Jak Connor"
      ],
      "published_date": "2024-01-17 16:05:03",
      "published_date_precision": "full",
      "updated_date": null,
      "updated_date_precision": null,
      "link": "https://www.tweaktown.com/news/95657/rabbit-sells-more-than-10-000-units-of-its-extremely-interesting-pocket-ai-companion/index.html",
      "domain_url": "tweaktown.com",
      "full_domain_url": "tweaktown.com",
      "name_source": "TweakTown",
      "is_headline": true,
      "paid_content": false,
      "parent_url": "https://www.tweaktown.com/news",
      "country": "US",
      "rights": "tweaktown.com",
      "rank": 7324,
      "media": "https://static.tweaktown.com/news/9/5/95657_8481_rabbit_full.png",
      "language": "en",
      "description": "AI startup company Rabbit has announced that it has sold out two batches of its R1, an AI companion device designed to be a pocket virtual assistant.",
      "content": "AI startup company Rabbit has announced that it has sold out two batches of its R1, an AI companion device designed to be a pocket virtual assistant.\nStartup company Rabbit gained massive attention at the CES event this year and has had to open up a second production run of its new AI-powered pocket assistant, the R1, after it sold 10,000 units on the very first day of pre-orders. After just one day of pre-orders being live, Rabbit announced it has sold out of their first run of AI companions, taking to social platform X to say, \"When we started building R1, we said internally that we'd be happy if we sold 500 devices on launch day.\" absolutely smashing that they added, \"In 24 hours, we already beat that by 20x!\" Rabbit unveiled the funky orange pocket pal during a showcase on Tuesday, which comes with a 2.88-inch touchscreen and runs on Rabbits OS. The device uses its \"Large Action Model\" as a universal controller for apps to allow it to do things like play music, order an Uber, buy groceries, and send messages through one interface without the need for a phone or computer. The device is also trainable, allowing users to set how the R1 interacts with apps. 2 VIEW GALLERY - 2 IMAGES Although Rabbit is completely sold out on their first line of production, due between March and April of this year, you can still pre-order the R1 directly through Rabbit's website. Rabbit says consumers can expect the delivery date for the device to be between April and May of this year, meaning those who missed out on the first set of pre-orders won't have to wait very long.",
      "word_count": 283,
      "is_opinion": false,
      "twitter_account": "@TweakTown",
      "all_links": [
        "https://twitter.com/1/status/1745186588475502718",
        "https://click.linksynergy.com/deeplink?id=RZrrn*9L87M&mid=44583&murl=https://www.newegg.com",
        "https://www.amazon.com/dp/B0BY3J3ZPZ?tag=twea-20",
        "https://www.tweaktownforum.com",
        "https://www.amazon.com/dp/B07WTS8T2W?tag=twea-20",
        "https://www.amazon.com/dp/B0B469JRGC?tag=twea-20",
        "https://www.youtube.com/user/tweaktown?sub_confirmation=1",
        "https://www.amazon.com/dp/B00OAJ412U?tag=twea-20",
        "https://twitter.com/TweakTown",
        "https://www.amazon.com/dp/B07GCKQD77?tag=twea-20",
        "https://www.amazon.com/dp/B08166SLDF?tag=twea-20",
        "https://www.pinterest.com/tweaktown/",
        "https://www.amazon.com/dp/B07NY9ZRZG?tag=twea-20",
        "https://www.facebook.com/TweakTown",
        "https://www.amazon.com/dp/B0BLCBLCDR?tag=twea-20",
        "https://www.amazon.com/dp/B09WCHGP12?tag=twea-20",
        "https://www.amazon.com/dp/B07C438TMN?tag=twea-20&linkCode=ogi&th=1&psc=1",
        "https://www.amazon.com/dp/B07SZXBTNW?tag=twea-20",
        "https://www.amazon.com/dp/B0BP8B6M7Y?tag=twea-20",
        "https://www.theverge.com/2024/1/10/24033498/rabbit-r1-sold-out-ces-ai"
      ],
      "all_domain_links": [
        "tweaktownforum.com",
        "twitter.com",
        "facebook.com",
        "amazon.com",
        "theverge.com",
        "linksynergy.com",
        "pinterest.com",
        "youtube.com"
      ],
      "nlp": {
        "theme": "Business, Tech",
        "summary": "Rabbit sold 10,000 units of their pocket virtual assistant R1 on the first day of pre-orders. The R1 is an AI-powered device with a 2.88-inch touchscreen and runs on Rabbits OS. The first production run of the R1 sold out in 24 hours. The second production run will be ready between April and May.",
        "sentiment": {
          "title": 0,
          "content": 0.9992566704750061
        },
        "ner_PER": [],
        "ner_ORG": [
          {
            "entity_name": "Rabbit",
            "count": 7
          },
          {
            "entity_name": "Uber",
            "count": 1
          }
        ],
        "ner_MISC": [
          {
            "entity_name": "R1",
            "count": 5
          },
          {
            "entity_name": "CES",
            "count": 1
          },
          {
            "entity_name": "Rabbits OS",
            "count": 1
          },
          {
            "entity_name": "allowing",
            "count": 1
          },
          {
            "entity_name": "VIEW",
            "count": 1
          }
        ],
        "ner_LOC": [],
        "iptc_tags_name": [
          "science and technology / technology and engineering / agricultural technology",
          "economy, business and finance / products and services / consumer goods / consumer electronics",
          "economy, business and finance / business information / business strategy and marketing / new product or service"
        ],
        "iptc_tags_id": [
          "20000192",
          "20000205",
          "20000170",
          "13000000",
          "20000243",
          "04000000",
          "20001258",
          "20000756",
          "20000209",
          "20000759"
        ]
      },
      "id": "164de9168279ea19a096bc5e24428753",
      "score": 30.279182
    },
    ...
    ],
    "user_input": {...}
}

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

authors

List of all author names

journalists

Clean list of journalists. No news publishcation names, only people.

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

updated_date

Updated date & time

updated_date_precision

Accuracy of the updated_datefield.

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

domain_url

The domain URL of the article's source

full_domain_url

The full domain URL with a subcategory of the article's source

name_source

The common name of the News Source

is_headline

True when an article has been seen on the main page of the news source.

parent_url

The URL where an article was initially found

country

The country of the publisher

rights

rank

The page rank of the source website (which is given in the clean_url)

media

A link to a thumbnail image of the article

language

The language of the article

description

Short summary of the article provided by the publisher

content

The full content of the article

word_count

Number of words in the article's content

is_opinion

True if the article is an "Opinion" article

twitter_account

The Twitter account of the publisher

all_links

All URL links embedded in the article's content HTML

all_domain_links

All domain URL embedded in the article's content HTML

nlp

Depending on your plan your can have : - summary- sentiment- theme- ner- embeddings- iptc_tags_name- iptc_tags_ids

id

Newscatcher API's unique identifier for each news article

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

user_input

An object that returns how the API 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

Supercharge Your News Searches

A lot can be done using the search endpoint, and we are constantly working on new functionalities to make it more powerful and valuable. Here are the functionalities that we recommend

Make More Precise Query

There's a lot you can do with simple keyword-based searches. Using exact matching and boolean operators, you can exclude a set of words or combine multiple queries related to a topic of interest into one query. There's also proximity-based searching for more sophisticated querying.

pageAdvance Querying

Deduplicate Articles

Most significant events and topics get massive coverage from 10s of news publications. Some media conglomerates even republish the articles. You or your analysts don't need to sift through all of these articles with duplicate information; use the clustering functionality in our search endpoint to get groups of articles with distinct bits of information.

pageClustering News Articles

Apple Or apple?

Sometimes, it's necessary to specify whether the keyword you're looking for is an organization or a person. For instance, take the tech giant Apple. If you were looking for articles about a recent development about Apple, you would want to get articles about apple prices or orchids, would you?

pageSearch By Entity

What Is This Linked To?

The links in an article can serve as valuable markers. Want to find all articles talking about a specific research paper or a press release? Which company named XYZ is this referring to?

pageSearch By URL

Previousv3 Authentication 🗝NextAdvance Querying

Last updated 3 days ago