Metadata-Version: 2.4
Name: filingrail
Version: 0.1.0
Summary: Python client for the Filingrail SEC EDGAR REST API on RapidAPI.
Author-email: Hudson Enterprises LLC <support@hudsonenterprisesllc.com>
License: MIT
Project-URL: Homepage, https://filingrail.hudsonenterprisesllc.com
Project-URL: Documentation, https://filingrail.hudsonenterprisesllc.com/docs
Project-URL: Repository, https://github.com/hudson-enterprises/filingrail-python
Project-URL: Listing on RapidAPI, https://rapidapi.com/hudson-enterprises-llc-hudson-enterprises-llc-default/api/filingrail
Project-URL: Status page, https://status.hudsonenterprisesllc.com
Keywords: sec,edgar,xbrl,filings,financial-data,rapidapi,form-4,13f,8-k,insider-trades
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Requires-Dist: respx>=0.20; extra == "test"

# filingrail — Python client for the SEC EDGAR REST API

A thin, async-and-sync Python client for the [Filingrail API](https://rapidapi.com/hudson-enterprises-llc-hudson-enterprises-llc-default/api/filingrail) on RapidAPI. Wraps the 7 v1 endpoints, returns typed dataclasses, no Pydantic dependency.

## Install

> **Note:** PyPI publication is pending. Watch the [Filingrail RapidAPI listing](https://rapidapi.com/hudson-enterprises-llc-hudson-enterprises-llc-default/api/filingrail) — the live-on-PyPI announcement will land in the listing's About tab.

```bash
pip install filingrail  # PyPI publication pending
```

## Get an API key

Subscribe on RapidAPI: <https://rapidapi.com/hudson-enterprises-llc-hudson-enterprises-llc-default/api/filingrail>. Free tier = 50 calls/day, no card. Pro $9/mo for 5,000 calls.

## Quickstart (sync)

```python
from filingrail import FilingrailClient

with FilingrailClient(api_key="YOUR_X_RAPIDAPI_KEY") as client:
    # Resolve a ticker to its CIK
    [aapl] = client.search_companies("AAPL", limit=1)
    print(aapl.cik, aapl.name)  # 320193 Apple Inc.

    # Latest financials (balance sheet + income statement + cash flow)
    statements = client.get_financials("AAPL", limit=3)
    for s in statements:
        print(s.statement_type, s.period_end, s.line_items.get("total_assets"))

    # Recent insider trades
    trades = client.get_insider_trades("AAPL", limit=5)
    for t in trades:
        print(t.transaction_date, t.insider_name, t.shares, t.price_per_share)

    # Berkshire Hathaway's 13F holdings (CIK 1067983)
    holdings = client.get_13f_holdings(1067983, limit=10)
    for h in holdings:
        print(h.issuer_name, h.value_usd)
```

## Quickstart (async)

```python
import asyncio
from filingrail import AsyncFilingrailClient

async def main():
    async with AsyncFilingrailClient(api_key="YOUR_X_RAPIDAPI_KEY") as client:
        statements = await client.get_financials("MSFT")
        for s in statements:
            print(s.statement_type, s.period_end)

asyncio.run(main())
```

## Environment variable

Set `RAPIDAPI_KEY` (or `X_RAPIDAPI_KEY`) and `api_key` becomes optional:

```python
import os
os.environ["RAPIDAPI_KEY"] = "..."

from filingrail import FilingrailClient
client = FilingrailClient()
```

## All endpoints

| Method | Endpoint |
|---|---|
| `search_companies(q, limit)` | `/v1/search/companies` |
| `get_recent_filings(form_type, cik, limit)` | `/v1/filings/recent` |
| `get_financials(ticker_or_cik, limit)` | `/v1/companies/{id}/financials` |
| `get_financials_history(ticker_or_cik, period, limit, statement_type, line_item)` | `/v1/companies/{id}/financials/history` |
| `get_insider_trades(ticker_or_cik, since, limit)` | `/v1/companies/{id}/insider-trades` |
| `get_8k_events(ticker_or_cik, since, limit)` | `/v1/companies/{id}/8k-events` |
| `get_13f_holdings(institution_cik, quarter, limit)` | `/v1/institutions/{cik}/13f-holdings` |
| `health()` | `/health` |

## Errors

All non-2xx responses raise `FilingrailError(message, status, detail)`. The `detail` is the parsed body when available, so you can pull out RapidAPI's specific error messages.

```python
from filingrail import FilingrailClient, FilingrailError

try:
    client = FilingrailClient(api_key="wrong")
    client.search_companies("AAPL")
except FilingrailError as e:
    print(f"status={e.status} message={e}")
```

## Why this exists

You could call `httpx.get("https://filingrail.p.rapidapi.com/v1/...", headers=...)` directly. The SDK saves you:
- typed responses (autocomplete in your IDE)
- no boilerplate for the RapidAPI auth headers
- consistent error handling
- example queries that match the canonical patterns documented in the [RapidAPI listing's Docs tab](https://rapidapi.com/hudson-enterprises-llc-hudson-enterprises-llc-default/api/filingrail)

## Links

- [Filingrail homepage](https://filingrail.hudsonenterprisesllc.com)
- [API docs (RapidAPI listing → Docs tab)](https://rapidapi.com/hudson-enterprises-llc-hudson-enterprises-llc-default/api/filingrail)
- [Status page](https://status.hudsonenterprisesllc.com)
- Issue tracker / source repo: TBD (public release pending — for now, email `support@hudsonenterprisesllc.com`)

## License

MIT
