Search articles by author
Searches for articles by author. You can filter results by language, country, source, and more.
Authorizations
Body
The name of the author to search for. This parameter returns exact matches only.
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"]
Predefined top 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.
Examples:
"top 100 US"
"top 33 AT"
"top 5 GB"
Multiple countries can be specified with custom numbers as a comma-separated string or an array of strings.
Examples:
"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"]
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"]
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.
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.
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.
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.
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:
1 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
.
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
,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
.
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
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 list for each article.
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
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.
The lowest boundary of the rank of a news website to filter by.
Range: 1
to 999999
, where a lower rank indicates a more popular source.
If you set this to 100
, the API includes sources ranked 100 or higher.
1 < x < 999999
The highest boundary of the rank of a news website to filter by.
Range: 1
to 999999
, where a lower rank indicates a more popular source.
If you set this to 100
, the API includes sources ranked 100 or lower.
1 < x < 999999
If true, only returns articles that were posted on the home page of a given news domain.
If true, returns only opinion pieces. If false, excludes opinion-based articles and returns news only.
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.
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"]
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.
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.
The minimum number of words an article must contain. To be used for avoiding articles with small content.
x > 0
The maximum number of words an article can contain. To be used for avoiding articles with large content.
x > 0
The page number to scroll through the results. This parameter is used to paginate: scroll through results because one API response cannot return more than 1000 articles.
x > 1
The number of articles to return per page.
Range: 1
to 1000
.
1 < x < 1000
If true, includes an NLP layer with each article in the response. This layer provides enhanced information such as theme classification, article summary, sentiment analysis, tags, and named entity recognition.
The NLP layer includes:
- Theme: General topic of the article.
- Summary: A concise overview of the article content.
- Sentiment: Separate scores for title and content (range: -1 to 1).
- Named entities: Identified persons (PER), organizations (ORG), locations (LOC), and miscellaneous entities (MISC).
- IPTC tags: Standardized news category tags.
- IAB tags: Content categories for digital advertising.
Note: The include_nlp_data
parameter is only available if NLP is included in your subscription plan.
To learn more, see NLP features.
If true, filters the results to include only articles with an NLP layer. This allows you to focus on articles that have been processed with advanced NLP techniques.
Note: The has_nlp
parameter is only available if NLP is included in your subscription plan.
To learn more, see NLP features.
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
.
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.
The name of person, organization, location, product or other named entity to search for. To specify multiple names use a comma-separated string.
Example: "Tesla, Amazon"
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
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
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
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
Filters articles based on IPTC (International Press Telecommunications Council) 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 if tags are included in your subscription plan.
To learn more, see IPTC Media Topic NewsCodes.
Inverse of the iptc_tags
parameter. Excludes articles based on IPTC (International Press Telecommunications Council) 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 if tags are included in your subscription plan.
To learn more, see IPTC Media Topic NewsCodes.
Filters articles based on IAB (Interactive Advertising Bureau) content categories. These tags provide a standardized taxonomy for digital advertising content categorization. To specify multiple IAB categories, use a comma-separated string or an array of strings.
Examples:
"Business, Events"
["Business", "Events"]
Note: The iab_tags
parameter is only available if tags are included in your subscription plan.
To learn more, see the IAB Content taxonomy.
Inverse of the iab_tags
parameter. Excludes articles based on IAB (Interactive Advertising Bureau) content categories.
These tags provide a standardized taxonomy for digital advertising content categorization.
To specify multiple IAB categories to exclude, use a comma-separated string or an array of strings.
Examples:
"Agriculture, Metals"
["Agriculture", "Metals"]
Note: The not_iab_tags
parameter is only available if tags are included in your subscription plan.
To learn more, see the IAB Content taxonomy.
Filters articles based on custom taxonomy tags specific to your organization. Each taxonomy is a custom-built classification system tailored to your specific needs and is accessible only with your API key.
To specify taxonomy and its tags, use the following pattern:
"custom_tags.taxonomy": "Tag1,Tag2,Tag3"
,
where taxonomy
is your taxonomy name and Tag1,Tag2,Tag3
are specific tags.
For multiple tags, use a comma-separated string or an array of strings.
Examples:
"custom_tags.my_taxonomy": "Tag1,Tag2,Tag3"
"custom_tags.my_taxonomy": ["Tag1", "Tag2", "Tag3"]
To learn more, see the Custom tags.
Response
The response model for a successful Authors
search request.
Response field behavior:
- Required fields are guaranteed to be present and non-null.
- Optional fields may be
null
/undefined
if the data couldn't be extracted during processing. - To access article properties in the
articles
response array, use array index notation. For example,articles[n].title
, wheren
is the zero-based index of the article object (0, 1, 2, etc.). - The
nlp
property within the article objectarticles[n].nlp
is only available with NLP-enabled subscription plans.
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.
A list of articles matching the search criteria.
The user input parameters for the search.
Was this page helpful?