Metadata-Version: 2.1
Name: fmpquote
Version: 0.2.1.post1
Summary: FMP Ultimate API 中文接口文档（附开箱即用 SDK）
Home-page: https://fmpquote.com/
Author: aborte
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/)

---

## 一、 安装与快速上手

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

包内已预置公共测试 Key（以及备用测试 Key `RcTN8ECyEECLFEXK`），安装后无需配置即可直接调通跨市场示范标的：
- **美股**：`AAPL`、`NVDA`、`TSLA`、`MSFT`、`AMZN`、`META`、`GOOGL`、`AMD`、`AVGO`
- **港股与 A 股**：`00700.HK` / `0700.HK`、`600519.SS`、`300750.SZ`
- **ETF、指数、外汇、加密与商品**：`SPY`、`^GSPC`、`EURUSD`、`BTCUSD`、`GCUSD` 及 `/stable/treasury-rates`。

---

## 二、 SDK 核心方法参考

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

# 优先级：显式传入 api_key > 环境变量 FMP_API_KEY > 内置默认测试 Key
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` |

---

## 三、 异常处理

当 API 返回非 200 状态码（如 403 权限限制或 429 频率超限）时，SDK 会抛出 `FMPAPIError(status_code, message, endpoint)`。查询全市场标的或了解完整接口说明请访问 [FMP 中文接口文档站](https://fmpquote.com/)。
