Metadata-Version: 2.4
Name: gfin
Version: 0.1.3
Summary: Lightweight Python SDK for gfin: hosted Google Finance quotes, prices, financials, market data, news, and research.
Project-URL: Homepage, https://gfin.dev
Project-URL: API, https://api.gfin.dev/v1/openapi.json
Project-URL: Documentation, https://docs.gfin.dev
Project-URL: Source, https://github.com/bluefin-ai/fin-services/tree/main/gfin
Project-URL: Rate Limits, https://docs.gfin.dev/rate-limits
Project-URL: API Reference, https://docs.gfin.dev/api-reference
Project-URL: LLM Summary, https://docs.gfin.dev/llms.txt
Author-email: gfin <sam@gfin.dev>
License: MIT
Keywords: finance,google-finance,market-data,stocks
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: certifi>=2024.2.2
Description-Content-Type: text/markdown

# gfin

Lightweight Python SDK for gfin, a hosted Google Finance data API for builders.

gfin gives you access to Google Finance-style market data without maintaining
browser automation or private RPC plumbing: symbol search, quotes, historical
prices, financials, earnings, related assets, sentiment, market summaries,
news, realtime snapshots, watchlists, and natural-language research through
product-native namespaces. Use it for dashboards, agents, notebooks, research
tools, watchlists, prototyping, and app backends.

This SDK is intentionally straightforward: plain `dict` responses, typed
errors, automatic retries, and a symbol-scoped ticker workbench.

Docs: https://docs.gfin.dev/python-sdk

```bash
pip install gfin
```

## Quick Use

```python
import gfin

client = gfin.Client()
apple = client.ticker("AAPL")

quote = apple.quote(exchange="NASDAQ")
history = apple.history(exchange="NASDAQ")
answer = client.research.ask("Why is AAPL moving today?")

print(quote["data"], history["data"], answer["data"])
```

## Common Calls

```python
client.symbols.search("apple")
client.quotes.get("AAPL", exchange="NASDAQ")
client.prices.history("AAPL", exchange="NASDAQ")
client.financials.get("AAPL")
client.earnings.get("AAPL")
client.market.movers()
client.news.latest(limit=10)
client.realtime.quotes(entity_ids=["/m/0cqyw"])
client.watchlists.get()
```

The client is organized around gfin product areas: `symbols`, `quotes`,
`prices`, `financials`, `earnings`, `related`, `sentiment`, `market`, `news`,
`research`, `realtime`, `watchlists`, and `management`. Use
`client.ticker("AAPL")` for symbol-scoped quote, details, profile, history,
financials, earnings, related-asset, and sentiment calls.

## Runtime Support

Configuration can come from constructor options or environment variables:

| Option | Environment | Purpose |
| --- | --- | --- |
| `base_url` | `GFIN_BASE_URL` | Override `https://api.gfin.dev`; must be `http` or `https` |
| `contact` | `GFIN_CONTACT` | Send optional support metadata |
| `api_key` | `GFIN_API_KEY` | Send email-verified API credentials |
| `management_token` | `GFIN_MANAGEMENT_TOKEN` | Manage API keys after email verification |

`api_key` is sent as `Authorization: Bearer <key>` by default. Pass
`api_key_header="x-gfin-key"` to use `X-Gfin-Key` instead.

The SDK retries transient `429`, `502`, `503`, and `504` responses by default.
Use `max_retries`, `retry_statuses`, `backoff_factor`, `max_backoff`, and
`backoff_jitter` when you need tighter control, or set `max_retries=0`.

Keep API keys on a server when you do not control the runtime.

## Errors

HTTP errors raise `GfinError`. HTTP 429 raises `GfinRateLimitError`; HTTP 503
raises `GfinServiceBusyError` after retry exhaustion. Error objects include
`retry_after`, `status`, and request IDs when provided.
