Skip to main content
POST
Search articles with GeoNames filtering

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
q
string

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"

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

Example:

"2024/09/24"

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

Example:

"2024/09/25"

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

Note: Search in summaries and translations is only available for NLP subscription plans.

Example:

"title_content, title_content_translated"

sort_by
enum<string>
default:date

The sorting order of the results. Possible values are:

  • relevancy: The most relevant results first.
  • date: The most recently published results first.
  • rank: Highest-ranked sources first; when clustering enabled, sorts by cluster_rank within clusters.
Available options:
relevancy,
date,
rank
Example:

"date"

geonames
object[]

Filters articles by geographic locations using structured GeoNames data. All location criteria within an object must be met (internal AND). Multiple objects are combined using the geonames_operator parameter.

For detailed information, see GeoNames filtering.

Example:
geonames_operator
enum<string>
default:AND

The operator to combine multiple geonames objects. If AND, all geonames objects must match. If OR, at least one geonames object must match.

Available options:
AND,
OR
Example:

"AND"

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

page
integer
default:1

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.

Required range: x >= 1
Example:

2

page_size
integer
default:100

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

Required range: 1 <= x <= 1000
Example:

100

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

clustering
boolean
default:false

If true, groups similar articles into clusters and returns clustered results. If false, returns individual articles without clustering.

To learn more, see Clustering news articles.

Example:

true

theme

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.

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:
content_type

Filters articles by content type, the kind of page the 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. If not set, articles of all content types are returned.

Shortcuts:

  • news: news_report, analysis, and interview.
  • all: no content type filter.

Note: Content type labels are available for articles from October 17, 2026. Later in Q4 2026, articles back to January 1, 2026, will be labelled too. Articles without a label are not returned when this filter is set. An unknown value returns a 422 error.

To learn more, see Content types.

Available options: news_report, analysis, interview, opinion, press_release, listicle, service, commerce, review, autogen, seo_spam, obituary, ugc, non_article, news, all.

Example:
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\""

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"

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

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). If false, excludes translation fields.

Example:

true

Response

A successful response containing articles that match the specified search criteria with GeoNames location data. The response may include clustering information if enabled.

The response model for the Search advanced, Latest headlines advanced, and Search by requests.

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, where n is the zero-based index of the article object (0, 1, 2, etc.).
status
string
default:ok
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.

articles
Article Result (Advanced) · object[]
user_input
object