Search articles

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.

The article fields to search in. To search in multiple fields, use a comma-separated string.

Example: "title, summary"

Available options: title, summary, content.

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.

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.

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 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 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.

The number of articles to return per page. Range: 1 to 1000.

Determines whether to group similar articles into clusters. If true, the API returns clustered results.

To learn more, see Clustering news articles.

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"]

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.

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

Examples:

• "Elon Musk, Jeff Bezos"
• ["Elon Musk", "Jeff Bezos"]

To learn more, see Search by entity.

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

Examples:

• "California, New York"
• ["California", "New York"]

To learn more, see Search by entity.

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

Examples:

• "Bitcoin, Blockchain"
• ["Bitcoin", "Blockchain"]

To learn more, see Search by entity.

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

Examples:

• "Apple, Microsoft"
• ["Apple", "Microsoft"]

To learn more, see Search by entity.

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 features.

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 features.

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 features.

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 features.

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

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

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.

An array of town entities related to the articles. Each town entity contains information about a specific town and the association methods to be used for searching.

Note: The associated_towns parameter is required for local news searches.

To learn more, see Town association methods.

Determines whether to include AI-extracted town names in the search. If true, the API searches for articles mentioning AI-extracted towns and towns specified in the associated_towns parameter.

Note: The search_in_ai_associated_town parameter is only available for the v3_local_news_ai_extraction_nlp plan. Data for AI-associated towns is only available from September 24, 2024, onwards.

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

• For an exact match, use double quotes. For example, "technology news".
• Use * to search for any keyword.
• Use + to include and - to exclude specific words or phrases. For example, +Apple, -Google.
• Use AND, OR, and NOT to refine search results. For example, technology AND (Apple OR Microsoft) NOT Google.

For more details, see Advanced querying.

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-09-24T00:00:00
• YYYY-MM-dd: 2024-09-24
• YYYY/mm/dd HH:MM:SS: 2024/09/24 00:00:00
• YYYY/mm/dd: 2024/09/24
• 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-09-25T00:00:00
• YYYY-MM-dd: 2024-09-25
• YYYY/mm/dd HH:MM:SS: 2024/09/25 00:00:00
• YYYY/mm/dd: 2024/09/25
• English phrases: 1 day ago, today, 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.