akshare-data

name	akshare-data
description	此技能用于使用 AKShare Python 库获取多市场金融数据，覆盖 A 股、港股、美股、期货、基金、ETF、可转债、期权、宏观指标、行业板块、概念板块、资金流向、涨停池、龙虎榜和实时行情。适用于用户提到 AKShare、akshare、A股实时行情、stock_zh_a_hist、stock_individual_fund_flow、stock_zt_pool_em、龙虎榜、港股、美股、期货、基金净值、ETF、可转债、宏观数据或多市场金融数据脚本的场景。

AKShare 多市场金融数据获取

使用 akshare 获取多市场金融数据。AKShare 不需要登录，直接调用函数返回 pandas DataFrame；多数 A 股接口使用中文列名，且上游数据源变化较频繁，脚本必须检查空结果和实际字段。

不适用于：高可靠生产行情源、逐笔级 tick 数据、需要强 SLA 的实时交易系统。纯 A 股历史行情或季频财务指标也可评估 baostock-data。

安装与验证

pip install akshare --upgrade
python -c "import akshare as ak; print(ak.__version__)"

遇到 JSONDecodeError、KeyError、字段缺失、返回结构变化时，先升级 AKShare，再查 references/api-reference.md 和官方文档：https://akshare.akfamily.xyz/。

工作流

复制此 checklist 追踪进度：

AKShare 进度:
- [ ] 步骤 1: 选择最窄 API 和数据源
- [ ] 步骤 2: 规范代码、市场、日期、周期和复权参数
- [ ] 步骤 3: 单标的任务优先使用个股接口
- [ ] 步骤 4: 调用 API 并检查 df.empty 和 df.columns
- [ ] 步骤 5: 按需重命名中文列并验证字段
- [ ] 步骤 6: 批量任务加入限速、重试和缓存
- [ ] 步骤 7: 运行质量检查并修正问题

步骤 1: 选择最窄 API 和数据源

根据市场和数据类型选择精确函数。函数签名、数据源变体和返回字段不确定时，加载 references/api-reference.md。

常用 API 速查：

需求	API
A 股日/周/月 K 线	stock_zh_a_hist()
A 股分钟线	stock_zh_a_hist_min_em()
A 股实时行情	stock_sh_a_spot_em() / stock_sz_a_spot_em() / stock_bj_a_spot_em() / stock_zh_a_spot_em()
个股盘口/基本信息	stock_bid_ask_em() / stock_individual_info_em()
个股/市场资金流	stock_individual_fund_flow() / stock_individual_fund_flow_rank() / stock_market_fund_flow()
行业/概念板块	stock_board_industry_* / stock_board_concept_*
涨停池/龙虎榜	stock_zt_pool_em() / stock_lhb_detail_em()
三大财务报表	stock_profit_sheet_by_report_em() / stock_balance_sheet_by_report_em() / stock_cash_flow_sheet_by_report_em()
股东与公司数据	stock_gdfx_top_10_em() / stock_gdfx_free_top_10_em() / stock_zh_a_gdhs()
港股/美股历史行情	stock_hk_hist() / stock_us_hist()
期货主力连续	futures_display_main_sina() / futures_main_sina()
ETF/基金/可转债	fund_etf_* / fund_open_fund_* / bond_zh_cov*
中国/美国宏观	macro_china_* / macro_usa_*

步骤 2: 规范代码、市场、日期、周期和复权参数

使用 AKShare 的代码约定，不要混用 BaoStock 格式：

项目	AKShare 约定
A 股代码	6 位纯数字，例如 "000001"
资金流等市场参数	通常沪市/科创板用 "sh"，深市/创业板用 "sz"
A 股日线日期	YYYYMMDD，例如 "20240101"
分钟线日期	YYYY-MM-DD HH:MM:SS
复权参数	通常 "" 不复权，"qfq" 前复权，"hfq" 后复权
返回列名	多数为中文，如 日期、收盘、成交量、换手率

与 BaoStock 的关键差异：

特性	AKShare	BaoStock
登录	不需要	需要 login() / logout()
A 股代码	"000001"	"sz.000001"
日线日期	"20240101"	"2024-01-01"
列名	中文为主	英文为主
数值类型	多数已转换	多数为字符串
市场覆盖	A 股、港股、美股、期货、基金、宏观等	主要 A 股

步骤 3: 单标的任务优先使用个股接口

单只股票任务使用个股接口，例如 stock_zh_a_hist()、stock_individual_info_em()、stock_bid_ask_em()、stock_individual_fund_flow()。只有真正需要全市场筛选、排名或扫描时才使用全市场接口。

全市场接口通常更慢、更容易被上游限流，返回列也更容易变化。

步骤 4: 调用 API 并检查 df.empty 和 df.columns

import akshare as ak
import pandas as pd


df = ak.stock_zh_a_hist(
    symbol="000001",
    period="daily",
    start_date="20240101",
    end_date="20241231",
    adjust="qfq",
)

if df.empty:
    raise ValueError("AKShare returned no rows; check symbol, date format, period, adjustment, and source coverage")

print(df.columns.tolist())

步骤 5: 按需重命名中文列并验证字段

只重命名任务需要的字段，并保留原始 DataFrame 便于排查数据源差异。

df = df.rename(columns={
    "日期": "date",
    "股票代码": "symbol",
    "开盘": "open",
    "收盘": "close",
    "最高": "high",
    "最低": "low",
    "成交量": "volume",
    "成交额": "amount",
    "涨跌幅": "pct_chg",
    "换手率": "turnover",
})

required = {"date", "close", "volume"}
missing = required - set(df.columns)
if missing:
    raise KeyError(f"Missing expected AKShare columns: {sorted(missing)}")

df["date"] = pd.to_datetime(df["date"])

步骤 6: 批量任务加入限速、重试和缓存

加载 references/common-recipes.md 获取批量下载、行业筛选、指数成分、分钟线、资金流、涨停池、龙虎榜、财务报表、股东数据、期货、基金、ETF、宏观仪表板、可转债、增量存储和技术指标模板。

批量调用时加入 time.sleep()、异常重试、中间结果落盘和跳过日志。遇到上游限流、空响应或畸形 JSON 时，增加等待时间或切换同类数据源后缀。

步骤 7: 运行质量检查并修正问题

运行下方质量 checklist。若检查失败，回到对应步骤修正后重新验证。

数据源后缀选择

AKShare 常见函数后缀反映不同上游来源。字段、覆盖范围和稳定性不能视为完全一致。

后缀	常见来源	使用建议
_em	东方财富	A 股行情、资金流、板块数据常用，字段较全，但可能限流
_ths	同花顺	财务和个股资料的替代来源
_xq	雪球	公司概况、持仓和部分实时数据
_sina	新浪	期货、部分历史数据较常见

遇到 _em 接口失败时，优先查 references/api-reference.md 中是否有同类 _ths、_xq 或 _sina 函数。

常见陷阱

• 日线、指数、期货等接口常用 YYYYMMDD；分钟线常用 YYYY-MM-DD HH:MM:SS。
• A 股函数通常传 6 位纯数字，不传 sh. / sz. 前缀。
• 资金流向接口常需要 market="sh" 或 market="sz"。
• 中文列名必须以实际 df.columns 为准，不要假设一定存在英文列。
• 单股查询不要用 stock_zh_a_spot_em() 再筛选，优先用个股接口。
• 退市股、非交易日、未覆盖标的可能静默返回空 DataFrame。
• period="1" 的分钟线通常不支持复权，历史深度也有限。
• 期货主力连续常用新浪品种代码，例如先用 futures_display_main_sina() 查映射。
• 可转债、基金、ETF 的代码格式类似 6 位数字，但含义和市场前缀规则不同。
• AKShare 上游接口变化较快，异常排查顺序为：升级库、打印列名、查官方文档、切换数据源。

约束

• 优先选择最窄 API，不为单标的任务调用全市场接口。
• 明确设置 adjust，不要依赖默认不复权。
• 在任何分析、筛选、绘图或存储前检查 df.empty 和 df.columns。
• 下游代码依赖字段前先验证字段存在。
• 批量任务必须加入限速、重试、日志和可恢复存储。
• 将实时行情视为第三方网页数据抓取结果，不承诺交易级稳定性。

质量检查

• name 与目录名一致，frontmatter 只保留必要元数据。
• API 选择与市场和数据类型匹配。
• A 股代码使用 6 位纯数字。
• 日期格式匹配具体接口。
• 价格序列已明确设置 adjust。
• 单标的任务未滥用全市场接口。
• 调用后检查 df.empty。
• 调用后打印或验证 df.columns。
• 中文列名重命名前已确认存在。
• 批量任务包含限速、重试、日志和缓存。
• 接口异常时已考虑升级 AKShare 或切换同类数据源。

参考资料（按需加载）

• references/api-reference.md - API 签名、数据源变体、参数、返回字段和市场覆盖。
• references/common-recipes.md - 批量下载、筛选器、资金流、涨停池、龙虎榜、财务报表、股东、期货、基金、ETF、宏观、可转债、增量存储、技术指标。
• 官方文档：https://akshare.akfamily.xyz/
• GitHub Issues：https://github.com/akfamily/akshare