Metadata-Version: 2.4
Name: openbq-eodhd
Version: 9.0.0
Summary: EODHD provider extension for OpenBB (equity/crypto/currency historical, fundamentals, corporate actions, ownership, insider trading, analyst estimates)
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: openbb-core<3,>=2.0.1
Requires-Dist: numpy>=1.25.2
Requires-Dist: pandas>=2.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.5.2
Provides-Extra: dev
Requires-Dist: ruff==0.15.22; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

<!-- Copyright 2026 SecretoftheUniverse.com LLC. Licensed under the Apache License, Version 2.0. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# openbq-eodhd

The EODHD provider extension for the OpenBB Platform, for the *Adventures in OpenBQ* stack (openbq-docker v9 vendors it under `v9/eodhd/source`). It is bdobb-dev/openbb-docker's `openbb-eodhd` (v9.6.3, fixes through v9.6.6), renamed; see NOTICE for provenance. The provider is still `eodhd` and its routes are still `obb.eodhd.*`.

An [EODHD](https://eodhd.com) (EOD Historical Data) provider extension for the
[OpenBB Platform](https://github.com/OpenBB-finance/OpenBB). Adds `provider="eodhd"`
for historical equity/ETF pricing.

All API calls go through the official
[EODHD Python library](https://github.com/EodHistoricalData/EODHD-APIs-Python-Financial-Library)
(`eodhd.APIClient`), vendored at upstream commit f98e69d — the PyPI release (1.0.32)
predates the SDK's typed errors, request timeouts, and the fundamentals
`filter` parameter.

## Coverage

| OpenBB command | EODHD endpoint | Notes |
| --- | --- | --- |
| `obb.equity.price.historical(..., provider="eodhd")` | `/api/eod`, `/api/intraday` | intervals `1d`, `1W`, `1M`, `1m`, `5m`, `1h` |
| `obb.etf.price.historical(..., provider="eodhd")` | same | same |
| `obb.crypto.price.historical(..., provider="eodhd")` | same (`.CC` symbols) | e.g. `BTC-USD`, `ETH-USD` |
| `obb.currency.price.historical(..., provider="eodhd")` | same (`.FOREX` symbols) | e.g. `EURUSD`, `EUR/USD` |
| `obb.equity.fundamental.income(..., provider="eodhd")` | `/api/fundamentals` → `Financials::Income_Statement` | `period="annual"` or `"quarter"`, `limit=N` |
| `obb.equity.fundamental.balance(..., provider="eodhd")` | `Financials::Balance_Sheet` | same |
| `obb.equity.fundamental.cash(..., provider="eodhd")` | `Financials::Cash_Flow` | same |
| `obb.equity.fundamental.dividends(..., provider="eodhd")` | `/api/div` | ex-date, amount, declaration/record/payment dates |
| `obb.equity.fundamental.historical_splits(..., provider="eodhd")` | `/api/splits` | numerator/denominator + `"n:1"` ratio |

### Historical prices (equity / ETF / crypto / forex)
- Intervals `1d/1W/1M` hit the end-of-day endpoint and carry an extra
  `adjusted_close` field (split/dividend adjusted).
- Intervals `1m/5m/1h` hit the intraday endpoint; bars are UTC and tz-aware.
  EODHD limits intraday history per request (roughly 120 days for `1m`, longer
  for `5m/1h`) — narrow the date window for fine intervals.
- Crypto uses EODHD's `BASE-QUOTE.CC` symbols (bare `BTCUSD`/`BTC/USD` are
  normalized to `BTC-USD.CC`); forex uses `EURUSD.FOREX` (`EUR/USD` normalized).

### Fundamentals
- Three statements: income, balance sheet, cash flow. `period` selects EODHD's
  `yearly` vs `quarterly`; `limit` caps the number of most-recent periods.
- Well-known line items map to OpenBB's conventional field names (`revenue`,
  `net_income`, `total_assets`, `free_cash_flow`, …); every other EODHD field is
  passed through snake_cased, so nothing is dropped.
- Fundamentals require a paid EODHD plan for most tickers (the `demo` token
  covers `AAPL.US`).

### Economic calendar
- `obb.economy.calendar(..., provider="eodhd")` rows carry `source` (publisher,
  e.g. "BLS") and `category` (release, e.g. "Producer Prices"), resolved from
  a static three-level taxonomy of EODHD's event names; unrecognized names
  resolve to `None`.
- EODHD's `/economic-events` caps every request at 1,000 rows; a range with
  more events than that is fetched in successive date windows and merged, so
  a busy three-month window returns every row instead of being cut off.

## Aggregation metadata

The provider-owned [aggregation dictionary](docs/aggregation-metadata.md)
offers versioned, conditional time-aggregation guidance for normalized EOD
price and financial-statement fields. Use
`openbq_eodhd.aggregation.get_aggregation_metadata` to inspect it.
Unknown fields require selection, and temporal rules are separate from
cross-entity aggregation. It does not change fetcher responses or
automatically aggregate data. The seven covered Data models carry each
field's hint into `widgets.json` as a per-column `aggregation` entry (see the
[transport section](docs/aggregation-metadata.md#transport-a-per-column-hint-in-widgetsjson)),
which also gives the three statements typed `columnsDefs` for their mapped
line items.
The contract also defines the [v11 data-mastering integration boundary](docs/aggregation-metadata.md#v11-data-mastering-workstream):
provider-owned rules, versioned canonical bindings, Bronze/Silver/Gold
provenance, and semantics pinned in query receipts.

## Symbols

EODHD symbols are `SYMBOL.EXCHANGE` (e.g. `AAPL.US`, `VOD.LSE`). Pass a bare
symbol and it is qualified with the `exchange` parameter (default `US`), or pass
a fully-qualified symbol to override:

```python
obb.equity.price.historical("AAPL", provider="eodhd")                 # -> AAPL.US
obb.equity.price.historical("VOD", provider="eodhd", exchange="LSE")  # -> VOD.LSE
obb.equity.price.historical("AAPL.US,MSFT.US", provider="eodhd")      # multi-symbol
```

## Credentials

One API key, read from the bare uppercase env var (no `OPENBB_` prefix):

```
EODHD_API_KEY=<your eodhd api token>
```

Get a token at https://eodhd.com. The public `demo` token works for a few
symbols (`AAPL.US`, `MCD.US`, `TSLA.US`, `VTI.US`) and is handy for testing.

## Install

```bash
pip install openbq-eodhd        # or: pip install /path/to/openbq-eodhd
python -c "import openbb; openbb.build()"   # regenerate the static package
```

## License

Apache-2.0 — see `LICENSE`.
