Get breaking news

curl --request GET \
  --url https://v3-api.newscatcherapi.com/api/breaking_news \
  --header 'x-api-token: <api-key>'

const options = {method: 'GET', headers: {'x-api-token': '<api-key>'}};

fetch('https://v3-api.newscatcherapi.com/api/breaking_news', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://v3-api.newscatcherapi.com/api/breaking_news",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://v3-api.newscatcherapi.com/api/breaking_news"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://v3-api.newscatcherapi.com/api/breaking_news")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "breaking_news_events": [],
  "user_input": {}
}

{
  "message": "Invalid JSON in request body",
  "status_code": 400,
  "status": "Bad request"
}

{
  "message": "The 'x-api-token' parameter has an invalid value. Please provide a valid API key.",
  "status_code": 401,
  "status": "Unauthorized"
}

{
  "message": "Your plan request date range cannot be greater than 400 days",
  "status_code": 403,
  "status": "Forbidden"
}

{
  "message": "Request timed out after 30 seconds",
  "status_code": 408,
  "status": "Request timeout"
}

{
  "message": "Invalid date format",
  "status_code": 422,
  "status": "Validation error"
}

{
  "message": "Max API requests concurrency reached",
  "status_code": 429,
  "status": "Too many requests"
}

Internal Server Error

GET

api

breaking_news

Get breaking news

curl --request GET \
  --url https://v3-api.newscatcherapi.com/api/breaking_news \
  --header 'x-api-token: <api-key>'

const options = {method: 'GET', headers: {'x-api-token': '<api-key>'}};

fetch('https://v3-api.newscatcherapi.com/api/breaking_news', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://v3-api.newscatcherapi.com/api/breaking_news",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://v3-api.newscatcherapi.com/api/breaking_news"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://v3-api.newscatcherapi.com/api/breaking_news")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "breaking_news_events": [],
  "user_input": {}
}

{
  "message": "Invalid JSON in request body",
  "status_code": 400,
  "status": "Bad request"
}

{
  "message": "The 'x-api-token' parameter has an invalid value. Please provide a valid API key.",
  "status_code": 401,
  "status": "Unauthorized"
}

{
  "message": "Your plan request date range cannot be greater than 400 days",
  "status_code": 403,
  "status": "Forbidden"
}

{
  "message": "Request timed out after 30 seconds",
  "status_code": 408,
  "status": "Request timeout"
}

{
  "message": "Invalid date format",
  "status_code": 422,
  "status": "Validation error"
}

{
  "message": "Max API requests concurrency reached",
  "status_code": 429,
  "status": "Too many requests"
}

Internal Server Error

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

Example:

"date"

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.

Example:

true

from_rank

integer<int32>

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

Example:

100

to_rank

integer<int32>

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

Example:

100

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 Retrieve large datasets

Required range: x >= 1

Example:

2

page_size

integer

default:100

The number of articles to return per page.

Required range: 1 <= x <= 1000

Example:

50

top_n_articles

integer

default:1

Controls the number of top articles to include for each breaking news event.

Important limitations:

Maximum value is 100.
The product of top_n_articles x page_size must not exceed 1,000 (total articles limit).

Required range: 1 <= x <= 100

Example:

5

include_translation_fields

boolean

default:false

If true, includes English translation fields in the response (title_translated_en, content_translated_en, and NLP translation fields).

Example:

true

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 data is only available for articles indexed from July 2023 onward. For articles indexed before July 2023, the nlp field is returned as an empty object {}.

To learn more, see NLP Enrichments.

Example:

true

has_nlp

boolean

default:false

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

Note: NLP data is only available for articles indexed from July 2023 onward. Applying this filter to a date range that predates July 2023 returns zero results.

To learn more, see NLP Enrichments.

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.

To learn more, see NLP Enrichments.

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

Example:

"Finance,Tech"

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.

To learn more, see NLP Enrichments.

Example:

"Crime,Sports"

content_type

string

Filters articles by content type: the kind of page an article is, as determined by NLP analysis. To select multiple content types, use a comma-separated string. Values are case-insensitive, and an article is returned if it matches any of them.

Available options: news_report, analysis, interview, opinion, press_release, listicle, service, commerce, review, autogen, seo_spam, obituary, ugc, non_article. Shortcuts: news selects news_report, analysis, and interview; all applies no filter.

Note: Articles without a content type label are excluded whenever content_type is set. An unknown value returns a 422 error.

To learn more, see Content types.

Example:

"news"

ORG_entity_name

string

Filters articles that mention specific organization names, as identified by NLP analysis.

To specify multiple organizations, use AND, OR, NOT operators, and \" escape literals for exact matches.
To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"\"Apple Inc\" OR Microsoft"

PER_entity_name

string

Filters articles that mention specific person names, as identified by NLP analysis.

To specify multiple names, use AND, OR, NOT operators, and \" escape literals for exact matches.
To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"\"Elon Musk\" OR \"Jeff Bezos\""

LOC_entity_name

string

Filters articles that mention specific location names, as identified by NLP analysis.

To specify multiple locations, use AND, OR, NOT operators, and \" escape literals for exact matches.
To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"\"San Francisco\" OR \"New York City\""

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 AND, OR, NOT operators, and \" escape literals for exact matches.
To search in translations, combine with the translation options of the search_in parameter (e.g., title_content_translated).

To learn more, see Search by entity.

Example:

"AWS OR \"Microsoft Azure\""

title_sentiment_min

number<float>

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.

To learn more, see NLP Enrichments.

Required range: -1 <= x <= 1

Example:

-0.5

title_sentiment_max

number<float>

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.

To learn more, see NLP Enrichments.

Required range: -1 <= x <= 1

Example:

0.5

content_sentiment_min

number<float>

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.

To learn more, see NLP Enrichments.

Required range: -1 <= x <= 1

Example:

-0.5

content_sentiment_max

number<float>

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.

To learn more, see NLP Enrichments.

Required range: -1 <= x <= 1

Example:

0.5

robots_compliant

boolean

If true, returns only articles that comply with the publisher's robots.txt rules. If false, returns only articles that do not comply with robots.txt rules. If omitted, returns all articles regardless of compliance status.

Example:

true

Response

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.

breaking_news_events

Breaking News Event Object · object[]

A list of breaking news events, each containing relevant articles.

Show child attributes

user_input

object

The user input parameters for the request.

Get started

Guides and concepts

How to

Troubleshooting

API Reference

Integrations

Libraries

Get breaking news

Authorizations

Query Parameters

Response