Metadata-Version: 2.1
Name: fmpquote
Version: 0.2.1
Summary: FMP Ultimate API 中文接口文档（附开箱即用 SDK）
Home-page: https://fmpquote.com/
Author: FMP数据源中文站技术团队
License: MIT
Keywords: FMP,Financial Modeling Prep,FMP Ultimate API,FMP中文文档,美股API,量化金融,10-K,13F,fmpquote
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
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
Classifier: Topic :: Office/Business :: Financial :: Investment
Project-URL: Homepage, https://fmpquote.com/
Project-URL: Documentation, https://fmpquote.com/apis/
Project-URL: Quickstart & Free Key, https://fmpquote.com/quick-start/
Project-URL: Financial Formulas, https://fmpquote.com/formulas/
Project-URL: Quant Blog & Tutorials, https://fmpquote.com/blog/
Project-URL: FAQ & Troubleshooting, https://fmpquote.com/faq/
Project-URL: Source Repository, https://github.com/aborte/fmpquote
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: pandas
Requires-Dist: pandas>=1.3.0; extra == 'pandas'

# FMP Ultimate API 中文接口文档（附开箱即用 SDK）

`fmpquote` 是面向中文量化与金融投研开发者的 **Financial Modeling Prep（FMP Ultimate API）轻量级 Python 客户端**，底层基于 Python 标准库实现零依赖开箱即用，并支持一键转换为 `pandas.DataFrame`。

- **中文接口文档总览（283 个接口）**：[FMP数据源中文站接口中心](https://fmpquote.com/apis/)
- **免费领取个人独享 Key**：[5分钟快速接入指南](https://fmpquote.com/quick-start/)
- **财务指标计算公式词典**：[86条财务指标公式对照表](https://fmpquote.com/formulas/)

---

## 一、 安装与内置体验 Key

```bash
pip install fmpquote
# 如需使用 as_df=True 直接返回 pandas.DataFrame：
pip install "fmpquote[pandas]"
```

包内已预置 **2 把公用 FMP Ultimate 体验 Key**，安装后无需注册即可直接调通跨市场示范标的（`AAPL`、`NVDA`、`TSLA`、`MSFT`、`00700.HK`、`600519.SS`、`SPY`、`BTCUSD` 等）：
- **默认体验 Key**：`c9tAmzCerpHeYA9M`（默认自动生效）
- **备用体验 Key**：`RcTN8ECyEECLFEXK`（如遇默认 Key 公共额度用满，可通过 `FMPClient(api_key="RcTN8ECyEECLFEXK")` 传入）

---

## 二、 SDK 核心方法参考

```python
from fmpquote import FMPClient, format_cik, normalize_hk_symbol

# 优先级：显式传入 api_key > 环境变量 FMP_API_KEY > 内置默认体验 Key (c9tAmzCerpHeYA9M)
client = FMPClient()

# 1. 获取实时报价（支持 as_df=True 转为 DataFrame）
quote_list = client.quote("NVDA")

# 2. 获取三大财务报表（支持 period="annual" 或 "quarter"）
inc = client.income_statement("AAPL", period="annual", limit=5)
bal = client.balance_sheet("AAPL", period="annual", limit=5)
cf  = client.cash_flow("AAPL", period="annual", limit=5)

# 3. 获取 TTM 财务比率、关键估值指标与 DCF 测算
ratios  = client.ratios_ttm("MSFT")
metrics = client.key_metrics_ttm("MSFT")
dcf_res = client.dcf("AAPL")

# 4. 历史日线、财报电话会议纪要与美债收益率曲线
eod = client.eod_chart("AAPL", from_date="2025-01-01", to_date="2025-10-01")
transcript = client.earnings_transcript("NVDA", year=2025, quarter=4)
treasury = client.treasury_rates()

# 5. 通用 GET 方法：可调用 /stable/ 下全部 283 个端点
holders = client.get(
    "institutional-ownership/extract",
    params={"cik": format_cik(1067983), "year": 2025, "quarter": 2},
)
```

| 方法签名 | 对应 `/stable/` 端点 | 返回字段与文档说明 |
| :--- | :--- | :--- |
| `client.quote(symbol)` | `/stable/quote` | [股票实时报价文档](https://fmpquote.com/apis/stock-quote/) |
| `client.income_statement(symbol, period, limit)` | `/stable/income-statement` | [利润表文档](https://fmpquote.com/apis/income-statement/) |
| `client.balance_sheet(symbol, period, limit)` | `/stable/balance-sheet-statement` | `totalAssets`, `totalDebt`, `totalStockholdersEquity` |
| `client.cash_flow(symbol, period, limit)` | `/stable/cash-flow-statement` | `operatingCashFlow`, `capitalExpenditure`, `freeCashFlow` |
| `client.ratios_ttm(symbol)` | `/stable/ratios-ttm` | [TTM 财务比率文档](https://fmpquote.com/apis/financial-ratios-ttm/) |
| `client.key_metrics_ttm(symbol)` | `/stable/key-metrics-ttm` | `evToEbitdaTTM`, `roicTTM`, `freeCashFlowYieldTTM` |
| `client.dcf(symbol)` | `/stable/discounted-cash-flow` | [DCF 估值文档](https://fmpquote.com/apis/dcf-valuation/) |
| `client.eod_chart(symbol, from_date, to_date)` | `/stable/historical-price-eod/full` | `date`, `open`, `high`, `low`, `close`, `volume`, `vwap` |
| `client.earnings_transcript(symbol, year, quarter)` | `/stable/earning-call-transcript` | [电话会纪要文档](https://fmpquote.com/apis/earnings-transcript/) |
| `client.treasury_rates(from_date, to_date)` | `/stable/treasury-rates` | `date`, `month3`, `year2`, `year10`, `year30` |

---

## 三、 异常处理与专属 Key 领取

当请求触发网关限制时，SDK 会抛出 `FMPAPIError(status_code, message, endpoint)` 并原样保留网关返回的双语提示。如需解锁全美股 10,000+ 标的或提升并发配额，请访问 [FMP数据源中文站官网](https://fmpquote.com/)。
