批量获取证券代码
一次性拿到某国、某行业或某类别的全部代码，作为后续分析的上游环节。相比手工维护代码清单，这条路更省事，也更容易复现。
FinanceDatabase / 三系 API
FinanceDatabase 架构：show / select / search 三系 API 体系
FinanceDatabase 的 API 围绕三件事展开：show 系列展示某类证券、select 系列按条件筛选、search 系列按名称搜索。三者都返回 pandas DataFrame，理解这三系 API 就能读懂绝大多数查询脚本。
show_*展示证券列表
select_*按条件筛选
search_products按名称搜索
API Overview
三系 API 对照
FinanceDatabase 的 API 划分与各自职责，以及每一系在什么情况下会被用到。
| 系列 | 职责 | 典型函数 | 返回什么 | 适用场景 | 注意点 |
|---|---|---|---|---|---|
show_* | 展示某类证券的完整列表 | show_equities() / show_etfs() / show_funds() | 该类证券的 DataFrame（代码与元数据） | 想知道「这一类证券到底有哪些」 | 属于全量拉取，类别越大返回越大，不适合反复调用 |
select_* | 按维度筛选出子集 | select_equities(country=, sector=, industry=, market_cap=) | 符合条件的那部分证券 | 已经明确要哪个国家、行业或市值区间 | 参数取值要与库内口径一致，写错值可能得到空表 |
search_products | 按名称模糊搜索 | search_products("Apple") | 匹配到的证券记录 | 只记得名字、不记得证券代码 | 模糊匹配可能一次命中多条，需要人工确认哪一个才是目标 |
| show + 本地过滤 | 全量取回后用 pandas 再筛 | show_equities() 之后自行 df[...] | 按自定义条件筛出的结果 | 筛选条件在 select_* 里没有对应参数 | 全量数据占内存，条件复杂时不如直接用 select_* |
| search + database 限定 | 在指定类别内搜索 | search_products(database="Equities", query="Apple") | 限定类别后的匹配结果 | 同名产品跨类别（股票与 ETF 同名等）需要先缩小范围 | 不限定 database 时会跨类别返回，容易混入非目标资产 |
| 三系组合 | 先筛后搜、逐步收敛 | select_* → search_products | 多轮收敛后的候选清单 | 研究初期需要反复缩小范围 | 每一轮都是一次库内查询，上游不可达时表现与「查不到」相似，需要区分 |
说明：三系查询都返回 pandas DataFrame，可继续做过滤、排序、导出。列名以实际返回为准，官方 README 给出的是函数与用法，字段清单请以自己机器上跑出的结果和官方文档为准。
show 系列
show 系列：一次性拿到某类证券全量
show 系列用于一次性获取某类证券的完整列表，是按类别建立清单的入口。
| 函数 | 拿到什么 | 典型用途 | 注意点 |
|---|---|---|---|
show_equities() | 股票清单与元数据 | 建立股票池、做全市场范围的清单整理 | 条目量居前，建议取一次后本地缓存，而不是每次分析都重拉 |
show_etfs() | ETF 清单 | 资产配置前先整理可用的 ETF 代码 | 本库定位是代码与元数据，ETF 的费率、持仓等需另找来源 |
show_funds() | 基金清单 | 基金代码整理与分类 | 净值序列属于行情类数据，不在本库范围内 |
show_indices() | 指数清单 | 找指数代码，用于基准对照 | 指数成分明细是否提供以官方 README 为准，使用前先确认 |
show_currencies() | 货币 / 外汇清单 | 币种代码整理 | 汇率时间序列需要另接行情源 |
show_cryptocurrencies() | 加密货币清单 | 币种代码整理 | 不同交易所的交易对命名口径不一，跨交易所对照时需二次核对 |
show_moneymarkets() | 货币市场工具清单 | 现金管理类工具的代码整理 | 利率、收益率等数据不在本库范围内 |
先看形状与列名
df = fd.show_equities(); df.shape; df.columns—— 先确认拿到的是 DataFrame、以及有哪几列。预期：打印出 (行数, 列数) 与列名清单，列名以实际返回与官方 README 为准。抽查几行内容
df.head()—— 看名称、代码、国家、行业等字段的实际取值风格。预期：能看到若干行证券记录；若某列整列缺失，先回官方文档确认该字段来源，不要直接当成「库坏了」。确认这里没有行情字段
df.columns里不应期待出现开高低收、成交量这类行情列 —— FinanceDatabase 提供证券代码与元数据，不提供行情价格。预期：需要价格时另配行情源，别在这一步卡住。缓存到本地再慢慢筛
df.to_csv("equities.csv")—— 先把清单落盘。预期：本地生成 csv，后续筛选不必反复访问上游，也避免上游波动影响分析节奏。
select 系列
select 系列：按条件筛选证券
select 系列用于按维度筛选，是 FinanceDatabase 在「建证券池」这件事上的核心用法。
| 参数 | 含义 | 示例 | 适用场景 | 注意点 |
|---|---|---|---|---|
country | 按国家 / 地区筛选 | country="United States" | 只研究某一市场的股票 | 取值需与库内口径一致，中文或简写不一定被识别 |
sector | 按板块筛选 | sector="Technology" | 做板块内的横向对照 | 板块划分口径由上游数据源决定，与本地习惯分类可能不同 |
industry | 按行业筛选 | industry="Software - Infrastructure" | 需要比 sector 更细的行业粒度 | 行业名称较长且带连字符等符号，建议先从已有结果里复制取值 |
market_cap | 按市值规模筛选 | market_cap="Large Cap" | 按大盘 / 中盘 / 小盘分层研究 | 市值字段可能滞后于实时市场，分层只能当粗略口径 |
| 多参数组合 | 同时满足多个条件 | select_equities(country="United States", sector="Technology") | 「某国科技股」这类复合筛选 | 组合条件的连接语义以官方实现为准，拿不准就先单参数跑一遍再叠加 |
| 参数取值来源 | 取值写法决定能不能筛到 | 先 show_equities() 看某列的既有取值 | 不确定某个国家 / 板块该怎么拼写时 | 用结果里的实际取值回填参数，比猜写法可靠 |
| 结果为空的排查 | 空表不等于库坏了 | 去掉参数逐步缩小定位 | 筛完返回 Empty DataFrame 时 | 先区分是「条件确实无匹配」还是「上游取数失败」，两者表现可能相似 |
边界：筛选出的结果是证券清单，不是行情或估值序列。按市值分层只能用于粗筛，具体数值请以行情源为准。
search 系列
search_products：按名称模糊搜索
search_products 用于按名称模糊搜索证券，是「记得名字但记不住代码」时的入口。
import financedatabase as fd
# 跨类别模糊搜索
fd.search_products("Apple")
# 限定在某一类里搜索
fd.search_products(database="Equities", query="Apple")
| 写法 | 会得到什么 | 适用场景 | 注意点 |
|---|---|---|---|
search_products("Apple") | 跨类别命中的记录 | 只知道名字、不知道它在哪一类 | 结果可能同时包含股票与其他类别，需要人工挑 |
search_products(database="Equities", query="Apple") | 限定类别后的命中结果 | 已经明确要找的是股票 | 类别名写法以官方文档为准，写错类别会返回空 |
| 只给主体名、不补后缀 | 可能命中相关的一族产品 | 想看看同一家公司有哪些相关证券 | 命中越多越需要人工确认，不要直接把随手取到的那条当目标 |
| 同名前缀跨类别 | 股票 / ETF / 基金可能都出现 | 排查「为什么同一个名字出来好几条」 | 先想清楚要的是哪一类，再叠加 database 限定 |
| 搜不到时的排查 | 换关键词或换搜索方式 | 关键词太具体、含中文、含特殊符号时 | 先用 show_* 看一眼该类里的实际命名风格，再回来搜 |
| 拿到结果之后 | 一个含代码的 DataFrame | 把名称反查成代码，再交给行情源 | 本库只到代码与元数据这一步，后续取价要另接数据源 |
说明：search_products 可跨类别搜索，也可用
database 参数限定在某类证券内搜索；模糊匹配的算法细节以官方实现为准。Task Routing
三系 API 怎么选：7 个真实任务的调用路径
官方 README 给的是函数清单，不给「我这件事该用哪一系」。下面按任务倒推调用路径。
| 我的目标 | 用哪一系 | 具体调用 | 拿到什么 | 适用场景 | 什么时候不用它 |
|---|---|---|---|---|---|
| 先看看这一类都有什么 | show_* | fd.show_equities() | 该类全量清单 | 探索阶段，还不确定范围 | 已经明确只要某国某行业时，全量拉取偏重 |
| 只要某国 + 某行业的股票 | select_* | fd.select_equities(country="United States", sector="Technology") | 复合条件筛出的子集 | 研究范围已经清楚 | 条件在参数里表达不了时，改用 show + 本地过滤 |
| 只记得公司名，要代码 | search_products | fd.search_products("Apple") | 命中的记录（含代码） | 名称反查代码 | 要做的是「按行业批量取数」而不是找某一家时 |
| 同名产品混杂要挑出股票 | search + 类别限定 | fd.search_products(database="Equities", query="Apple") | 限定类别后的结果 | 跨类别同名排查 | 不确定目标在哪一类时，先不加限定跑一次 |
| 筛选条件库里没有对应参数 | show_* + pandas | 先全量取回，再自行 df[df["..."] == ...] | 自定义条件的子集 | 一次性、探索性的特殊筛选 | 会反复跑的分析，更适合先看有没有现成参数 |
| 按市场规模分层建池 | select_* | fd.select_equities(market_cap="Large Cap") | 某一市值层级的清单 | 做分层对照研究 | 需要精确市值数字时，本库字段可能滞后，要另行取数 |
| 先筛大类再逐步收敛 | 三系组合 | select_* 收窄 → search_products 定位 | 多轮收敛后的候选清单 | 研究初期反复缩小范围 | 每轮都查上游，网络不稳时更容易失败，注意区分空结果与失败 |
取舍原则：能用
select_* 表达的就不要先拉全量；能用一次 search_products 定位的就不要遍历清单。库的定位是「代码与元数据」，调用越多、越靠近上游，越容易碰到数据源侧的不稳定。Read the DataFrame
返回的 DataFrame 怎么读：自查清单与常见误用
三系 API 都返回 DataFrame，但「拿到了表」不等于「数据可用」。下面这几项建议每次上手新环境时过一遍。
| 检查项 | 怎么查 | 正常表现 | 异常表现 | 怎么办 |
|---|---|---|---|---|
| 是不是 DataFrame | type(df) | pandas DataFrame | 返回 None 或列表 | 先确认函数名与参数写法，以官方 README 为准 |
| 行列规模是否合理 | df.shape | 行数与该类证券量级相符 | 0 行、或行数明显异常 | 0 行先查参数取值与上游可达性，两种原因表现相似 |
| 列名是否符合预期 | df.columns | 出现名称、代码、国家、行业等元数据列 | 缺少你依赖的那一列 | 列清单以实际返回与官方文档为准，不要照抄别的教程字段名 |
| 关键列缺失情况 | df.isna().sum() | 个别字段有缺失 | 整列缺失或大面积缺失 | 按需过滤，并在结论里注明缺失范围 |
| 代码列是否可直接对接 | 抽查 df.head() 里的代码字段 | 能识别出交易所与代码 | 代码带后缀 / 前后有空格 | 对接行情源前先清洗，不同数据源对后缀要求不同 |
| 是否被当成行情表用 | 看有没有开高低收、成交量列 | 本库没有行情列 | 把元数据字段当成价格用 | 行情需另接数据源；市值等字段也可能滞后，不宜直接当估值依据 |
边界与披露：FinanceDatabase 与 EasyClaw 无已证实集成——项目 README 与官方文档未提及，本机技能目录中也没有对应技能。本页介绍的是 FinanceDatabase 自身的 API 用法，所有判断以官方 README / PyPI 为准。
Scenarios
这套 API 适合什么、不适合什么
把「适合」和「不适合」并排写清楚，比只列优点更省时间。
构建研究用证券池
按国家、板块、行业、市值分层筛出候选集合，先固定范围再谈分析口径。分层建议只用于粗筛，别把市值分层当成精确的规模判断。
名称反查代码
只记得公司或产品名时，用 search_products 把名字换成代码，再交给行情源。跨类别同名时记得叠加类别限定，避免拿错标的。
数据管道的上游环节
把本库输出当作管道输入：先出代码清单，再由行情 / 基本面库补数据。职责单一反而好排错，出问题时更容易定位到是哪一环。
跨类别清单整理
股票、ETF、基金、指数、货币、加密货币、货币市场七类可在同一套 API 下取数，适合做清单级的横向整理与对照。
不适合：要行情与估值序列
需要价格、净值、收益率、财务时序的场合不适合用它单独完成，必须另接数据源。把它当「代码与元数据层」使用，定位最不容易出错。
Same Name, Different Thing
七类证券里最容易混的同名概念
FinanceDatabase 把七类证券放在同一套 API 下，但不同类别里「看起来同名」的概念含义并不一样。跨类别取数时的多数错误，都发生在这一步。
| 容易混的一对 | 混在哪里 | 怎么区分 | 对调用结果的影响 | 注意点 |
|---|---|---|---|---|
| ETF 与基金（Funds） | 两者都可能是「一篮子资产」的载体 | 看它归属哪一类数据库，而不是看名字 | 选错类别会整类漏掉目标产品 | 同一产品在两类里的收录口径可能不同，以官方说明为准 |
| 指数（Indices）与指数型 ETF | 名字里常出现同一个指数名称 | 指数是「标的」，ETF 是「可交易产品」 | 想做交易却拿到指数代码，后续行情对不上 | 指数成分与 ETF 持仓明细都不在本库范围内 |
| 货币（Currencies）与加密货币 | 中英文里都带着一个「币」字 | 看类别归属：外汇类还是加密类 | 两类代码风格完全不同，混用会直接取数失败 | 加密资产在不同交易所的交易对命名不统一，需二次核对 |
| 股票与其他类别的同名产品 | 同一家公司名下可能同时有股票与 ETF | 用类别限定，或按类别分别取数 | search_products 会跨类别命中，随手取到的那条不一定是你要的 | 命中多条时务必人工确认，不要按顺序取排在前面的那一条 |
| 货币市场工具与货币 | 都涉及「短端、现金类」的概念 | 前者是工具清单，后者是币种清单 | 想找币种代码却拿到工具清单 | 利率、收益率等数据不在本库范围内 |
| 国家字段与交易所所在地 | 看到海外上市就默认属于当地 | 国家字段表达的是归属口径，不是挂牌地 | 按国家筛会漏掉跨境上市的标的 | 字段口径由上游数据源决定，可能滞后或与本地习惯不同 |
| 板块（sector）与行业（industry） | 两层分类看起来都能用来「分行业」 | sector 更粗、industry 更细，粒度不同 | 用错层级，结果量级可能差出很多倍 | 分类体系来自上游，与本地常用分类不完全一致 |
实用建议：跨类别取数前，先想清楚要的是「标的」还是「产品」、是「币种」还是「工具」，再用类别参数把范围钉死。拿不准时，先用
show_* 看一眼该类里真实的命名风格，比凭直觉猜写法要快得多，也更容易复现。Troubleshooting
API 调用常见报错与空结果排查
官方 README 通常只给成功路径。这一节汇总「直接报错」和「跑得通但结果不对」两类情况，便于刚上手时对照排查。
| 现象 | 常见原因 | 怎么确认 | 处理建议 | 注意点 |
|---|---|---|---|---|
ModuleNotFoundError: financedatabase | 没装，或装到了另一个解释器环境 | 在报错的那个解释器里执行 import 试一次 | 用当前解释器重新 pip install financedatabase | 多环境机器上这是最常见原因，先查解释器再怀疑包本身 |
| 导入成功，调用时报错 | 依赖库（如 pandas）版本不匹配 | 看报错信息里点出的依赖与版本号 | 按官方 README 与 PyPI 的约束调整依赖版本 | 不建议一次性升级全部依赖，容易引入新的冲突 |
| 返回空 DataFrame | 参数取值与库内口径不一致 | 把参数逐个去掉，重跑一次对比行数 | 用 show_* 看实际取值，再回填到筛选参数 | 空结果与上游取数失败表现相似，必须分开判断 |
| 调用很慢或超时 | 上游数据源可达性差 | 换个时段或网络再试一次 | 把结果缓存在本地，减少重复拉取全量清单 | 本库依赖公开上游源，不是本地静态数据包 |
| 某一整列都是空值 | 该字段在上游缺失或口径变化 | 用 df.isna().sum() 逐列看缺失量 | 调整分析口径，或在结论里标注缺失范围 | 字段清单会随上游变动，以官方文档与实测为准 |
| 拿到的代码无法对接行情源 | 后缀与格式不符合行情源要求 | 抽查 df.head() 里的代码字段写法 | 对接前先做一次代码清洗与格式统一 | 不同数据源要求的代码格式不同，不能一套写法到处用 |
| 用中文关键词搜不到 | 库内命名以英文为主 | 把同一个标的换成英文名再搜一次 | 先用 show_* 看命名风格，再用英文名搜索 | 中文检索的支持程度以官方实现为准 |
先确认解释器与安装
python -c "import financedatabase; print(financedatabase.__file__)"—— 打印实际加载的包路径。预期：路径与你执行 pip 安装的那个环境一致；不一致说明装到了别的解释器，后面的报错都能由此解释。再用最小代价确认上游可达
挑一个体量较小的类别跑一次
fd.show_currencies()—— 用最小查询判断「是上游不通，还是我的参数不对」。预期：返回一个非空 DataFrame；若这里就为空，问题更可能出在网络或上游数据源。最后逐个加回你的筛选条件
把
select_*的参数一个个加回来，每加一个看一次df.shape—— 定位是哪一个条件把结果筛空。预期：能收敛到具体参数上，而不是停留在「查询没结果」。
排查顺序建议：先确认「能不能跑通」（解释器与依赖），再确认「能不能取到数」（上游可达性），最后才怀疑参数写法。顺序反了会在错误的方向上反复试。本页涉及的调用细节与字段口径，均以官方 README / PyPI 为准。
FAQ
三系 API 常见问题
show 和 select 有什么区别？
show 展示某类证券的完整列表；select 按 country / sector / industry / market_cap 等条件筛出子集。判断方法很简单：需要「全量清单」用 show，需要「子集」用 select。函数名与参数细节以官方 README 为准。
返回的数据是什么格式？
pandas DataFrame，列包含证券名称、代码、国家、行业、市值、货币等元数据。具体列名随上游数据源变动，建议以自己机器上返回的结果和官方文档为准，不要照搬第三方教程的字段清单。
能跨类别搜索吗？
可以。search_products 默认跨类别搜索，也可以用 database 参数限定在某一类内搜索。类别名的写法以官方文档为准；返回多条时请人工确认目标，模糊匹配不代表只有一条命中。
select 传多个参数是「同时满足」还是「满足其一」？
多参数属于叠加的筛选条件，连接语义以官方实现为准。稳妥做法是先单参数跑一遍看结果量级，再逐个叠加参数，这样出现空表时更容易定位是哪个条件把结果筛没了。
查询返回空表怎么办？
先区分两种原因：一是参数取值与库内口径不一致（例如国家、板块的写法不同），二是上游数据源不可达或响应失败。推荐顺序是先去掉参数重跑，再回查取值写法，最后才怀疑网络与上游状态。两种原因的表现可能相似，不要直接判定为「库有问题」。
这些数据能当行情或估值依据用吗？
不能。FinanceDatabase 提供的是证券代码与元数据，不提供行情价格；部分字段（如市值）也可能滞后于实时市场。做行情、净值、收益率分析需要另接数据源，本页内容仅供项目研究与安装判断，不构成投资建议。