> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Python client library for News API

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

## Installation

```bash theme={null}
pip install newscatcher-sdk
```

## Basic usage

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
# 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](/news-api/how-to/retrieve-more-than-10k-articles).

## Query validation

The SDK includes client-side query validation that helps you catch syntax errors
before making API calls:

```python theme={null}
# 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](/news-api/how-to/validate-queries-python-sdk).

## Error handling

```python theme={null}
from newscatcher.core.api_error import ApiError

try:
    client.search.post(...)
except ApiError as e:
    print(e.status_code)
    print(e.body)
```

## Resources

* [GitHub Repository](https://github.com/Newscatcher/newscatcher-python)
* [PyPI Package](https://pypi.org/project/newscatcher-sdk/)