v3 Latest Headlines
Get the latest headlines given any topic, country, source, or language
Last updated
Get the latest headlines given any topic, country, source, or language
Last updated
GET https://v3-api.newscatcherapi.com/api/latest_headlines?when=1h&by_parse_date=false&page=1&page_size=100
| Name | Type | Description |
|---|---|---|
POST https://v3-api.newscatcherapi.com/api/latest_headlines
JSON format query input
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
ranked_only
string
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
when
string
The time period you want to get the latest headlines for.
Accepted forms:
- 7d => Dailly Form (last 7 days time period), 30d (last 30 days time period)
- 1h => Hourly Form (last hour), 24h (last 24 hours)
Default: The number of historic data available for your subscription plan
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 Allowed Languages section for more details.
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.
theme
string
[Available only if NLP is enabled for your API key]
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
Topic labelling is based on the actual content of an article.
sources
array
One or more news resources to filter your search. It should be the normal form of the URL,
For example, nytimes.com,theguardian.com
not_sources
array
One or more sources to be excluded from the search.
Comma-separated list. For example, wsj.com
page_size
integer
[1:100] 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 100 articles.
by_parse_date
boolean
When set to True, transforms your when 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.
is_opinion
boolean
[Still in development phase]
When set to True, only articles that are determined to be an opinion piece will be returned. Set False to exclude opinion-based articles and receive news only.
predefined_sources
string
Use our TOP predefined sources per country.
Later, we will improve it and add more functionality, like top categories.
The format should be strictly like this:
-starting with the word top
-put the number of desired sources on 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 a custom number of top sources, which should be comma-separated.
For example:
top 100 US, GB
top 33 AT, 55 IT
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.
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
word_count_min
integer
Set a minimum number of words that an article must contain.
word_count_max
integer
Set a maximum number of words that an article must contain.
include_nlp_data
boolean
[Available only if NLP is enabled for your API key]
When set to True, adds to each article an NLP layer.
Not available for all plans. Please get in touch with us to enable it.
has_nlp
boolean
[Available only if NLP is enabled for your API key]
When set to True, filter data only to articles with an NLP layer.
title_sentiment_min
float
[Available only if NLP is enabled for your API key]
You can narrow 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]
You can narrow 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 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.
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
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
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
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.
x-api-token
string
Your unique authentication token
x-api-token
string
Your unique authentication token
ranked_only
string
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
when
string
The time period you want to get the latest headlines for.
Accepted forms:
- 7d => Dailly Form (last 7 days time period), 30d (last 30 days time period)
- 1h => Hourly Form (last hour), 24h (last 24 hours)
Default: The number of historic data available for your subscription plan
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 Allowed Languages section for more details.
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.
theme
string
[Available only if NLP is enabled for your API key]
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
Topic labelling is based on the actual content of an article.
sources
array
One or more news resources to filter your search. It should be the normal form of the URL,
For example, nytimes.com,theguardian.com
not_sources
array
One or more sources to be excluded from the search.
Comma-separated list. For example, wsj.com
page_size
integer
[1:100] 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 100 articles.
by_parse_date
boolean
When set to True, transforms your when 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.
predefined_sources
string
Use our TOP predefined sources per country.
Later, we will improve it and add more functionality, like top categories.
The format should be strictly like this:
-starting with the word top
-put the number of desired sources on 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 a custom number of top sources, which should be comma-separated.
For example:
top 100 US, GB
top 33 AT, 55 IT
is_headline
boolean
When set to True, only articles that were posted on the home page of a given news domain will be shown.
is_headline
boolean
[Still in development phase]
When set to True, only articles that are determined to be an opinion piece will be returned. Set False to exclude opinion-based articles and receive news only.
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.
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
word_count_min
integer
Set a minimum number of words that an article must contain.
word_count_max
integer
Set a maximum number of words that an article can contain.
include_nlp_data
boolean
[Available only if NLP is enabled for your API key]
When set to True, adds to each article an NLP layer.
Not available for all plans. Please get in touch with us to enable it.
has_nlp
boolean
[Available only if NLP is enabled for your API key]
When set to True, filter data only to articles with an NLP layer.
title_sentiment_min
float
[Available only if NLP is enabled for your API key]
You can narrow 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]
You can narrow 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 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.
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
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_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.
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
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
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
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
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.