Get aggregation count by interval

curl --request POST \
  --url https://v3-api.newscatcherapi.com/api/aggregation_count \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '
{
  "q": "\"supply chain\" AND Amazon NOT China",
  "aggregation_by": "day"
}
'

import requests

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

payload = {
    "q": "\"supply chain\" AND Amazon NOT China",
    "aggregation_by": "day"
}
headers = {
    "x-api-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({q: '"supply chain" AND Amazon NOT China', aggregation_by: 'day'})
};

fetch('https://v3-api.newscatcherapi.com/api/aggregation_count', 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/aggregation_count",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'q' => '"supply chain" AND Amazon NOT China',
    'aggregation_by' => 'day'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"q\": \"\\\"supply chain\\\" AND Amazon NOT China\",\n  \"aggregation_by\": \"day\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://v3-api.newscatcherapi.com/api/aggregation_count")
  .header("x-api-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"\\\"supply chain\\\" AND Amazon NOT China\",\n  \"aggregation_by\": \"day\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["x-api-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"q\": \"\\\"supply chain\\\" AND Amazon NOT China\",\n  \"aggregation_by\": \"day\"\n}"

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

{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "aggregations": {
    "aggregation_count": [
      {
        "time_frame": "2024-12-31 00:00:00",
        "article_count": 86
      }
    ]
  },
  "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

POST

api

aggregation_count

Get aggregation count by interval

curl --request POST \
  --url https://v3-api.newscatcherapi.com/api/aggregation_count \
  --header 'Content-Type: application/json' \
  --header 'x-api-token: <api-key>' \
  --data '
{
  "q": "\"supply chain\" AND Amazon NOT China",
  "aggregation_by": "day"
}
'

import requests

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

payload = {
    "q": "\"supply chain\" AND Amazon NOT China",
    "aggregation_by": "day"
}
headers = {
    "x-api-token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({q: '"supply chain" AND Amazon NOT China', aggregation_by: 'day'})
};

fetch('https://v3-api.newscatcherapi.com/api/aggregation_count', 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/aggregation_count",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'q' => '"supply chain" AND Amazon NOT China',
    'aggregation_by' => 'day'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"q\": \"\\\"supply chain\\\" AND Amazon NOT China\",\n  \"aggregation_by\": \"day\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://v3-api.newscatcherapi.com/api/aggregation_count")
  .header("x-api-token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"\\\"supply chain\\\" AND Amazon NOT China\",\n  \"aggregation_by\": \"day\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["x-api-token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"q\": \"\\\"supply chain\\\" AND Amazon NOT China\",\n  \"aggregation_by\": \"day\"\n}"

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

{
  "status": "<string>",
  "total_hits": 123,
  "page": 123,
  "total_pages": 123,
  "page_size": 123,
  "aggregations": {
    "aggregation_count": [
      {
        "time_frame": "2024-12-31 00:00:00",
        "article_count": 86
      }
    ]
  },
  "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.

Body

application/json

Request body for aggregation counts based on specified criteria such as keyword, language, country, source, and more.

string

required

The keyword(s) to search for in articles. Query syntax supports logical operators (AND, OR, NOT) and wildcards:

For exact phrases, use escaped quotes: \"technology news\"
Use * for wildcards: technolog* (cannot start with *)
Use + to include and - to exclude: +Apple, -Google
Boolean operators: technology AND (Apple OR Microsoft) NOT Google
Forbidden characters: [ ] / \\ : ^ and URL-encoded equivalents

Note: The API automatically inserts AND operators between standalone terms, so strings like "machine learning" become "machine AND learning". To avoid syntax errors (especially in queries with OR operators), use literal escape "\"machine learning\"".

For detailed syntax rules, see Advanced querying.

Example:

"\"supply chain\" AND Amazon NOT China"

aggregation_by

enum<string>

default:day

The aggregation interval for the results.

Available options:

day,

hour,

month

search_in

string

default:title_content

The article fields to search in. Use a comma-separated string for multiple options, with a maximum of 2 in a single request.

Available options:

Standard fields: title, content, summary, title_content
Translation fields: title_translated, content_translated, summary_translated, title_content_translated

Example:

"title_content, title_content_translated"

predefined_sources

Predefined top news sources per country.

Format: start with the word top, followed by the number of desired sources, and then the two-letter country code ISO 3166-1 alpha-2.

Multiple countries with the number of top sources can be specified as a comma-separated string or an array of strings.

Example:

"top 50 US, top 20 GB"

sources

One or more news sources to narrow down the search. The format must be a domain URL. Subdomains, such as finance.yahoo.com, are also acceptable. To specify multiple sources, use a comma-separated string or an array of strings.

Example:

"nytimes.com, theguardian.com"

not_sources

The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string or an array of strings.

Example:

"cnn.com, wsj.com"

lang

The language(s) of the search. The only accepted format is the two-letter ISO 639-1 code. To select multiple languages, use a comma-separated string or an array of strings.

To learn more, see Enumerated parameters > Language.

Example:

"en,es"

not_lang

The language(s) to exclude from the search. The accepted format is the two-letter ISO 639-1 code. To exclude multiple languages, use a comma-separated string or an array of strings.

To learn more, see Enumerated parameters > Language.

Example:

"fr,de"

countries

The countries where the news publisher is located. The accepted format is the two-letter ISO 3166-1 alpha-2 code. To select multiple countries, use a comma-separated string or an array of strings.

To learn more, see Enumerated parameters > Country.

Example:

"US,CA"

not_countries

The publisher location countries to exclude from the search. The accepted format is the two-letter ISO 3166-1 alpha-2 code. To exclude multiple countries, use a comma-separated string or an array of strings.

To learn more, see Enumerated parameters > Country.

Example:

"UK,FR"

not_author_name

The list of author names to exclude from your search. To exclude articles by specific authors, use a comma-separated string or an array of strings.

Example:

"John Doe, Jane Doe"

from_

default:7 days ago

The starting point in time to search from. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC.

Formats with examples:

YYYY-mm-ddTHH:MM:SS: 2024-07-01T00:00:00
YYYY-MM-dd: 2024-07-01
YYYY/mm/dd HH:MM:SS: 2024/07/01 00:00:00
YYYY/mm/dd: 2024/07/01
English phrases: 7 day ago, today
Duration shorthand: 7d, 30d, 24h, 48h

Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.

Example:

"2021/01/01"

to_

default:now

The ending point in time to search up to. Accepts date-time strings in ISO 8601 format and plain text strings. The default time zone is UTC.

Formats with examples:

YYYY-mm-ddTHH:MM:SS: 2024-07-01T00:00:00
YYYY-MM-dd: 2024-07-01
YYYY/mm/dd HH:MM:SS: 2024/07/01 00:00:00
YYYY/mm/dd: 2024/07/01
English phrases: 1 day ago, now
Duration shorthand: 7d, 30d, 24h, 48h

Note: By default, applied to the publication date of the article. To use the article's parse date instead, set the by_parse_date parameter to true.

Example:

"now"

published_date_precision

string

The precision of the published date. There are three types:

full: The day and time of an article is correctly identified with the appropriate timezone.
timezone unknown: The day and time of an article is correctly identified without timezone.
date: Only the day is identified without an exact time.

Example:

"full"

by_parse_date

boolean

default:false

If true, the from_ and to_ parameters use article parse dates instead of published dates. Additionally, the parse_date variable is added to the output for each article object.

In the Aggregation count endpoint, the articles are also counted per interval by their parse date.

Example:

true

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

is_headline

boolean

If true, only returns articles that were posted on the home page of a given news domain.

Example:

true

is_opinion

boolean

If true, returns only opinion pieces. If false, excludes opinion-based articles and returns news only.

Example:

true

is_paid_content

boolean

Filters articles by content completeness.

If false, returns only articles for which full-text content is publicly available. If true, returns all indexed articles, including those where only partial content is publicly available (e.g., headlines, summaries, or preview paragraphs from paywalled sources).

Note: NewsCatcher indexes content that is publicly accessible and available for crawling in accordance with publisher access controls (e.g., robots.txt and similar mechanisms). For paywalled sources, only content that publishers make publicly available (such as headlines, summaries, or preview text) is indexed. NewsCatcher does not bypass paywalls, authentication systems, or other technical access restrictions.

Example:

false

parent_url

The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string or an array of strings.

Example:

"wsj.com/politics,wsj.com/tech"

all_links

The complete URL(s) mentioned in the article. For multiple URLs, use a comma-separated string or an array of strings.

For more details, see Search by URL.

Example:

"https://aiindex.stanford.edu/report/, https://www.stateof.ai/"

all_domain_links

The domain(s) mentioned in the article. For multiple domains, use a comma-separated string or an array of strings.

For more details, see Search by URL.

Example:

"who.int, nih.gov"

all_links_text

The text content of links mentioned in the article. Searches for links where the anchor text contains the specified terms. For multiple terms, use a comma-separated string or an array of strings.

Note: When this parameter is used, the response includes the all_links_data field with detailed link information.

For more details, see Search by URL.

Example:

"Nvidia, Tesla"

word_count_min

integer

The minimum number of words an article must contain. To be used for avoiding articles with small content.

Required range: x >= 0

Example:

300

word_count_max

integer

The maximum number of words an article can contain. To be used for avoiding articles with large content.

Required range: x >= 0

Example:

1000

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

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

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 or an array of strings. 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

iptc_tags

Filters articles based on International Press Telecommunications Council (IPTC) media topic tags. To specify multiple IPTC tags, use a comma-separated string or an array of strings.

Note: The iptc_tags parameter is only available in the v3_nlp_iptc_tags subscription plan.

To learn more, see IPTC Media Topic NewsCodes.

Example:

"20000199,20000209"

not_iptc_tags

Inverse of the iptc_tags parameter. Excludes articles based on International Press Telecommunications Council (IPTC) media topic tags. To specify multiple IPTC tags to exclude, use a comma-separated string or an array of strings.

Note: The not_iptc_tags parameter is only available in the v3_nlp_iptc_tags subscription plan.

To learn more, see IPTC Media Topic NewsCodes.

Example:

"20000205, 20000209"

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 aggregation count results that match the search criteria. If no matches, returns a failed aggregation response according to the defined schema.

Aggregation Response
Failed Aggregation Response

The response model for a successful Aggregation count request. 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.

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.

aggregations

Aggregation Item · object

A single item in the aggregations array containing a collection of time-based article counts.

Aggregation Item · object
Aggregation Item · object[]

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 aggregation count by interval

Authorizations

Body

Response