Python SDK provides access to the News API v3 from Python applications with support for both synchronous and asynchronous operations.

​
Installation

pip install newscatcher-sdk

​
Basic usage

import datetime
from newscatcher import NewscatcherApi

client = NewscatcherApi(
    api_key="YOUR_API_KEY",
)

# Search for articles
client.search.post(
    q="renewable energy",
    predefined_sources=["top 50 US"],
    lang=["en"],
    from_=datetime.datetime.fromisoformat("2024-01-01 00:00:00+00:00"),
    to=datetime.datetime.fromisoformat("2024-06-30 00:00:00+00:00"),
    additional_domain_info=True,
    is_news_domain=True,
)

​
Async usage

import asyncio
import datetime
from newscatcher import AsyncNewscatcherApi

client = AsyncNewscatcherApi(
    api_key="YOUR_API_KEY",
)

async def main() -> None:
    await client.search.post(
        q="renewable energy",
        predefined_sources=["top 50 US"],
        lang=["en"],
        from_=datetime.datetime.fromisoformat("2024-01-01 00:00:00+00:00"),
        to=datetime.datetime.fromisoformat("2024-06-30 00:00:00+00:00"),
        additional_domain_info=True,
        is_news_domain=True,
    )

asyncio.run(main())

​
Retrieving more then 10,000 articles

The SDK provides methods to automatically retrieve more than the standard 10,000 article limit: 
# Get articles about renewable energy from the past 10 days
articles = client.get_all_articles(
    q="renewable energy",
    from_="10d",           # Last 10 days
    time_chunk_size="1d",  # Split into 1-day chunks
    max_articles=50000,    # Limit to 50,000 articles
    show_progress=True     # Show progress indicator
)
To learn more about the custom methods allowing to bypass the API limits, see How to retrieve more than 10,000 articles.

​
Query validation

The SDK includes client-side query validation that helps you catch syntax errors before making API calls: 
# Validate query syntax
is_valid, error_message = client.validate_query("machine learning")
if is_valid:
    print("Query is valid!")
else:
    print(f"Invalid query: {error_message}")
Query validation is automatically enabled in methods like get_all_articles() and will raise a ValueError for invalid queries. You can disable validation by setting validate_query=False. To learn more about query validation rules and bulk validation techniques, see Validate queries with Python SDK.

​
Error handling

from newscatcher.core.api_error import ApiError

try:
    client.search.post(...)
except ApiError as e:
    print(e.status_code)
    print(e.body)
If you use our legacy Python SDK (Konfig-based), see our Legacy SDKs documentation. We recommend migrating to this newer SDK for improved features and ongoing support.

​
Resources