Metadata-Version: 2.4
Name: currentsapi
Version: 0.1.3
Summary: Official Python client for the Currents API
Home-page: https://github.com/currentslab/currentsapi-python
Author: Currents Dev
Author-email: ray@currentsapi.services
License: MIT
Keywords: currentsapi,news,wrapper,currents,api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: requests>=2.25.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# currentsapi-python

The official Python SDK for the [Currents API](https://currentsapi.services/en/docs/).

## Installation

Install the package from PyPI. The distribution name is `currentsapi` (this
repository is `currentsapi-python`, and the Python import name is also
`currentsapi`):

```bash
pip install currentsapi
```

Python 3.8+ is supported.

## Usage

Import the client and initialize it with your API key:

```python
from currentsapi import CurrentsAPI

api = CurrentsAPI(api_key="YOUR_API_KEY")
```

## Endpoints

### Latest News

Retrieve the latest news headlines. Optionally filter by language:

```python
api.latest_news()
api.latest_news(language="en")
```

### Search

Search news articles with optional filters:

```python
api.search(keywords="OpenAI", language="en")
api.search(country="US", category="technology", start_date="2024-01-01", end_date="2024-12-31")
```

Supported parameters:

- `keywords` – search keywords
- `language` – article language code
- `country` – country code
- `category` – news category
- `start_date` – start date (`YYYY-MM-DD` or `datetime` object)
- `end_date` – end date (`YYYY-MM-DD` or `datetime` object)

### Available Resources

```python
api.available_languages()
api.available_regions()
api.available_category()
```

## Examples

- [Generate a source-linked news briefing](examples/source_linked_briefing/README.md) from a live Search API response or a deterministic offline fixture.
- [Build a company news monitor](examples/company_news_monitor/README.md) with
  a JSON watchlist, bounded search window, local state, and deterministic fixture.

## Authentication

All requests are authenticated using an `Authorization` header. Pass your API key when instantiating the client:

```python
api = CurrentsAPI(api_key="YOUR_API_KEY")
```

Get your API key at [https://currentsapi.services/en/register](https://currentsapi.services/en/register).

## License

MIT License

## Error handling

Any non-200 API response raises `CurrentsAPIError`, which exposes the parsed
response body:

```python
from currentsapi.client import CurrentsAPIError

try:
    api.latest_news()
except CurrentsAPIError as exc:
    print(exc.status, exc.code, exc.message)
```
