GET
/
api
/
breaking_news
curl --request GET \
  --url https://v3-api.newscatcherapi.com/api/breaking_news \
  --header 'x-api-token: <api-key>'
{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "articles": [],
  "user_input": {}
}

Authorizations

​
x-api-token
string
header
required

API Key to authenticate requests.

To access the API, include your API key in the x-api-token header. To obtain your API key, complete the form or contact us directly.

Query Parameters

​
sort_by
enum<string>
default:relevancy

The sorting order of the results. Possible values are:

  • relevancy: The most relevant results first.
  • date: The most recently published results first.
  • rank: The results from the highest-ranked sources first.
Available options:
relevancy,
date,
rank
​
ranked_only
boolean
default:true

If true, limits the search to sources ranked in the top 1 million online websites. If false, includes unranked sources which are assigned a rank of 999999.

​
from_rank
integer
default:1

The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

Required range: 1 <= x <= 999999
​
to_rank
integer
default:999999

The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.

Required range: 1 <= x <= 999999
​
page
integer
default:1

The page number to scroll through the results. Use for pagination, as a single API response can return up to 1,000 articles.

For details, see How to paginate large datasets.

Required range: x >= 1
​
page_size
integer
default:100

The number of articles to return per page.

Required range: 1 <= x <= 1000
​
include_nlp_data
boolean
default:false

If true, includes an NLP object for each article in the response. This object provides results of NLP analysis, including article theme, summary, sentiment, tags, and named entity recognition if available.

Note: NLP coverage and analysis completeness may vary by language, with full data available for articles in English and Arabic. The include_nlp_data parameter is available only in NLP subscription plans.

To learn more, see NLP features.

Example:

true

​
has_nlp
boolean
default:false

If true, filters results to include only articles that have NLP data.

Note: NLP coverage and analysis completeness may vary by language, with full data available for articles in English and Arabic. The has_nlp parameter is available only in NLP subscription plans.

To learn more, see NLP features.

Example:

true

​
theme
string

Filters articles based on their general topic, as determined by NLP analysis. To select multiple themes, use a comma-separated string.

Example: "Finance, Tech"

Note: The theme parameter is only available if NLP is included in your subscription plan.

To learn more, see NLP features.

Available options: Business, Economics, Entertainment, Finance, Health, Politics, Science, Sports, Tech, Crime, Financial Crime, Lifestyle, Automotive, Travel, Weather, General.

​
not_theme
string

Inverse of the theme parameter. Excludes articles based on their general topic, as determined by NLP analysis. To exclude multiple themes, use a comma-separated string.

Example: "Crime, Tech"

Note: The not_theme parameter is only available if NLP is included in your subscription plan.

To learn more, see NLP features.

​
ORG_entity_name
string

Filters articles that mention specific organization names, as identified by NLP analysis. To specify multiple organizations, use a comma-separated string.

Example: "Apple, Microsoft"

Note: The ORG_entity_name parameter is only available if NLP is included in your subscription plan.

To learn more, see Search by entity.

​
PER_entity_name
string

Filters articles that mention specific person names, as identified by NLP analysis. To specify multiple names, use a comma-separated string.

Example: "Elon Musk, Jeff Bezos"

Note: The PER_entity_name parameter is only available if NLP is included in your subscription plan.

To learn more, see Search by entity.

​
LOC_entity_name
string

Filters articles that mention specific location names, as identified by NLP analysis. To specify multiple locations, use a comma-separated string.

Example: "California, New York"

Note: The LOC_entity_name parameter is only available if NLP is included in your subscription plan.

To learn more, see Search by entity.

​
MISC_entity_name
string

Filters articles that mention other named entities not falling under person, organization, or location categories. Includes events, nationalities, products, works of art, and more. To specify multiple entities, use a comma-separated string.

Example: "Bitcoin, Blockchain"

Note: The MISC_entity_name parameter is only available if NLP is included in your subscription plan.

To learn more, see Search by entity.

​
title_sentiment_min
number

Filters articles based on the minimum sentiment score of their titles.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

Note: The title_sentiment_min parameter is only available if NLP is included in your subscription plan.

To learn more, see NLP features.

Required range: -1 <= x <= 1
​
title_sentiment_max
number

Filters articles based on the maximum sentiment score of their titles.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

Note: The title_sentiment_max parameter is only available if NLP is included in your subscription plan.

To learn more, see NLP features.

Required range: -1 <= x <= 1
​
content_sentiment_min
number

Filters articles based on the minimum sentiment score of their content.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

Note: The content_sentiment_min parameter is only available if NLP is included in your subscription plan.

To learn more, see NLP features.

Required range: -1 <= x <= 1
​
content_sentiment_max
number

Filters articles based on the maximum sentiment score of their content.

Range is -1.0 to 1.0, where:

  • Negative values indicate negative sentiment.
  • Positive values indicate positive sentiment.
  • Values close to 0 indicate neutral sentiment.

Note: The content_sentiment_max parameter is only available if NLP is included in your subscription plan.

To learn more, see NLP features.

Required range: -1 <= x <= 1

Response

200
application/json
A successful response containing breaking news articles with additional breaking news event information.

The response model for the breaking news requests. Response field behavior:

  • Required fields are guaranteed to be present and non-null.
  • Optional fields may be null or undefined if the data point is not presented or couldn't be extracted during processing.
  • To access article properties in the articles response array, use array index notation. For example, articles[n].title, where n is the zero-based index of the article object (0, 1, 2, etc.).
  • The nlp property within the article object articles[n].nlp is only available with NLP-enabled subscription plans.
​
status
string
required

The status of the response.

​
total_hits
integer
required

The total number of articles matching the search criteria.

​
page
integer
required

The current page number of the results.

​
total_pages
integer
required

The total number of pages available for the given search criteria.

​
page_size
integer
required

The number of articles per page.

​
articles
object[]

A list of articles matching the search criteria.

The data model representing a single article in the Breaking news search results.

​
user_input
object

The user input parameters for the request.

Was this page helpful?

Suggest editsRaise issue