Skip to content

reference.md

Latest commit

 

History

History
5221 lines (3397 loc) · 78.4 KB

reference.md

File metadata and controls

5221 lines (3397 loc) · 78.4 KB
Raw

Reference

Search

client.search.get(...) -> GetSearchResponse

📝 Description

Searches for articles based on specified criteria such as keywords, language, country, source, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment
import datetime

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.search.get(
    q="\"supply chain\" AND Amazon NOT China",
    search_in="title_content, title_content_translated",
    include_translation_fields=True,
    predefined_sources="top 50 US, top 20 GB",
    source_name="sport,tech",
    sources="nytimes.com,finance.yahoo.com",
    not_sources="cnn.com,wsj.com",
    lang="en,es",
    not_lang="fr,de",
    countries="US,CA",
    not_countries="UK,FR",
    not_author_name="John Doe, Jane Doe",
    from_=datetime.datetime.fromisoformat("1 day ago"),
    to="now",
    published_date_precision="full",
    by_parse_date=True,
    ranked_only=True,
    from_rank=100,
    to_rank=100,
    is_headline=True,
    is_opinion=True,
    is_paid_content=False,
    parent_url="wsj.com/politics,wsj.com/tech",
    all_links="https://aiindex.stanford.edu/report,https://www.stateof.ai",
    all_domain_links="who.int,nih.gov",
    all_links_text="Nvidia,Tesla",
    additional_domain_info=True,
    is_news_domain=True,
    news_type="General News Outlets,Tech News and Updates",
    word_count_min=300,
    word_count_max=1000,
    page=2,
    page_size=50,
    clustering_enabled=True,
    clustering_threshold=0.7,
    include_nlp_data=True,
    has_nlp=True,
    theme="Finance,Tech",
    not_theme="Crime,Sports",
    org_entity_name="\"Apple Inc\" OR Microsoft",
    per_entity_name="\"Elon Musk\" OR \"Jeff Bezos\"",
    loc_entity_name="\"San Francisco\" OR \"New York City\"",
    misc_entity_name="AWS OR \"Microsoft Azure\"",
    title_sentiment_min=-0.5,
    title_sentiment_max=0.5,
    content_sentiment_min=-0.5,
    content_sentiment_max=0.5,
    iptc_tags="20000199,20000209",
    not_iptc_tags="20000205,20000209",
    iab_tags="Business,Events",
    not_iab_tags="Agriculture,Metals",
    custom_tags="Tag1,Tag2",
    exclude_duplicates=True,
    robots_compliant=True,
)

⚙️ Parameters

q: Q

search_in: typing.Optional[SearchIn]

include_translation_fields: typing.Optional[IncludeTranslationFields]

predefined_sources: typing.Optional[str]

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.

source_name: typing.Optional[str]

Word or phrase to search within the source names. To specify multiple values, use a comma-separated string.

Note: The search doesn't require an exact match and returns sources containing the specified terms in their names. You can use any word or phrase, like "sport" or "new york times".

For example, "sport" returns sources such as "Motorsport", "Dot Esport", and "Tuttosport".

sources: typing.Optional[str] — 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.

not_sources: typing.Optional[str] — The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string.

lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

not_lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

not_countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

not_author_name: typing.Optional[str] — The list of author names to exclude from your search. To exclude articles by specific authors, use a comma-separated string.

from: typing.Optional[From]

to: typing.Optional[To]

published_date_precision: typing.Optional[PublishedDatePrecision]

by_parse_date: typing.Optional[ByParseDate]

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[str] — The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string.

all_links: typing.Optional[str]

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

For more details, see Search by URL.

all_domain_links: typing.Optional[str]

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

For more details, see Search by URL.

all_links_text: typing.Optional[str]

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.

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

To learn more, see Search by URL.

additional_domain_info: typing.Optional[AdditionalDomainInfo]

is_news_domain: typing.Optional[IsNewsDomain]

news_domain_type: typing.Optional[NewsDomainType]

news_type: typing.Optional[str]

Filters results based on the news type. Multiple types can be specified using a comma-separated string.

For a complete list of available news types, see Enumerated parameters > News type.

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

clustering_enabled: typing.Optional[ClusteringEnabled]

clustering_variable: typing.Optional[ClusteringVariable]

clustering_threshold: typing.Optional[ClusteringThreshold]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[str]

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

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

To learn more, see IPTC Media Topic NewsCodes.

not_iptc_tags: typing.Optional[str]

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 of tag IDs.

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.

iab_tags: typing.Optional[str]

Filters articles based on Interactive Advertising Bureau (IAB) content categories. These tags provide a standardized taxonomy for digital advertising content categorization. To specify multiple IAB categories, use a comma-separated string.

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

To learn more, see the IAB Content taxonomy.

not_iab_tags: typing.Optional[str]

Inverse of the iab_tags parameter. Excludes articles based on Interactive Advertising Bureau (IAB) 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.

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

To learn more, see the IAB Content taxonomy.

custom_tags: typing.Optional[str]

Filters articles based on provided taxonomy that is tailored to your specific needs and is accessible only with your API key. To specify tags, use the following pattern:

  • custom_tags.taxonomy=Tag1,Tag2, where taxonomy is the taxonomy name and Tag1,Tag2 is a comma-separated list of tag names.

Example: custom_tags.industry="Manufacturing,Logistics"

To learn more, see the Custom tags.

exclude_duplicates: typing.Optional[ExcludeDuplicates]

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.search.post(...) -> PostSearchResponse

📝 Description

Searches for articles based on specified criteria such as keywords, language, country, source, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.search.post(
    q="\"supply chain\" AND Amazon NOT China",
    page_size=1,
)

⚙️ Parameters

q: Q

search_in: typing.Optional[SearchIn]

include_translation_fields: typing.Optional[IncludeTranslationFields]

predefined_sources: typing.Optional[PredefinedSources]

source_name: typing.Optional[SourceName]

sources: typing.Optional[Sources]

not_sources: typing.Optional[NotSources]

lang: typing.Optional[Lang]

not_lang: typing.Optional[NotLang]

countries: typing.Optional[Countries]

not_countries: typing.Optional[NotCountries]

not_author_name: typing.Optional[NotAuthorName]

from: typing.Optional[From]

to: typing.Optional[To]

published_date_precision: typing.Optional[PublishedDatePrecision]

by_parse_date: typing.Optional[ByParseDate]

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[ParentUrl]

all_links: typing.Optional[AllLinks]

all_domain_links: typing.Optional[AllDomainLinks]

all_links_text: typing.Optional[AllLinksText]

additional_domain_info: typing.Optional[AdditionalDomainInfo]

is_news_domain: typing.Optional[IsNewsDomain]

news_domain_type: typing.Optional[NewsDomainType]

news_type: typing.Optional[NewsType]

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

clustering_enabled: typing.Optional[ClusteringEnabled]

clustering_variable: typing.Optional[ClusteringVariable]

clustering_threshold: typing.Optional[ClusteringThreshold]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[IptcTags]

not_iptc_tags: typing.Optional[NotIptcTags]

iab_tags: typing.Optional[IabTags]

not_iab_tags: typing.Optional[NotIabTags]

custom_tags: typing.Optional[CustomTags]

exclude_duplicates: typing.Optional[ExcludeDuplicates]

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

LatestHeadlines

client.latest_headlines.get(...) -> GetLatestHeadlinesResponse

📝 Description

Retrieves the latest headlines for the specified time period. You can filter results by language, country, source, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.latest_headlines.get(
    when="7d",
    by_parse_date=True,
    lang="en,es",
    not_lang="fr,de",
    countries="US,CA",
    not_countries="UK,FR",
    predefined_sources="top 50 US, top 20 GB",
    sources="nytimes.com,finance.yahoo.com",
    not_sources="cnn.com,wsj.com",
    not_author_name="John Doe, Jane Doe",
    ranked_only=True,
    is_headline=True,
    is_opinion=True,
    is_paid_content=False,
    parent_url="wsj.com/politics,wsj.com/tech",
    all_links="https://aiindex.stanford.edu/report,https://www.stateof.ai",
    all_domain_links="who.int,nih.gov",
    all_links_text="Nvidia,Tesla",
    word_count_min=300,
    word_count_max=1000,
    page=2,
    page_size=50,
    clustering_enabled=True,
    clustering_threshold=0.7,
    include_translation_fields=True,
    include_nlp_data=True,
    has_nlp=True,
    theme="Finance,Tech",
    not_theme="Crime,Sports",
    org_entity_name="\"Apple Inc\" OR Microsoft",
    per_entity_name="\"Elon Musk\" OR \"Jeff Bezos\"",
    loc_entity_name="\"San Francisco\" OR \"New York City\"",
    misc_entity_name="AWS OR \"Microsoft Azure\"",
    title_sentiment_min=-0.5,
    title_sentiment_max=0.5,
    content_sentiment_min=-0.5,
    content_sentiment_max=0.5,
    iptc_tags="20000199,20000209",
    not_iptc_tags="20000205,20000209",
    iab_tags="Business,Events",
    not_iab_tags="Agriculture,Metals",
    custom_tags="Tag1,Tag2",
    robots_compliant=True,
)

⚙️ Parameters

when: typing.Optional[When]

by_parse_date: typing.Optional[ByParseDate]

sort_by: typing.Optional[SortBy]

lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

not_lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

not_countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

predefined_sources: typing.Optional[str]

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.

sources: typing.Optional[str] — 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.

not_sources: typing.Optional[str] — The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string.

not_author_name: typing.Optional[str] — The list of author names to exclude from your search. To exclude articles by specific authors, use a comma-separated string.

ranked_only: typing.Optional[RankedOnly]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[str] — The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string.

all_links: typing.Optional[str]

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

For more details, see Search by URL.

all_domain_links: typing.Optional[str]

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

For more details, see Search by URL.

all_links_text: typing.Optional[str]

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.

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

To learn more, see Search by URL.

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

clustering_enabled: typing.Optional[ClusteringEnabled]

clustering_variable: typing.Optional[ClusteringVariable]

clustering_threshold: typing.Optional[ClusteringThreshold]

include_translation_fields: typing.Optional[IncludeTranslationFields]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[str]

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

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

To learn more, see IPTC Media Topic NewsCodes.

not_iptc_tags: typing.Optional[str]

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 of tag IDs.

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.

iab_tags: typing.Optional[str]

Filters articles based on Interactive Advertising Bureau (IAB) content categories. These tags provide a standardized taxonomy for digital advertising content categorization. To specify multiple IAB categories, use a comma-separated string.

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

To learn more, see the IAB Content taxonomy.

not_iab_tags: typing.Optional[str]

Inverse of the iab_tags parameter. Excludes articles based on Interactive Advertising Bureau (IAB) 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.

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

To learn more, see the IAB Content taxonomy.

custom_tags: typing.Optional[str]

Filters articles based on provided taxonomy that is tailored to your specific needs and is accessible only with your API key. To specify tags, use the following pattern:

  • custom_tags.taxonomy=Tag1,Tag2, where taxonomy is the taxonomy name and Tag1,Tag2 is a comma-separated list of tag names.

Example: custom_tags.industry="Manufacturing,Logistics"

To learn more, see the Custom tags.

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.latest_headlines.post(...) -> PostLatestHeadlinesResponse

📝 Description

Retrieves the latest headlines for the specified time period. You can filter results by language, country, source, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.latest_headlines.post(
    when="7d",
    page_size=1,
)

⚙️ Parameters

when: typing.Optional[When]

by_parse_date: typing.Optional[ByParseDate]

lang: typing.Optional[Lang]

not_lang: typing.Optional[NotLang]

countries: typing.Optional[Countries]

not_countries: typing.Optional[NotCountries]

predefined_sources: typing.Optional[PredefinedSources]

sources: typing.Optional[Sources]

not_sources: typing.Optional[NotSources]

not_author_name: typing.Optional[NotAuthorName]

ranked_only: typing.Optional[RankedOnly]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[ParentUrl]

all_links: typing.Optional[AllLinks]

all_domain_links: typing.Optional[AllDomainLinks]

all_links_text: typing.Optional[AllLinksText]

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

clustering_enabled: typing.Optional[ClusteringEnabled]

clustering_variable: typing.Optional[ClusteringVariable]

clustering_threshold: typing.Optional[ClusteringThreshold]

include_translation_fields: typing.Optional[IncludeTranslationFields]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[IptcTags]

not_iptc_tags: typing.Optional[NotIptcTags]

iab_tags: typing.Optional[IabTags]

not_iab_tags: typing.Optional[NotIabTags]

custom_tags: typing.Optional[CustomTags]

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

BreakingNews

client.breaking_news.get(...) -> BreakingNewsResponseDto

📝 Description

Retrieves breaking news articles and sorts them based on specified criteria.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.breaking_news.get(
    ranked_only=True,
    from_rank=100,
    to_rank=100,
    page=2,
    page_size=50,
    top_n_articles=5,
    include_translation_fields=True,
    include_nlp_data=True,
    has_nlp=True,
    theme="Finance,Tech",
    not_theme="Crime,Sports",
    org_entity_name="\"Apple Inc\" OR Microsoft",
    per_entity_name="\"Elon Musk\" OR \"Jeff Bezos\"",
    loc_entity_name="\"San Francisco\" OR \"New York City\"",
    misc_entity_name="AWS OR \"Microsoft Azure\"",
    title_sentiment_min=-0.5,
    title_sentiment_max=0.5,
    content_sentiment_min=-0.5,
    content_sentiment_max=0.5,
)

⚙️ Parameters

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

top_n_articles: typing.Optional[TopNArticles]

include_translation_fields: typing.Optional[IncludeTranslationFields]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.breaking_news.post(...) -> BreakingNewsResponseDto

📝 Description

Retrieves breaking news articles and sorts them based on specified criteria.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.breaking_news.post(
    sort_by="relevancy",
    ranked_only=True,
    top_n_articles=1,
)

⚙️ Parameters

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

top_n_articles: typing.Optional[TopNArticles]

include_translation_fields: typing.Optional[IncludeTranslationFields]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Authors

client.authors.get(...) -> GetAuthorsResponse

📝 Description

Searches for articles written by a specified author. You can filter results by language, country, source, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment
import datetime

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.authors.get(
    author_name="Jane Smith",
    not_author_name="John Doe, Jane Doe",
    predefined_sources="top 50 US, top 20 GB",
    sources="nytimes.com,finance.yahoo.com",
    not_sources="cnn.com,wsj.com",
    lang="en,es",
    not_lang="fr,de",
    countries="US,CA",
    not_countries="UK,FR",
    from_=datetime.datetime.fromisoformat("1 day ago"),
    to="now",
    published_date_precision="full",
    by_parse_date=True,
    ranked_only=True,
    from_rank=100,
    to_rank=100,
    is_headline=True,
    is_opinion=True,
    is_paid_content=False,
    parent_url="wsj.com/politics,wsj.com/tech",
    all_links="https://aiindex.stanford.edu/report,https://www.stateof.ai",
    all_domain_links="who.int,nih.gov",
    all_links_text="Nvidia,Tesla",
    word_count_min=300,
    word_count_max=1000,
    page=2,
    page_size=50,
    include_translation_fields=True,
    include_nlp_data=True,
    has_nlp=True,
    theme="Finance,Tech",
    not_theme="Crime,Sports",
    ner_name="Tesla,Amazon",
    title_sentiment_min=-0.5,
    title_sentiment_max=0.5,
    content_sentiment_min=-0.5,
    content_sentiment_max=0.5,
    iptc_tags="20000199,20000209",
    not_iptc_tags="20000205,20000209",
    iab_tags="Business,Events",
    not_iab_tags="Agriculture,Metals",
    custom_tags="Tag1,Tag2",
    robots_compliant=True,
)

⚙️ Parameters

author_name: AuthorName

not_author_name: typing.Optional[str] — The list of author names to exclude from your search. To exclude articles by specific authors, use a comma-separated string.

predefined_sources: typing.Optional[str]

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.

sources: typing.Optional[str] — 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.

not_sources: typing.Optional[str] — The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string.

lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

not_lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

not_countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

from: typing.Optional[From]

to: typing.Optional[To]

published_date_precision: typing.Optional[PublishedDatePrecision]

by_parse_date: typing.Optional[ByParseDate]

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[str] — The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string.

all_links: typing.Optional[str]

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

For more details, see Search by URL.

all_domain_links: typing.Optional[str]

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

For more details, see Search by URL.

all_links_text: typing.Optional[str]

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.

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

To learn more, see Search by URL.

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

include_translation_fields: typing.Optional[IncludeTranslationFields]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

ner_name: typing.Optional[NerName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[str]

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

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

To learn more, see IPTC Media Topic NewsCodes.

not_iptc_tags: typing.Optional[str]

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 of tag IDs.

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.

iab_tags: typing.Optional[str]

Filters articles based on Interactive Advertising Bureau (IAB) content categories. These tags provide a standardized taxonomy for digital advertising content categorization. To specify multiple IAB categories, use a comma-separated string.

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

To learn more, see the IAB Content taxonomy.

not_iab_tags: typing.Optional[str]

Inverse of the iab_tags parameter. Excludes articles based on Interactive Advertising Bureau (IAB) 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.

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

To learn more, see the IAB Content taxonomy.

custom_tags: typing.Optional[str]

Filters articles based on provided taxonomy that is tailored to your specific needs and is accessible only with your API key. To specify tags, use the following pattern:

  • custom_tags.taxonomy=Tag1,Tag2, where taxonomy is the taxonomy name and Tag1,Tag2 is a comma-separated list of tag names.

Example: custom_tags.industry="Manufacturing,Logistics"

To learn more, see the Custom tags.

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.authors.post(...) -> PostAuthorsResponse

📝 Description

Searches for articles by author. You can filter results by language, country, source, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.authors.post(
    author_name="David Muir",
)

⚙️ Parameters

author_name: AuthorName

not_author_name: typing.Optional[NotAuthorName]

predefined_sources: typing.Optional[PredefinedSources]

sources: typing.Optional[Sources]

not_sources: typing.Optional[NotSources]

lang: typing.Optional[Lang]

not_lang: typing.Optional[NotLang]

countries: typing.Optional[Countries]

not_countries: typing.Optional[NotCountries]

from: typing.Optional[From]

to: typing.Optional[To]

published_date_precision: typing.Optional[PublishedDatePrecision]

by_parse_date: typing.Optional[ByParseDate]

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[ParentUrl]

all_links: typing.Optional[AllLinks]

all_domain_links: typing.Optional[AllDomainLinks]

all_links_text: typing.Optional[AllLinksText]

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

include_translation_fields: typing.Optional[IncludeTranslationFields]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

ner_name: typing.Optional[NerName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[IptcTags]

not_iptc_tags: typing.Optional[NotIptcTags]

iab_tags: typing.Optional[IabTags]

not_iab_tags: typing.Optional[NotIabTags]

custom_tags: typing.Optional[CustomTags]

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

SearchByLink

client.search_by_link.get(...) -> SearchResponseDto

📝 Description

Searches for articles based on specified links or IDs. You can filter results by date range.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment
import datetime

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.search_by_link.get(
    ids="5f8d0d55b6e45e00179c6e7e",
    links="https://nytimes.com/article1,https://bbc.com/article2",
    from_=datetime.datetime.fromisoformat("1 day ago"),
    to="now",
    page=2,
    page_size=50,
    robots_compliant=True,
)

⚙️ Parameters

ids: typing.Optional[str]

The Newscatcher article ID (corresponds to the _id field in API response) or a list of article IDs to search for. To specify multiple IDs, use a comma-separated string.

Caution: You can use either the links or the ids parameter, but not both at the same time.

links: typing.Optional[str]

The article link or list of article links to search for. To specify multiple links, use a comma-separated string.

Caution: You can use either the links or the ids parameter, but not both at the same time.

from: typing.Optional[From]

to: typing.Optional[To]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.search_by_link.post(...) -> SearchResponseDto

📝 Description

Searches for articles using their ID(s) or link(s).

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.search_by_link.post(
    links="https://www.reuters.com/business/energy/oil-prices-up-after-israeli-attacks-oversupply-caps-gains-2025-09-10/",
)

⚙️ Parameters

ids: typing.Optional[Ids]

links: typing.Optional[Links]

from: typing.Optional[From]

to: typing.Optional[To]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Sources

client.sources.get(...) -> SourcesResponseDto

📝 Description

Retrieves a list of sources based on specified criteria such as language, country, rank, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.sources.get(
    lang="en,es",
    countries="US,CA",
    predefined_sources="top 50 US, top 20 GB",
    source_name="sport,tech",
    source_url="bbc.com",
    include_additional_info=True,
    is_news_domain=True,
    news_type="General News Outlets,Tech News and Updates",
    from_rank=100,
    to_rank=100,
)

⚙️ Parameters

lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

predefined_sources: typing.Optional[str]

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.

source_name: typing.Optional[str]

Word or phrase to search within the source names. To specify multiple values, use a comma-separated string.

Note: The search doesn't require an exact match and returns sources containing the specified terms in their names. You can use any word or phrase, like "sport" or "new york times".

For example, "sport" returns sources such as "Motorsport", "Dot Esport", and "Tuttosport".

source_url: typing.Optional[str]

The domain(s) of the news publication to search for.

Caution: When specifying the source_url parameter, you can only use include_additional_info as an extra parameter.

include_additional_info: typing.Optional[IncludeAdditionalInfo]

is_news_domain: typing.Optional[IsNewsDomain]

news_domain_type: typing.Optional[NewsDomainType]

news_type: typing.Optional[str]

Filters results based on the news type. Multiple types can be specified using a comma-separated string.

For a complete list of available news types, see Enumerated parameters > News type.

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.sources.post(...) -> SourcesResponseDto

📝 Description

Retrieves the list of sources available in the database. You can filter the sources by language, country, and more.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.sources.post(
    predefined_sources="top 10 US",
)

⚙️ Parameters

lang: typing.Optional[Lang]

countries: typing.Optional[Countries]

predefined_sources: typing.Optional[PredefinedSources]

source_name: typing.Optional[SourceName]

source_url: typing.Optional[SourceUrl]

include_additional_info: typing.Optional[IncludeAdditionalInfo]

is_news_domain: typing.Optional[IsNewsDomain]

news_domain_type: typing.Optional[NewsDomainType]

news_type: typing.Optional[NewsType]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

AggregationCount

client.aggregation_count.get(...) -> GetAggregationCountResponse

📝 Description

Retrieves the count of articles aggregated by day or hour based on various search criteria, such as keyword, language, country, and source.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment
import datetime

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.aggregation_count.get(
    q="\"supply chain\" AND Amazon NOT China",
    search_in="title_content, title_content_translated",
    predefined_sources="top 50 US, top 20 GB",
    sources="nytimes.com,finance.yahoo.com",
    not_sources="cnn.com,wsj.com",
    lang="en,es",
    not_lang="fr,de",
    countries="US,CA",
    not_countries="UK,FR",
    not_author_name="John Doe, Jane Doe",
    from_=datetime.datetime.fromisoformat("1 day ago"),
    to="now",
    published_date_precision="full",
    by_parse_date=True,
    ranked_only=True,
    from_rank=100,
    to_rank=100,
    is_headline=True,
    is_opinion=True,
    is_paid_content=False,
    parent_url="wsj.com/politics,wsj.com/tech",
    all_links="https://aiindex.stanford.edu/report,https://www.stateof.ai",
    all_domain_links="who.int,nih.gov",
    all_links_text="Nvidia,Tesla",
    word_count_min=300,
    word_count_max=1000,
    page=2,
    page_size=50,
    include_nlp_data=True,
    has_nlp=True,
    theme="Finance,Tech",
    not_theme="Crime,Sports",
    org_entity_name="\"Apple Inc\" OR Microsoft",
    per_entity_name="\"Elon Musk\" OR \"Jeff Bezos\"",
    loc_entity_name="\"San Francisco\" OR \"New York City\"",
    misc_entity_name="AWS OR \"Microsoft Azure\"",
    title_sentiment_min=-0.5,
    title_sentiment_max=0.5,
    content_sentiment_min=-0.5,
    content_sentiment_max=0.5,
    iptc_tags="20000199,20000209",
    not_iptc_tags="20000205,20000209",
    robots_compliant=True,
)

⚙️ Parameters

q: Q

aggregation_by: typing.Optional[AggregationBy]

search_in: typing.Optional[SearchIn]

predefined_sources: typing.Optional[str]

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.

sources: typing.Optional[str] — 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.

not_sources: typing.Optional[str] — The news sources to exclude from the search. To exclude multiple sources, use a comma-separated string.

lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

not_lang: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Language.

countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

not_countries: typing.Optional[str]

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.

To learn more, see Enumerated parameters > Country.

not_author_name: typing.Optional[str] — The list of author names to exclude from your search. To exclude articles by specific authors, use a comma-separated string.

from: typing.Optional[From]

to: typing.Optional[To]

published_date_precision: typing.Optional[PublishedDatePrecision]

by_parse_date: typing.Optional[ByParseDate]

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[str] — The categorical URL(s) to filter your search. To filter your search by multiple categorical URLs, use a comma-separated string.

all_links: typing.Optional[str]

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

For more details, see Search by URL.

all_domain_links: typing.Optional[str]

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

For more details, see Search by URL.

all_links_text: typing.Optional[str]

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.

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

To learn more, see Search by URL.

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[str]

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

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

To learn more, see IPTC Media Topic NewsCodes.

not_iptc_tags: typing.Optional[str]

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 of tag IDs.

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.

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.aggregation_count.post(...) -> PostAggregationCountResponse

📝 Description

Retrieves the count of articles aggregated by day or hour based on various search criteria, such as keyword, language, country, and source.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.aggregation_count.post(
    q="\"supply chain\" AND Amazon NOT China",
    aggregation_by="day",
)

⚙️ Parameters

q: Q

aggregation_by: typing.Optional[AggregationBy]

search_in: typing.Optional[SearchIn]

predefined_sources: typing.Optional[PredefinedSources]

sources: typing.Optional[Sources]

not_sources: typing.Optional[NotSources]

lang: typing.Optional[Lang]

not_lang: typing.Optional[NotLang]

countries: typing.Optional[Countries]

not_countries: typing.Optional[NotCountries]

not_author_name: typing.Optional[NotAuthorName]

from: typing.Optional[From]

to: typing.Optional[To]

published_date_precision: typing.Optional[PublishedDatePrecision]

by_parse_date: typing.Optional[ByParseDate]

sort_by: typing.Optional[SortBy]

ranked_only: typing.Optional[RankedOnly]

from_rank: typing.Optional[FromRank]

to_rank: typing.Optional[ToRank]

is_headline: typing.Optional[IsHeadline]

is_opinion: typing.Optional[IsOpinion]

is_paid_content: typing.Optional[IsPaidContent]

parent_url: typing.Optional[ParentUrl]

all_links: typing.Optional[AllLinks]

all_domain_links: typing.Optional[AllDomainLinks]

all_links_text: typing.Optional[AllLinksText]

word_count_min: typing.Optional[WordCountMin]

word_count_max: typing.Optional[WordCountMax]

page: typing.Optional[Page]

page_size: typing.Optional[PageSize]

include_nlp_data: typing.Optional[IncludeNlpData]

has_nlp: typing.Optional[HasNlp]

theme: typing.Optional[Theme]

not_theme: typing.Optional[NotTheme]

org_entity_name: typing.Optional[OrgEntityName]

per_entity_name: typing.Optional[PerEntityName]

loc_entity_name: typing.Optional[LocEntityName]

misc_entity_name: typing.Optional[MiscEntityName]

title_sentiment_min: typing.Optional[TitleSentimentMin]

title_sentiment_max: typing.Optional[TitleSentimentMax]

content_sentiment_min: typing.Optional[ContentSentimentMin]

content_sentiment_max: typing.Optional[ContentSentimentMax]

iptc_tags: typing.Optional[IptcTags]

not_iptc_tags: typing.Optional[NotIptcTags]

robots_compliant: typing.Optional[RobotsCompliant]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Subscription

client.subscription.get() -> SubscriptionResponseDto

📝 Description

Retrieves information about your subscription plan.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.subscription.get()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscription.post() -> SubscriptionResponseDto

📝 Description

Retrieves information about your subscription plan.

🔌 Usage

from newscatcher import NewscatcherApi
from newscatcher.environment import NewscatcherApiEnvironment

client = NewscatcherApi(
    api_key="<value>",
    environment=NewscatcherApiEnvironment.DEFAULT,
)

client.subscription.post()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.