Authorizations
Body
Request body for aggregation counts based on specified criteria such as keyword, language, country, source, and more.
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.
"\"supply chain\" AND Amazon NOT China"
The aggregation interval for the results.
day
, hour
, month
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
"title_content, title_content_translated"
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.
Examples:
"top 100 US"
"top 33 AT"
"top 50 US, top 20 GB"
["top 50 US", "top 20 GB"]
["top 50 US", "top 20 GB"]
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.
Examples:
"nytimes.com, theguardian.com"
["nytimes.com", "theguardian.com"]
["nytimes.com", "theguardian.com"]
The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string or an array of strings.
Examples:
"cnn.com, wsj.com"
["cnn.com", "wsj.com"]
["cnn.com", "wsj.com"]
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.
Examples:
"en,es"
["en", "es"]
To learn more, see Enumerated parameters > Language.
["en", "es"]
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.
Examples:
"fr,de"
["fr", "de"]
To learn more, see Enumerated parameters > Language.
["fr", "de"]
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.
Examples:
"US,CA"
["US", "CA"]
To learn more, see Enumerated parameters > Country.
["US", "CA"]
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.
Examples:
"UK,FR"
["UK", "FR"]
To learn more, see Enumerated parameters > Country.
["UK", "FR"]
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.
Examples:
"John Doe, Jane Doe"
["John Doe", "Jane Doe"]
["John Doe", "Jane Doe"]
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
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
.
"2024-07-01T00:00:00.000Z"
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
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
.
"2024-01-01T00:00:00.000Z"
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.
full
, timezone unknown
, date
"full"
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.
true
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.
relevancy
, date
, rank
"date"
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.
true
The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.
1 <= x <= 999999
100
The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.
1 <= x <= 999999
100
If true, only returns articles that were posted on the home page of a given news domain.
true
If true, returns only opinion pieces. If false, excludes opinion-based articles and returns news only.
true
If false, returns only articles that have publicly available complete content. Some publishers partially block content, so this setting ensures that only full articles are retrieved.
false
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.
Examples:
"wsj.com/politics,wsj.com/tech"
["wsj.com/politics", "wsj.com/tech"]
["wsj.com/politics", "wsj.com/tech"]
The complete URL(s) mentioned in the article. For multiple URLs, use a comma-separated string or an array of strings.
Examples:
"https://aiindex.stanford.edu/report/, https://www.stateof.ai/"
["https://aiindex.stanford.edu/report/", "https://www.stateof.ai/"]
For more details, see Search by URL.
{
"string-input": {
"summary": "Comma-separated string",
"value": "https://aiindex.stanford.edu/report/, https://www.stateof.ai/"
},
"array-input": {
"summary": "Array of strings",
"value": [
"https://aiindex.stanford.edu/report/",
"https://www.stateof.ai/"
]
}
}
The domain(s) mentioned in the article. For multiple domains, use a comma-separated string or an array of strings.
Examples:
"who.int, nih.gov"
["who.int", "nih.gov"]
For more details, see Search by URL.
{
"string-input": {
"summary": "Comma-separated string",
"value": "who.int, nih.gov"
},
"array-input": {
"summary": "Array of strings",
"value": ["who.int", "nih.gov"]
}
}
The minimum number of words an article must contain. To be used for avoiding articles with small content.
x >= 0
300
The maximum number of words an article can contain. To be used for avoiding articles with large content.
x >= 0
1000
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.
x >= 1
2
The number of articles to return per page.
1 <= x <= 1000
50
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.
To learn more, see NLP features.
true
If true, filters results to include only articles that have NLP data.
To learn more, see NLP features.
true
Filters articles based on their general topic, as determined by NLP analysis. To select multiple themes, use a comma-separated string or an array of strings.
Examples:
"Finance, Tech"
["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
.
["Business", "Finance"]
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 or an array of strings.
Examples:
"Crime, Tech"
["Crime", "Tech"]
Note: The not_theme
parameter is only available if NLP is included in your subscription plan.
To learn more, see NLP features.
["Crime"]
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.
"\"Apple Inc\" OR Microsoft"
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.
"\"Elon Musk\" OR \"Jeff Bezos\""
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.
"\"San Francisco\" OR \"New York City\""
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.
"AWS OR \"Microsoft Azure\""
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.
-1 <= x <= 1
-0.5
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.
-1 <= x <= 1
0.5
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.
-1 <= x <= 1
-0.5
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.
-1 <= x <= 1
0.5
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.
Examples:
"20000199, 20000209"
["20000199", "20000209"]
Note: The iptc_tags
parameter is only available in the v3_nlp_iptc_tags
subscription plan.
To learn more, see IPTC Media Topic NewsCodes.
["20000199", "20000209"]
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.
Examples:
"20000205, 20000209"
["20000205", "20000209"]
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.
["20000205", "20000209"]
If true, returns only articles/sources that comply with the publisher's robots.txt rules. If false, returns only articles/sources that do not comply with robots.txt rules. If omitted, returns all articles/sources regardless of compliance status.
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.
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
orundefined
if the data point is not presented or couldn't be extracted during processing.
The base response model containing common fields for search operations.
The status of the response.
The total number of articles matching the search criteria.
The current page number of the results.
The total number of pages available for the given search criteria.
The number of articles per page.
The aggregation results. Can be either a dictionary or a list of dictionaries. A single item in the aggregations array containing a collection of time-based article counts.
The user input parameters for the request.