Skip to main content

Documentation Index

Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Python SDK provides access to the News API 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 than 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)

​
Resources