40 个端点 · 行情 · 基本面 · 筹码面 · 其他 · 板块与题材 · 选股器
https://api.blave.orgapi-key 与 secret-key 请求头API plan or Blave Agent planstock_id:TWSE(上市)/TPEx(上柜)代码,例如 2330、0050、00878、006208。英文字母与数字(可含点),≤ 8 字符,否则回 400 {"error": "Invalid stock_id"}。start/end:YYYY-MM-DD,含当日。除非该端点另有说明,否则不做格式验证(以字符串比较过滤),所以一律送 YYYY-MM-DD。503 {"error": "Upstream rate limit. Please retry shortly."},稍后重试。batch/<data_type>(每次 ≤ 50 档);不要拿单股端点对整个股票池跑循环。/studio/market/twstock/list 无。
data = requests.get(f"{BASE_URL}/studio/market/twstock/list" , headers=headers, timeout=60).json()["data"]# [{"stock_id": "00400A", "name": "主動國泰動能高息", "close": 14.72, "market": "TWSE",# "industry_code": None, "listing_date": None}, ...] # 2,392 rows in this response{"data": [...]},约 2,400 列(上市+上柜,含 ETF;不含兴柜)。
| 字段 | 类型 | 说明 |
|---|---|---|
stock_id | string | 代码 |
name | string | 名称 |
close | float | null | 最新日收盘价(上游没有数据时为 null,例如暂停交易) |
market | string | TWSE(上市)或 TPEx(上柜) |
industry_code | string | null | TWSE/TPEx 原始的数字产业别代码,原样传回(不解码)。ETF/非公司型证券为 null。常见代码:15 航运业、17 金融保险业、22 生技医疗业、24 半导体业、25 电脑及周边设备业、26 光电业、27 通信网络业、28 电子零组件业、29 电子通路业、30 资讯服务业、31 其他电子业 |
listing_date | string | null | YYYY-MM-DD;ETF/非公司型证券为 null |
只有共用错误(两个市场都失败时回 500)。
[:N] 截断会集中在少数几个产业。/studio/market/twstock/info/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 |
info = requests.get(f"{BASE_URL}/studio/market/twstock/info/2330" , headers=headers, timeout=30).json()["data"]# {"stock_id": "2330", "name": "台積電", "close": 2410.0, "industry_code": "24", "listing_date": "1994-09-05"}{"stock_id": "<stock_id>", "data": {...}};data 的字段与 /list 的一列相同。
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id"} | 格式检查未通过 |
| 404 | {"error": "Stock not found"} | 不是目前上市柜的证券 |
/list 共用同一份缓存。/studio/market/twstock/price/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 上市或上柜股票/ETF 代码 | 英文字母/数字(可含点),≤ 8 字符,例如 2330、0050、00878、006208 | |
startstring · query | 起始日,含当日 | YYYY-MM-DD | 完整历史 |
endstring · query | 结束日,含当日 | YYYY-MM-DD | 最新一天 |
response = requests.get(f"{BASE_URL}/studio/market/twstock/price/2330" , headers=headers, timeout=60)data = response.json()["data"] # no start/end → full history, 8,069 rows# [{"date": "1994-10-01", "stock_id": "2330", "open": 171.0, "high": 172.0,# "low": 171.0, "close": 172.0, "spread": 1.0,# "volume": 1660506, "turnover_value": 284858008, "turnover_count": 684},# {"date": "1994-10-03", "stock_id": "2330", "open": 172.0, "high": 173.0,# "low": 171.0, "close": 172.0, "spread": 0.0,# "volume": 1560000, "turnover_value": 268084000, "turnover_count": 711}, ...]{"stock_id": "<stock_id>", "data": [ ... ]},依 date 由旧到新排序。
| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
date | string | YYYY-MM-DD | 交易日 |
stock_id | string | — | 股票代码 |
open / high / low / close | float | 元 | 未还原价格 |
spread | float | 元 | 与前一日收盘价的差额 |
volume | int | 股 | 成交股数 |
turnover_value | int | 元 | 成交金额 |
turnover_count | int | 笔 | 成交笔数 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id"} | stock_id 格式检查未通过 |
| 404 | {"error": "No data found for stock_id: <stock_id>"} | 未知代码/上游没有数据 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽,稍后重试 |
start/end 不做格式验证:格式错误的值会改用字符串比较过滤,而不是回 400,所以一律送 YYYY-MM-DD。price_adj;这个端点是未还原价格。batch/price(每次 ≤ 50 档),不要对这个端点跑循环。/studio/market/twstock/price_adj/<stock_id> 同 /price/<stock_id>。
params = {"start": "2020-01-01", "end": "2024-12-31"}data = requests.get(f"{BASE_URL}/studio/market/twstock/price_adj/2330" , headers=headers, params=params, timeout=60).json()["data"]形状与字段同 /price/<stock_id>;open/high/low/close 是还原后的价格,volume/turnover_* 与原始序列相同。
同 /price/<stock_id>。
/price 序列有新数据时重建。/studio/market/twstock/quote/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/quote/2330" , headers=headers, timeout=30).json()["data"]# {"open": 2415.0, "high": 2465.0, "low": 2415.0, "close": 2445.0,# "change_price": -20.0, "change_rate": -0.81, "average_price": 2432.58,# "volume": 4245, "total_volume": 26403, "amount": 10379025000, "total_amount": 64227410000,# "yesterday_volume": 27390, "buy_price": 2445.0, "buy_volume": 17,# "sell_price": 2450.0, "sell_volume": 11, "volume_ratio": 0.96,# "quote_time": "2026-07-03 14:30:00", "stock_id": "2330", "tick_type": 2}{"stock_id": "<stock_id>", "data": {...}};data 是扁平对象。
| 字段 | 类型 | 说明 |
|---|---|---|
open / high / low / close | float | 今日至今的 OHLC |
change_price / change_rate | float | 与前一日收盘价的涨跌(元/%) |
average_price | float | 成交均价 |
volume | int | 最新一笔的成交量 |
total_volume | int | 今日累计成交量 |
amount / total_amount | float | 最新一笔/累计成交金额 |
yesterday_volume | int | 前一日成交量 |
buy_price / buy_volume | float / int | 最佳买价 |
sell_price / sell_volume | float / int | 最佳卖价 |
volume_ratio | float | 量比 |
quote_time | string | YYYY-MM-DD HH:MM:SS,是完整时间戳,不像其他端点只有 date |
stock_id | string | 代码 |
tick_type | int | 0 无法判断、1 卖盘成交、2 买盘成交 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id"} | 格式检查未通过 |
| 404 | {"error": "No data found for stock_id: <stock_id>"} | 没有报价 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
/studio/market/twstock/quote | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idsstring · query必填 | 代码 | 逗号分隔,≤ 50 档 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/quote" , headers=headers, params={"stock_ids": "2330,2317"}, timeout=30).json()["data"]# {"2330": {...}, "2317": {...}}{"data": {"<stock_id>": {...quote fields...}, ...}};字段同 /quote/<stock_id>。没有报价的代码不会出现。
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "stock_ids parameter required"} | 缺少 |
| 400 | {"error": "stock_ids exceeds max 50 per request"} | 超过上限 |
| 400 | {"error": "Invalid stock_id in list"} | 有代码格式检查未通过 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
/studio/market/twstock/quote/all 无。
rows = requests.get(f"{BASE_URL}/studio/market/twstock/quote/all" , headers=headers, timeout=30).json()["data"]{"data": [{...quote fields...}, ...]}(约 2,800 列);字段同 /quote/<stock_id>。
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
/studio/market/twstock/minute/ohlcv/<stock_id>/<schema> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 目前上市柜的 TWSE/TPEx 代码,或 TAIEX(加权指数) | |
schemastring · path必填 | K 棒周期 | 1m, 5m, 15m, 30m, 60m, 1d | |
startstring · query | 起始日 | YYYY-MM-DD | end − 该周期的最大区间 |
endstring · query | 结束日(含当日) | YYYY-MM-DD | 今天(UTC) |
adjuststring · query | 1 = 还原(后复权)OHLC,因子同 /price_adj;volume 一律不还原 | 0, 1, true, false | 0 |
每次请求的最大区间(end − start):1m 31 天 · 5m 62 天 · 15m 93 天 · 30m 186 天 · 60m 365 天 · 1d 3650 天。
body = requests.get(f"{BASE_URL}/studio/market/twstock/minute/ohlcv/2330/1m" , headers=headers, params={"start": "2026-08-06", "end": "2026-08-06"}, timeout=60).json()# {"stock_id": "2330", "schema": "1m", "data": [# {"close": 2385.0, "high": 2395.0, "low": 2385.0, "open": 2395.0, "ts": "2026-08-06 01:00:00+00:00", "volume": 2540}, ...]}{"stock_id", "schema", "data": [...]}.
| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
ts | string | UTC ISO 格式 | K 棒开始时间(以分钟起点标记);台北时间 13:30 那根是收盘集合竞价 |
open / high / low / close | float | 元 | 价格 |
volume | int | 张,不是股 | 成交量。TAIEX 的 K 棒在每个周期都是 volume: 0:指数没有成交量,所以不提供;不要当成成交金额来读 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id (must be a listed TWSE/TPEx security)"} | 未上市柜 |
| 400 | {"error": "Invalid schema. Allowed: [...]"} | 周期不对 |
| 400 | {"error": "Invalid adjust (use 0 or 1)"} | adjust 不对 |
| 400 | {"error": "Invalid date format. Use YYYY-MM-DD"} | 日期格式错误 |
| 400 | {"error": "date_range_too_large", "message": "...", "max_days": <n>} | 区间超过上限 |
| 503 | {"error": "market data temporarily unavailable"} | 数据库读取失败 |
| 503 | {"error": "adjust factors temporarily unavailable"} | adjust=1 但取不到还原因子:绝不会默默改给未还原数据 |
minute/ohlcv/symbols。200 与 []。/quote/<stock_id>。/studio/market/twstock/minute/ohlcv/symbols 无。
covered = requests.get(f"{BASE_URL}/studio/market/twstock/minute/ohlcv/symbols" , headers=headers, timeout=30).json()["data"]{"data": ["2330", "TAIEX", ...]}:已经有分钟线数据的代码(目前上市柜的股票加上 TAIEX),已排序。
只有共用错误。
/studio/market/twstock/kbar/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 目前上市柜的 TWSE/TPEx 代码,或 TAIEX | |
startstring · query | 起始日 | YYYY-MM-DD | 今天 − 6 天 |
endstring · query | 结束日;end − start ≤ 31 天 | YYYY-MM-DD | 今天 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/kbar/2330" , headers=headers, params={"start": "2026-08-03", "end": "2026-08-07"}, timeout=60).json()["data"]{"stock_id", "data": [...]},由旧到新。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | YYYY-MM-DD(台北时间) |
minute | string | HH:MM:SS 台北时间,K 棒开始时间(09:00–13:30) |
stock_id | string | 代码 |
open / high / low / close | float | 元 |
volume | int | 张 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id (must be a listed TWSE/TPEx security)"} | 未上市柜 |
| 400 | {"error": "Date range exceeds 31 days"} | 区间太长 |
| 400 | {"error": "Invalid start date, expected YYYY-MM-DD"}(或 end) | 日期格式错误 |
| 400 | {"error": "start must not be after end"} | 区间颠倒 |
minute/ohlcv/<stock_id>/1m。上市柜股票没有分钟数据时回 [](这个端点不会触发回补)。minute/ohlcv/symbols 涵盖的代码有数据。/studio/market/twstock/market_value/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 完整历史 |
endstring · query | 结束日 | YYYY-MM-DD | 最新 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/market_value/2330" , headers=headers, params={"start": "2026-01-01"}, timeout=60).json()["data"]{"stock_id", "data": [{"date", "stock_id", "market_value"}]};market_value 单位为元。
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
/studio/market/twstock/market_value/all | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
topint · query | 只留市值前 N 名 | 1–3000 | 全部(约 2,400) |
body = requests.get(f"{BASE_URL}/studio/market/twstock/market_value/all" , headers=headers, params={"top": 10}, timeout=60).json()# {"date": "2026-09-17", "twse_ex_etf_market_value": 150952470507848,# "data": [{"is_etf": false, "market": "TWSE", "market_value": 62885997412475,# "name": "台積電", "rank": 1, "stock_id": "2330"},# ...,# {"is_etf": true, "market": "TWSE", "market_value": 2383312875000,# "name": "元大台灣50", "rank": 6, "stock_id": "0050"}, ...]}# Index weight of a 上市 non-ETF stock (works with any `top`, the denominator is whole-market)row = body["data"][0] # 2330 — market "TWSE", is_etf falseshare = row["market_value"] / body["twse_ex_etf_market_value"]# ETFs rank alongside stocks (0050 is rank 6) — filter them with `is_etf`. Never by code prefix,# and never by re-fetching a classification: `is_etf` already IS that classification.rows = requests.get(f"{BASE_URL}/studio/market/twstock/market_value/all" , headers=headers, params={"top": 100}, timeout=60).json()["data"]top50 = [r["stock_id"] for r in rows if not r["is_etf"]][:50] # ETF-free market-cap top 50tpex_only = [r["stock_id"] for r in rows if r["market"] == "TPEx"] # board filter is exact{"date": "YYYY-MM-DD", "twse_ex_etf_market_value": int, "data": [...]},依市值由大到小排序。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 实际采用的基准日(最新公布日;可能比今天晚一天) |
twse_ex_etf_market_value | int | 元。同一基准日 market == "TWSE" 且非 ETF 各列的加总。这是全市场分母,不会因 top 而缩小 |
data[].rank | int | 名次,从 1 起算 |
data[].stock_id | string | 代码 |
data[].name | string | 名称 |
data[].market | string | "TWSE"(上市)或 "TPEx"(上柜),取自 TWSE/TPEx 的上市柜名册 |
data[].market_value | int | 元 |
data[].is_etf | bool | 排行中的 ETF 为 true(2026-09-17 的 2,370 列中有 359 列)。false 代表「不在 ETF 集合里」,不代表「确认不是 ETF」:没有产业类别的证券(例如 REIT 01010T)会是 false,而且仍算在 twse_ex_etf_market_value 里 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "top must be an integer between 1 and 3000"} | top 不对 |
| 503 | {"error": "Data temporarily unavailable. Please retry shortly."} | 近期数据或上市柜清单暂时无法取得 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
/market_value/<stock_id> 跑循环。rank 与 twse_ex_etf_market_value 的母体不同。rank 是全市场排名(上市+上柜,含 ETF),加上分母之后也没有改变。分母只算上市、排除 ETF(industry_category 属于 {ETF, 上櫃ETF, 上櫃指數股票型基金(ETF)});REIT 与特别股没有排除。所以 market_value / twse_ex_etf_market_value 只有在该列 market 为 "TWSE" 且不是 ETF 时才是指数权重,上柜或 ETF 的列除以这个分母不是权重;rank 则仍是全市场排名。不要把两者当成同一个排行来读。market 是挂牌板别标记,不是 ETF 旗标,is_etf 才是 ETF 旗标。要排除 ETF 的股票池就用它。不要从 stock_id 开头推断 ETF(00 是市场惯例而不是规格,而且会漏掉 REIT 01xxxT),也不要再从别处抓一次分类。is_etf 正是 twse_ex_etf_market_value 计算时用的判准,所以用 is_etf 筛选的结果和分母不可能对不上。/studio/market/twstock/per/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 完整历史 |
endstring · query | 结束日 | YYYY-MM-DD | 最新 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/per/2330" , headers=headers, params={"start": "2026-01-01", "end": "2026-07-22"}, timeout=60).json()["data"]# [{"date": "2026-07-21", "stock_id": "2330", "dividend_yield": 0.95, "PER": 34.87, "PBR": 11.05}, ...]{"stock_id", "data": [...]}.
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 交易日 |
stock_id | string | 代码 |
dividend_yield | float | 殖利率(%) |
PER | float | 本益比 |
PBR | float | 股价净值比 |
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
batch/per。/studio/market/twstock/financials/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 2013-01-01 |
endstring · query | 结束日 | YYYY-MM-DD | 今天 |
import pandas as pddata = requests.get(f"{BASE_URL}/studio/market/twstock/financials/2330" , headers=headers, params={"start": "2022-01-01", "end": "2024-12-31"}, timeout=30).json()["data"]# [{"date": "2022-03-31", "stock_id": "2330", "type": "Revenue", "value": 491075000000.0, "origin_name": "營業收入"}, ...]wide = pd.DataFrame(data).pivot_table(index="date", columns="type", values="value", aggfunc="first"){"stock_id", "data": [...]},长格式(每季每个科目一列)。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 季末日(03-31/06-30/09-30/12-31) |
stock_id | string | 代码 |
type | string | 科目代码,例如 Revenue、GrossProfit、OperatingIncome、NetIncome、EPS、TAX、OtherComprehensiveIncome |
value | float | 数值(元;EPS 为每股元) |
origin_name | string | 中文科目名称,遇到不认得的 type 代码时用它辨识 |
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
start 默认为 2013-01-01;送更早的 start 就会拿到更早的数据(2330 最早到 2000-06-30)。/studio/market/twstock/balance_sheet/<stock_id> 同 /financials/<stock_id>。
data = requests.get(f"{BASE_URL}/studio/market/twstock/balance_sheet/2330" , headers=headers, params={"start": "2022-01-01"}, timeout=30).json()["data"]长格式同 /financials/<stock_id>。主要 type 代码:CashAndCashEquivalents、TotalAssets、TotalLiabilities、TotalEquity。结尾为 _per 的代码是占总资产的百分比。
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
start 默认为 2013-01-01;送更早的 start 就会拿到更早的数据(2330 最早到 2012-12-31)。/studio/market/twstock/cashflow/<stock_id> 同 /financials/<stock_id>。
import pandas as pddata = requests.get(f"{BASE_URL}/studio/market/twstock/cashflow/2330" , headers=headers, params={"start": "2022-01-01"}, timeout=30).json()["data"]cfo = (pd.DataFrame(data).query("type == 'CashFlowsFromOperatingActivities'") .assign(date=lambda d: pd.to_datetime(d["date"])).set_index("date")["value"].sort_index())cfo_q = cfo - cfo.groupby(cfo.index.year).shift(1).fillna(0) # YTD → single quarter长格式同 /financials/<stock_id>。主要 type 代码(上游数据集自己的代码;完整集合依公司与年度而异,以回应内容为准,下表没有的用 origin_name 判读)。筛选时用 type,不要用 origin_name:同一个代码的中文名称在不同年度会在全形与半形括号之间切换:
type | origin_name |
|---|---|
CashFlowsFromOperatingActivities | 营业活动之净现金流入(流出) |
CashProvidedByInvestingActivities | 投资活动之净现金流入(流出) |
CashFlowsProvidedFromFinancingActivities | 筹资活动之净现金流入(流出) |
PropertyAndPlantAndEquipment | 取得不动产、厂房及设备(资本支出,负值) |
Depreciation / AmortizationExpense | 折旧费用 / 摊销费用 |
CashBalancesIncrease | 本期现金及约当现金增加(减少)数 |
CashBalancesBeginningOfPeriod / CashBalancesEndOfPeriod | 期初(年初)/ 期末现金及约当现金余额 |
流量科目是年初至今(YTD)累计,照台湾申报方式:03-31 那列只有 Q1,06-30 是 Q1–Q2,09-30 是 Q1–Q3,12-31 是全年。要单季数字就减掉同年前一季(Q1 不用减),所以 start 要从 1 月开始抓。CashBalancesEndOfPeriod 是季末余额;CashBalancesBeginningOfPeriod 是年初余额。这个端点没有 period 参数,一律回 YTD(?period=quarter 单季检视只存在于网页图表路由,这里没有)。
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
start 默认为 2013-01-01;送更早的 start 就会拿到更早的数据(2330 最早到 2012-03-31)。/studio/market/twstock/monthly_revenue/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 2000-01-01 |
endstring · query | 结束日 | YYYY-MM-DD | 今天 |
import pandas as pddata = requests.get(f"{BASE_URL}/studio/market/twstock/monthly_revenue/2330" , headers=headers, params={"start": "2024-01-01", "end": "2024-12-31"}, timeout=30).json()["data"]df = pd.DataFrame(data).sort_values(["revenue_year", "revenue_month"])df["yoy_pct"] = df["revenue"].pct_change(periods=12) * 100# [{"date": "2024-01-01", "stock_id": "2330", "country": "Taiwan", "create_time": "",# "revenue": 176299866000, "revenue_year": 2023, "revenue_month": 12},# {"date": "2024-02-01", "stock_id": "2330", "country": "Taiwan", "create_time": "",# "revenue": 215785127000, "revenue_year": 2024, "revenue_month": 1}, ...]{"stock_id", "data": [...]},每月一列。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 营收月份的下一个月的第一天:2024-01-01 那列是 revenue_year: 2023、revenue_month: 12。绝不要拿它当营收期间 |
stock_id | string | 代码 |
country | string | 市场,观察到的值是 Taiwan |
create_time | string | 每一列都观察到是空字符串("") |
revenue | int | 月营收,单位为元,不是千元。这是从数量级推得的,上游没有注明:2330 的 revenue_year 2024, revenue_month 1 回 215785127000,只有读成元(NT$215.8bn)才是合理的数字 |
revenue_month | int | 营收月份(1–12),营收期间看这个,不要看 date |
revenue_year | int | 营收年度 |
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
/studio/market/twstock/ratios/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始季末日 | YYYY-MM-DD | 2013-01-01 |
endstring · query | 结束季末日 | YYYY-MM-DD | 今天 |
import pandas as pddata = requests.get(f"{BASE_URL}/studio/market/twstock/ratios/2330" , headers=headers, params={"start": "2024-01-01"}, timeout=30).json()["data"]# [..., {"date": "2026-06-30", "stock_id": "2330",# "gross_margin_q": 67.7207, "gross_margin_ttm": 64.2302, "operating_margin_q": 60.3443, "operating_margin_ttm": 56.1009,# "net_margin_q": 55.6354, "net_margin_ttm": 50.3717, "roe_q": 11.3934, "roe_ttm": 40.3342, "roa_q": 7.8372, "roa_ttm": 27.3074,# "eps_q": 27.25, "eps_ttm": 86.28, "eps_yoy_q": 77.4089, "eps_yoy_ttm": 53.2232,# "revenue_yoy_q": 36.0453, "revenue_yoy_ttm": 30.5567, "revenue_qoq_q": 12.0163, "revenue_qoq_ttm": 8.2017,# "debt_ratio": 30.9438, "current_ratio": 245.7635, "quick_ratio": 225.0114, "equity_multiplier": 1.4481,# "interest_coverage_q": 280.5515, "interest_coverage_ttm": 227.0232,# "inventory_turnover_q": 1.1767, "inventory_turnover_ttm": 4.6058, "cfo_to_net_income_q": 1.1084, "cfo_to_net_income_ttm": 1.1779,# "fcf_q": 287363030000.0, "fcf_ttm": 1143556366000.0, "fcf_per_share_q": 11.0827, "fcf_per_share_ttm": 44.1036, ...}]df = pd.DataFrame(data).assign(date=lambda d: pd.to_datetime(d["date"])).set_index("date"){"stock_id", "data": [...]},宽格式:每季一列,由旧到新,每个比率一栏。每个比率都是四舍五入到 4 位小数的 float,或 null。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 季末日(03-31/06-30/09-30/12-31),不是财报公开的日期 |
stock_id | string | 代码 |
<ratio>_q | float | null | 单季 |
<ratio>_ttm | float | null | 近四季(四个单季加总);四季中任一季缺数据就是 null |
debt_ratio, current_ratio, quick_ratio, equity_multiplier | float | null | 期末资产负债表比率,没有后缀 |
<ratio>(每个都有 _q 与 _ttm 两种):
| 类别 | 比率 | 单位 |
|---|---|---|
| 获利能力 | gross_margin, operating_margin, pretax_margin, net_margin, opex_ratio, roe, roa | %(已乘 100) |
| 每股 | eps, revenue_per_share, fcf_per_share | 每股元 |
| 成长 | revenue_yoy, revenue_qoq, operating_income_yoy, net_income_yoy, eps_yoy | %(已乘 100) |
| 结构 | interest_coverage | 倍 |
| 经营效率 | receivable_turnover, inventory_turnover, asset_turnover, cfo_to_net_income | 倍 |
| 现金流量 | fcf | 元,原始金额(不是千元) |
没有后缀的字段:debt_ratio、current_ratio、quick_ratio 是 %(已乘 100,流动比率 2.46 倍会回 245.7635);equity_multiplier 是倍数。
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id"} | 代码格式检查未通过 |
| 404 | {"error": "No data found for stock_id: <id>"} | 这个代码没有财报(例如 0050/00878 这类 ETF),或 start–end 范围内没有数据 |
| 503 | {"error": "Data temporarily unavailable. Please retry shortly."} | 比率数据库还没准备好,稍后重试,绝不要当成「没有数据」 |
null(没有毛利率、流动比率等)。date 对齐会有前视偏差。null,绝不会是 0。per/<stock_id>),以及月营收相关比率(自己用 monthly_revenue/<stock_id> 算年增/月增)。GET /studio/market/twstock/batch/ratios?stock_ids=...(每次 ≤ 50 档)。start 也拿不到更早的数据。/studio/market/twstock/dividend/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 目前上市柜的代码(4–6 位数字,结尾可带一个英文字母) | |
startstring · query | 起始生效日 | 严格 YYYY-MM-DD | 完整历史 |
endstring · query | 结束生效日 | 严格 YYYY-MM-DD | 完整历史 |
区间过滤用三层递补的生效日:有 cash_ex_date 用它,否则 stock_ex_date,再否则 record_date;刚公告、还没有除息日的事件也会出现。
data = requests.get(f"{BASE_URL}/studio/market/twstock/dividend/2330" , headers=headers, params={"start": "2025-01-01", "end": "2025-12-31"}, timeout=30).json()["data"]# [{"record_date": "2025-03-24", "period": "113年第3季", "announce_date": "2025-03-03",# "cash_ex_date": "2025-03-18", "stock_ex_date": "", "pay_date": "2025-04-10",# "cash": 4.50002042, "stock": 0.0, "stock_ratio": 0.0}, ...]{"stock_id", "data": [...]},每笔公告一列。
| 字段 | 类型 | 说明 |
|---|---|---|
record_date | string | 权利分派基准日 YYYY-MM-DD |
period | string | 股利所属期间,是不透明的标签(114年第3季、113、不適用…);当字符串比较,不要解析成年份 |
announce_date | string | 公告日;不明时为 "" |
cash_ex_date | string | 除息交易日;没有或未定时为 "" |
stock_ex_date | string | 除权交易日;没有时为 "" |
pay_date | string | 现金股利发放日;不明时为 "" |
cash | float | 每股现金股利(元,盈余+公积) |
stock | float | 每股股票股利(元面额,盈余+公积) |
stock_ratio | float | stock / 10,即拆分式的调整比例 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id"} | 格式检查未通过 |
| 400 | {"error": "Invalid start date, expected YYYY-MM-DD"}(或 end) | 日期格式错误 |
| 404 | {"error": "No data found for stock_id: <id>"} / {"error": "No dividend records for stock_id: <id>"} | 未上市柜,或完全没有股利纪录 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
cash == 0 且 stock == 0)会保留,代表公告不分派。2330 的完整历史查询最后一列比请求日还晚一周。只要过去的事件就自己依日期过滤。200 + [](与 404 不同)。404。/studio/market/twstock/news/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 今天 − 6 天 |
endstring · query | 结束日;end − start ≤ 31 天 | YYYY-MM-DD | 今天 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/news/2330" , headers=headers, params={"start": "2026-08-01", "end": "2026-08-07"}, timeout=60).json()["data"]{"stock_id", "data": [...]},每天多则新闻(含周末)。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 发布时间 |
stock_id | string | 代码 |
title | string | 标题 |
source | string | 发布来源 |
link | string | 网址 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Date range exceeds 31 days"} 或日期解析错误的信息 | 区间太长/日期格式错误 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
[]。/studio/market/twstock/institutional/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 完整历史 |
endstring · query | 结束日 | YYYY-MM-DD | 最新 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/institutional/2330" , headers=headers, params={"start": "2024-01-01", "end": "2024-12-31"}, timeout=60).json()["data"]# [{"date": "2024-01-02", "stock_id": "2330", "foreign_buy": 28464159, "foreign_sell": 47404324,# "trust_buy": 5553520, "trust_sell": 269712, "dealer_self_buy": 452000, "dealer_self_sell": 366190,# "dealer_hedge_buy": 942546, "dealer_hedge_sell": 780090,# "foreign_dealer_self_buy": 0, "foreign_dealer_self_sell": 0}, ...]{"stock_id", "data": [...]},宽格式,每天一列。所有数值单位都是股。
| 字段 | 说明 |
|---|---|
date, stock_id | 日期、代码 |
foreign_buy / foreign_sell | 外资(不含外资自营商) |
trust_buy / trust_sell | 投信 |
dealer_self_buy / dealer_self_sell | 自营商自行买卖 |
dealer_hedge_buy / dealer_hedge_sell | 自营商避险 |
foreign_dealer_self_buy / foreign_dealer_self_sell | 外资自营商(多半是 0) |
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
*_buy − *_sell。GET /studio/market/twmarket/institutional)的分组方式不同,见该节。/studio/market/twstock/margin/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 完整历史 |
endstring · query | 结束日 | YYYY-MM-DD | 最新 |
import pandas as pddata = requests.get(f"{BASE_URL}/studio/market/twstock/margin/2330" , headers=headers, params={"start": "2024-01-01"}, timeout=60).json()["data"]df = pd.DataFrame(data)df["margin_util"] = df["margin_balance"] / df["margin_limit"] # 融資使用率{"stock_id", "data": [...]},每天一列。数值单位是张,不是股,已对照 TWSE MI_MARGN 验证:2026-09-15 的 2330 回 margin_balance: 29282 与 margin_limit: 6483092,与 TWSE 当日公布的今日余额 29,282、次一营业日限额 6,483,092 完全相符。每一列都带自己的 date 与 stock_id;读完整历史(不带 start/end)时,每个数字都要取自同一列:margin_limit 每天重新公布,会随时间改变。
| 字段 | 说明 |
|---|---|
margin_buy / margin_sell | 融资买进/卖出 |
margin_cash_repay | 融资现金偿还 |
margin_balance / margin_prev_balance | 融资今日/前日余额 |
margin_limit | 融资限额,即 TWSE 在该列日期公布的次一营业日限额,也就是适用于下一个营业日的上限(2330 在 2026-09-15 为 6,483,092 张) |
short_buy / short_sell | 融券买进/卖出 |
short_cash_repay | 融券现金偿还 |
short_balance / short_prev_balance | 融券今日/前日余额 |
short_limit | 融券限额 |
offset_loan_short | 资券相抵 |
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
/studio/market/twstock/gov_bank/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 今天 − 6 天 |
endstring · query | 结束日;end − start ≤ 31 天 | YYYY-MM-DD | 今天 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/gov_bank/2330" , headers=headers, params={"start": "2026-08-01", "end": "2026-08-07"}, timeout=60).json()["data"]{"stock_id", "data": [...]},每天最多 8 列(每家行库一列),依日期、行库排序。
| 字段 | 说明 |
|---|---|
date, stock_id | 日期、代码 |
bank_name | 行库 |
buy / sell | 买进/卖出股数 |
buy_amount / sell_amount | 买进/卖出金额(元) |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Date range exceeds 31 days"} 或日期解析错误的信息 | 区间太长/日期格式错误 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
/studio/market/twstock/lending/<stock_id> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
startstring · query | 起始日 | YYYY-MM-DD | 完整历史 |
endstring · query | 结束日 | YYYY-MM-DD | 最新 |
data = requests.get(f"{BASE_URL}/studio/market/twstock/lending/2330" , headers=headers, params={"start": "2026-08-01"}, timeout=60).json()["data"]{"stock_id", "data": [...]},每天多列。
| 字段 | 说明 |
|---|---|
date, stock_id | 日期、代码 |
transaction_type | 競價 / 議借 |
volume | 成交量 |
fee_rate | 借券费率 |
close | 收盘价 |
original_return_date | 原始还券日 |
original_lending_period | 原始借券期间 |
400 stock_id 无效、404 没有数据、503 上游配额耗尽。
/studio/market/twstock/broker/search | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
namestring · query必填 | 要搜寻的分点名称 | 任意子字符串,不分大小写 |
rows = requests.get(f"{BASE_URL}/studio/market/twstock/broker/search" , headers=headers, params={"name": "松山"}, timeout=30).json()["data"]# [{"broker_id": "9217", "broker_name": "凱基-松山"}, ...]{"query": "<name>", "data": [{"broker_id", "broker_name"}]}.
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "name parameter required"} | 缺少 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
/studio/market/twstock/broker/stock/<stock_id> 查单日送 date,查区间送 start(+ end);两者都送时以 start 为准。
| 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
stock_idstring · path必填 | 代码 | 见本类别共通规则 | |
datestring · query | 单日 | YYYY-MM-DD | 今天 |
startstring · query | 区间起点 | YYYY-MM-DD | |
endstring · query | 区间终点;区间 ≤ 366 天(含头尾) | YYYY-MM-DD | start |
rows = requests.get(f"{BASE_URL}/studio/market/twstock/broker/stock/2330" , headers=headers, params={"start": "2026-08-03", "end": "2026-08-07"}, timeout=60).json()["data"]{"stock_id", "data": [...]},每个分点每天一列。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 交易日 |
stock_id | string | 代码 |
broker_id | string | 分点代码(可能含英文字母,例如 920A) |
broker_name | string | 分点名称 |
price | float | 成交量加权平均价 |
buy / sell | int | 买进/卖出股数 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid stock_id"} | 格式检查未通过 |
| 400 | {"error": "Invalid date (YYYY-MM-DD)"} | 日期格式错误 |
| 400 | {"error": "start/end range is <n> days; max 366 (inclusive) — split into smaller ranges"} | 区间太长 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 数据暂时无法取得,请重试;不要当成「没有成交」 |
200 + []。start/end 设 2026-09-06 → 2026-09-13,broker/stock/<stock_id> 与 broker/trader/<trader_id> 都回了涵盖五个交易日的数据。/studio/market/twstock/broker/trader/<trader_id> date/start/end 规则同 /broker/stock/<stock_id>。
| 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
trader_idstring · path必填 | 分点代码,从 /broker/search 取得 | 英文字母、数字、-(例如 9217、920A) | |
datestring · query | 单日 | YYYY-MM-DD | 今天 |
startstring · query | 区间起点 | YYYY-MM-DD | |
endstring · query | 区间终点;区间 ≤ 366 天(含头尾) | YYYY-MM-DD | start |
rows = requests.get(f"{BASE_URL}/studio/market/twstock/broker/trader/9217" , headers=headers, params={"date": "2026-08-07"}, timeout=60).json()["data"]{"trader_id", "data": [...]},每档股票每天一列;字段为 date、broker_id、broker_name、stock_id、price、buy、sell(同 /broker/stock)。
同 /broker/stock/<stock_id>,另外代码错误时回 400 {"error": "Invalid trader_id"}。
/studio/market/twstock/alerts 给 date,或 start/end,或都不给(= 今天,台北时间)。
| 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
datestring · query | 单日:当天生效中的处置,以及当天公告的注意 | 严格 YYYY-MM-DD;不能与 start/end 同时使用 | |
startstring · query | 区间第一天 | 严格 YYYY-MM-DD | 有 stock_id 时为 2001-01-01,否则为 end − 365 天 |
endstring · query | 区间最后一天(含当日) | 严格 YYYY-MM-DD | 今天(start 较晚时改用它) |
kindstring · query | 公告类型 | disposal(处置)、notice(注意) | 两者 |
marketstring · query | 交易所 | twse, tpex | 两者 |
stock_idstring · query | 单一代码;不受 366 天上限限制 | 见本类别共通规则 | 全部 |
区间的意思:处置的期间(start–end)与查询区间有重叠就回传,注意则是公告 date 落在区间内才回传。不带 stock_id 时区间最多 366 天(含头尾),全市场更长的区间要拆开查(一次查一个日历年刚好放得下)。与本类别的默认不同,start/end/date 都会严格验证。
# disposals in force on one daydata = requests.get(f"{BASE_URL}/studio/market/twstock/alerts" , headers=headers, params={"date": "2026-10-13", "kind": "disposal"}, timeout=30).json()["data"]# [..., {"date": "2026-10-12", "stock_id": "5228", "stock_name": "鈺鎧", "market": "tpex",# "kind": "disposal", "count": 2, "start": "2026-10-13", "end": "2026-10-19",# "condition": "連續3個營業日", "measure": "第一次處置", "match_minutes": 2,# "reason": "* 公布日期:115/10/12\n* 證券代號:5228\n…", "close": 59.6, "pe": 29.22},# {"date": "2026-10-12", "stock_id": "2492", "stock_name": "華新科", "market": "twse",# "kind": "disposal", "count": 8, "start": "2026-10-13", "end": "2026-10-19",# "condition": "連續三次", "measure": "第一次處置", "match_minutes": 2,# "reason": "1處置原因:該有價證券之交易,連續三個營業日達本公司「公布注意交易資訊」標準。\n2處置期間:…", "close": None, "pe": None}, ...] # 36 rows# notices announced on one daynotes = requests.get(f"{BASE_URL}/studio/market/twstock/alerts" , headers=headers, params={"date": "2026-10-12", "kind": "notice"}, timeout=30).json()["data"]# [..., {"date": "2026-10-12", "stock_id": "5228", "stock_name": "鈺鎧", "market": "tpex",# "kind": "notice", "count": 15, "start": None, "end": None, "condition": "第一款、第三款、第四款",# "measure": None, "match_minutes": None,# "reason": "最近六個營業日(含當日)累積之最後成交價漲幅達32.63%(第一款)\n…", "close": 59.6, "pe": 29.22}, ...]# one stock's disposal history (no range cap with stock_id)hist = requests.get(f"{BASE_URL}/studio/market/twstock/alerts" , headers=headers, params={"stock_id": "2492", "kind": "disposal", "start": "2001-01-01"}, timeout=30).json()["data"]# 10 rows: 2001-11-23~2001-11-29 收足五成款券 (match_minutes None), 2018-05-08~2018-05-21 第一次處置 (5), …,# 2026-10-13~2026-10-19 第一次處置 (2){"start", "end", "data": [...]};start/end 回显实际采用的区间(送 date 时两者都等于 date)。各列依 date、market、kind、stock_id 排序。每则公告一列。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 公告日 YYYY-MM-DD(处置从下一个交易日起生效) |
stock_id | string | 代码,包含权证、ETF 与可转债(例如 037060、45402) |
stock_name | string | null | 公告上的名称 |
market | string | twse(上市)或 tpex(上柜) |
kind | string | disposal 或 notice |
count | int | 交易所的累计次数(累计/累计次数) |
start, end | string | null | 处置期间,头尾两天都算;注意为 null |
condition | string | null | 处置:公告上的触发条件(連續三次、連續3個營業日、最近十個營業日已有六次 …)。注意:引用的款次(第一款、第五款);没有时为 null |
measure | string | null | 处置类型:第一次處置、第二次處置、再次處置、人工管制撮合、收足五成款券 …;注意与早期 TPEx 的列为 null |
match_minutes | int | null | 处置:从内文读出「约每N分钟撮合一次」的 N。内文没写时(约 2011 年以前的 TWSE 处置内文都是空白,以及不是撮合类的措施)与注意皆为 null |
reason | string | null | 公告全文;交易所没有公布内文时为 null(2011-03 以前的 TWSE 处置都没有)(处置为处置内容,注意为注意交易资讯) |
close, pe | float | null | 公告当时的收盘价与本益比;TWSE 处置一律为 null |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Invalid start date, expected YYYY-MM-DD"}(或 end) | start/end 格式错误 |
| 400 | {"error": "start must not be after end"} | 区间颠倒 |
| 400 | {"error": "Invalid date, expected YYYY-MM-DD"} | date 格式错误 |
| 400 | {"error": "use either date or start/end"} | date 与 start 或 end 同时送出 |
| 400 | {"error": "Invalid stock_id"} | 格式检查未通过 |
| 400 | {"error": "kind must be one of ['disposal', 'notice']"} / {"error": "market must be one of ['twse', 'tpex']"} | 不认得的值 |
| 400 | {"error": "start/end range is <n> days; max 366 (inclusive) without stock_id — split into smaller ranges"} | 不带 stock_id 时区间超过 366 天 |
| 503 | {"error": "Data temporarily unavailable. Please retry shortly."} | 要查的表目前无法提供(48 小时没更新,或读不到),稍后重试,绝不要当成「没有公告」。只检查这次要查的 kind/market 那几张表 |
date 是公告日,start 是生效第一天。要问「D 日是否处置中」,用 date=D(或 start=end=D),不要用公告日。start/end 是公告的期间;期间内遇到休市或暂停交易时,实际结束日会延后,这份数据没有记录。match_minutes 依当时的规则而定(TPEx 从 2026-08-10 起由 5/20 分钟改为 2 分钟),要逐列读,绝不要假设固定值。/studio/market/twstock/batch/<data_type> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
data_typestring · path必填 | 数据集 | price, price_adj, per, institutional, shareholding, foreign_shareholding, financials, balance_sheet, monthly_revenue, ratios, dividend | |
stock_idsstring · query必填 | 代码 | 逗号分隔,≤ 50 | |
startstring · query | 起始日 | YYYY-MM-DD(只有 dividend 会严格验证) | 依 data_type 而定 |
endstring · query | 结束日 | YYYY-MM-DD | 依 data_type 而定 |
payload = requests.get(f"{BASE_URL}/studio/market/twstock/batch/per" , headers=headers, params={"stock_ids": "2330,6182", "start": "2026-08-04", "end": "2026-08-08"}, timeout=120).json()# {"data_type": "per",# "data": {"2330": [{"date": "2026-08-04", "dividend_yield": 0.95, "PER": 31.19, "PBR": 10.21, "stock_id": "2330"}, ...],# "6182": [...]},# "failed": []}{"data_type", "data": {"<stock_id>": [...rows...]}, "failed": [...]}。各列与对应的单股端点完全相同。
failed:服务器端抓取失败的代码(频率限制或上游错误),重试这些。data 与 failed 里都没有的代码,就是真的没有数据。| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "Unsupported data_type '<x>'. Supported: [...]"} | data_type 不对 |
| 400 | {"error": "stock_ids parameter required"} | 缺少 |
| 400 | {"error": "stock_ids exceeds max 50 per request"} | 超过上限 |
| 400 | {"error": "Invalid stock_id in list"} | 有代码格式检查未通过 |
| 400 | {"error": "Invalid start date, expected YYYY-MM-DD"} | 限 dividend |
ratios(财务比率):每个代码的数据列就是 /ratios/<stock_id> 的宽格式季数据("data": {"2330": [{"date": "2026-06-30", "stock_id": "2330", "roe_q": 11.3934, ...}], "2317": [...]})。没有财报的代码(ETF)不会出现在 data 也不会出现在 failed(不回 404);比率数据库还没准备好时,所有代码都会放进 failed(不回 503)。dividend 与 /dividend/<stock_id> 不同:只读已存的数据(不更新);未知代码或没有股利纪录的股票会直接缺席(不回 404);上游配额问题会出现在 failed,而不是回 503。/studio/market/twstock/sector/overview | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
windowint · query | 相对强弱与区间买卖超加总用的交易日数 | 10, 20, 60 | 20 |
body = requests.get(f"{BASE_URL}/studio/market/twstock/sector/overview" , headers=headers, params={"window": 20}, timeout=120).json()# Live capture 2026-11-06 (abridged with ...):# {"date": "2026-11-06",# "summary": {"up": 2, "down": 30, "migrations_today": 3, "foreign_total": -911.9, "foreign_streak": -7,# "trust_total": 266.6, "trust_streak": 19, "margin_change": -423.6, "margin_pctl": 0},# "sectors": [{"slug": "cement", "name": "水泥", "group": "trad", "weight": 0.3,# "returns": {"d1": -1.66, "d5": -4.72, "d10": -1.66, "d20": 4.16, "d60": null, "ytd": null},# "rs": 115.0, "momentum": 112.0, "tail": [[113.1, 97.7], [115.0, 104.2], [115.0, 109.6], [115.0, 112.0]],# "clamped": true, "quadrant": "leading", "migration_days": 4,# "foreign": 4.5, "trust": -0.1, "dealer": 0.3,# "foreign_win": 48.0, "trust_win": 3.7, "dealer_win": 4.3, "foreign_win_prev": 8.4,# "stats": {"rs_up_streak": 2, "foreign_streak": 3, "dealer_streak": 2, "d5_return_pctl_1y": null,# "foreign_buy_days_20d": 15, "foreign_buy_days_pctl_1y": 100}}, ...,# {"slug": "semiconductor", "name": "半導體", "group": "elec", "weight": 55.2,# "returns": {"d1": -4.71, "d5": -12.04, "d10": -14.4, "d20": -20.99, "d60": -11.55, "ytd": 44.86},# "rs": 99.1, "momentum": 100.7, "tail": [[98.0, 100.6], [98.3, 100.5], [98.5, 100.9], [98.9, 100.8]],# "clamped": false, "quadrant": "improving", "migration_days": 6,# "foreign": -662.8, "trust": 135.8, "dealer": 216.8,# "foreign_win": -10057.1, "trust_win": 1402.2, "dealer_win": 865.3, "foreign_win_prev": 1944.2,# "stats": {...}}, ... 32 sectors],# "concentration": {"top3_buy_share": 0.64},# "flow_caps": {"foreign": 320, "trust": 160, "dealer": 30}}leading = [s["name"] for s in body["sectors"] if s["quadrant"] == "leading"]一个对象(没有 data 外层):{"date", "summary", "sectors": [...], "concentration", "flow_caps"}。sectors 是 32 个 TWSE 类股指数,顺序固定。
| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
date | string | — | 类股指数的最新交易日 |
summary.up / summary.down | int | 个板块 | date 当天收涨/收跌的板块数 |
summary.migrations_today | int | 个板块 | date 当天换象限的板块数 |
summary.foreign_total / summary.trust_total | float | 亿元(TWD 100M) | 最新公布日的全市场外资/投信买卖超(官方合计) |
summary.foreign_streak / summary.trust_streak | int | 天 | 连续买超(+N)或卖超(−N)天数 |
summary.margin_change | float | 亿元(TWD 100M) | 最新公布日的全市场融资余额增减 |
summary.margin_pctl | int | 0–100 | margin_change 在过去一年的百分位;历史不满一年时为 null |
sectors[].slug / name / group | string | — | 板块代码(sector/constituents/<slug> 用这个)、中文名称、elec(电子)/fin(金融)/trad(传产) |
sectors[].weight | float | % | 板块市值 ÷ 所有已归板块票的市值 |
sectors[].returns | object | % | d1、d5、d10、d20、d60、ytd 指数报酬(ytd 以前一年最后收盘价为基准) |
sectors[].rs | float | 指数(100 = 加权指数) | window 期间的相对强弱:100 ×(板块收盘 ÷ window 天前的板块收盘)÷(加权指数收盘 ÷ window 天前的加权指数收盘) |
sectors[].momentum | float | 指数(100 = 持平) | 100 + rs 的 5 日变化 |
sectors[].quadrant | string | — | leading(rs ≥ 100,momentum ≥ 100)、weakening(rs ≥ 100,momentum < 100)、lagging(两者都 < 100)、improving(rs < 100,momentum ≥ 100) |
sectors[].migration_days | int | 交易日 | 停留在目前象限的连续交易日数(最多往回看 90 个交易日) |
sectors[].tail | array | — | date 之前 4 天的 [rs, momentum] 数对,由旧到新 |
sectors[].clamped | bool | — | rs、momentum 或 tail 中任一点被截顶时为 true(见备注) |
sectors[].foreign / trust / dealer | float | 亿元(TWD 100M) | date 当天外资/投信/自营商的估计买卖超 |
sectors[].foreign_win / trust_win / dealer_win | float | 亿元(TWD 100M) | 同上,加总最近 window 个交易日 |
sectors[].foreign_win_prev | float | 亿元(TWD 100M) | 再往前 window 天的外资加总 |
sectors[].stats.rs_up_streak | int | 天 | rs 连续上升的天数 |
sectors[].stats.foreign_streak / dealer_streak | int | 天 | 连续买超(+N)/卖超(−N)天数 |
sectors[].stats.d5_return_pctl_1y | int | 0–100 | 5 日报酬在过去一年的百分位 |
sectors[].stats.foreign_buy_days_20d | int | 天 | 最近 20 天中外资买超的天数 |
sectors[].stats.foreign_buy_days_pctl_1y | int | 0–100 | 这个天数在过去一年的百分位 |
concentration.top3_buy_share | float | 0–1 | 当天外资流入板块的正向金额中,前 3 大板块所占的比重 |
flow_caps | object | 亿元(TWD 100M) | {"foreign", "trust", "dealer"}:过去一年板块 20 日买卖超加总的典型规模(P90),用于配色刻度;历史不满一年时为 null |
历史太短或当天还没公布时,任何字段都可能是 null。
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "window must be one of [10, 20, 60]"} | window 不正确 |
| 503 | {"error": "<message>"} | 板块数据尚未就绪 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
summary 的合计是官方的全市场金额,所以不会等于各板块的加总。rs、momentum 与 tail 为了画图会截顶(window 10:88–112,20:85–115,60:78–122;momentum 88–112),有截顶时会设定 clamped。quadrant 与 migration_days 一律用截顶前的数值。foreign/trust/dealer 只会是 date 当天的数值,所以在当天买卖超公布前都是 null。*_win、foreign_win_prev、连续天数与 foreign_buy_days_* 都截止在最新公布买卖超的那天,下午时段可能是前一个交易日。foreign_win/trust_win/dealer_win 都是 null。cement、food、plastic、textile、electric_machinery、wire_cable、chemical、biotech、glass_ceramic、paper、steel、rubber、automobile、semiconductor、computer_peripheral、optoelectronic、communication、electronic_components、electronic_distribution、information_service、other_electronic、construction、shipping、tourism、financial、trading_consumer、oil_gas、green_energy、digital_cloud、sports_leisure、household、other。/studio/market/twstock/sector/breadth | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
daysint · query | 从今天往回算的日历日数 | ≥ 1;超过 730 一律当作 730 | 365 |
body = requests.get(f"{BASE_URL}/studio/market/twstock/sector/breadth" , headers=headers, params={"days": 90}, timeout=120).json()# Live capture 2026-11-06 (abridged with ...):# {"dates": ["2026-08-10", "2026-08-11", "2026-08-12", ..., "2026-11-06"],# "pct_up": [76.7, 46.7, 56.7, ..., 6.2]} # 60 trading days一个对象(没有 data 外层):{"dates": [...], "pct_up": [...]},两个平行数组,每个交易日一个元素,由旧到新。
| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
dates | string[] | — | 交易日(YYYY-MM-DD) |
pct_up | float[] | % | 当天收涨的类股指数占当天有涨跌数字的类股指数比重(多数日子是 32 个;一位小数) |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "days must be an integer"} | 不是整数 |
| 400 | {"error": "days must be positive"} | days < 1 |
| 503 | {"error": "<message>"} | 板块数据尚未就绪 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
/studio/market/twstock/sector/constituents/<slug> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
slugstring · path必填 | 板块 | sector/overview 列出的 32 个板块代码之一 |
body = requests.get(f"{BASE_URL}/studio/market/twstock/sector/constituents/semiconductor" , headers=headers, timeout=60).json()# Live capture 2026-11-06 (abridged with ...):# {"date": "2026-11-06", "total": 116,# "stocks": [{"stock_id": "2330", "name": "台積電", "chg": -4.69, "foreign": -487.7,# "themes": [{"slug": "silicon-photonics-cpo",# "name": {"zh": "矽光子/CPO", "en": "Silicon Photonics / CPO", "cn": "硅光子/CPO"}}]},# {"stock_id": "2454", "name": "聯發科", "chg": -2.02, "foreign": -153.8, "themes": []}, ...,# {"stock_id": "2408", "name": "南亞科", "chg": -4.58, "foreign": 19.3,# "themes": [{"slug": "memory", "name": {"zh": "記憶體", "en": "Memory", "cn": "存储器"}}]}, ... 5 rows]}一个对象(没有 data 外层):{"date", "total", "stocks": [...]}。stocks 是该板块市值最大的 5 档成分股,由大到小。
| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
date | string | — | 价格的交易日 |
total | int | 档 | 板块的成分股档数 |
stocks[].stock_id / name | string | — | 代码、名称 |
stocks[].chg | float | % | date 当天涨跌幅 |
stocks[].foreign | float | 亿元(TWD 100M) | date 当天外资的估计买卖超(净买卖股数 × 收盘价) |
stocks[].themes | array | — | [{"slug", "name"}] 这档股票所属的概念股题材,name = {"zh", "en", "cn"};没有时为 [] |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 404 | {"error": "Unknown sector slug"} | slug 不在那 32 个之内 |
| 503 | {"error": "No recent market price data available"} | 最近 7 天没有公布的价格 |
| 503 | {"error": "Upstream rate limit. Please retry shortly."} | 上游配额耗尽 |
chg 与 foreign 为 null。市值还没公布的日子,那 5 档改依代码排序。/studio/market/twstock/theme/overview | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
windowint · query | 区间买卖超加总用的交易日数 | 10, 20, 60 | 20 |
body = requests.get(f"{BASE_URL}/studio/market/twstock/theme/overview" , headers=headers, params={"window": 20}, timeout=60).json()# Live capture 2026-11-06 (abridged with ...):# {"date": "2026-11-06", "list_ym": "2026-10", "first_ym": "2026-10", "list_age_days": 24, "stale_months": 1,# "pctl_includes_backfill": true,# "summary": {"up": 0, "down": 6, "top": {"slug": "ai", "d20": -20.32},# "bottom": {"slug": "pcb-abf-substrate", "d20": -38.51},# "foreign_top": {"slug": "ai", "foreign_win": -70.1, "foreign_win_ex_top": 40.4, "top_name": "鴻海"}},# "themes": [{"slug": "ai", "name": {"zh": "AI", "en": "AI", "cn": "AI"}, "count": 12, "snapshot_ym": "2026-10",# "indexable": true,# "returns": {"d1": -4.84, "d5": -13.88, "d10": -17.83, "d20": -20.32, "d60": -13.27, "ytd": 24.78},# "returns_backfill": {"d1": false, "d5": false, "d10": false, "d20": true, "d60": true, "ytd": true},# "foreign": -43.3, "trust": 20.0, "dealer": 22.7,# "foreign_win": -70.1, "trust_win": -76.2, "dealer_win": 123.3, "foreign_win_prev": -716.1,# "foreign_win_ex_top": 40.4, "foreign_buy_members": 4,# "top": {"stock_id": "2317", "name": "鴻海", "mv_share": 40.0},# "top5": [{"stock_id": "2317", "name": "鴻海"}, {"stock_id": "2382", "name": "廣達"}, ...],# "stats": {"foreign_streak": -4, "dealer_streak": 6, "d5_return_pctl_1y": 0,# "foreign_buy_days_20d": 8, "foreign_buy_days_pctl_1y": 52}}, ... 6 themes],# "flow_caps": {"foreign": 1480, "trust": 430, "dealer": 180}}一个对象(没有 data 外层):{"date", "list_ym", "first_ym", "list_age_days", "stale_months", "pctl_includes_backfill", "summary", "themes": [...], "flow_caps"}。
| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
date | string | — | 题材指数的最新交易日 |
list_ym | string | — | 最新一期题材名单的月份,YYYY-MM |
first_ym | string | — | 所有题材中最早一期名单的月份 |
list_age_days / stale_months | int | 天/月 | 最新名单的新旧:生效后经过的天数、距名单月份的月数 |
pctl_includes_backfill | bool | — | 某个百分位的一年历史往前跨过名单生效日时为 true |
summary.up / summary.down | int | 个题材 | date 当天上涨/下跌的题材数 |
summary.top / summary.bottom | object | % | {"slug", "d20"}:20 日报酬最好与最差的题材 |
summary.foreign_top | object | 亿元(TWD 100M) | {"slug", "foreign_win", "foreign_win_ex_top", "top_name"}:扣掉最大权值股后,外资买超最多的题材 |
themes[].slug | string | — | 题材代码(其他题材端点用这个) |
themes[].name | object | — | {"zh", "en", "cn"} |
themes[].count | int | 档 | 目前名单的成分股数(不含已下市) |
themes[].snapshot_ym | string | — | 该题材目前名单的月份 |
themes[].indexable | bool | — | 题材至少有 5 档成分股、且名单生效不超过 90 天时为 true |
themes[].returns | object | % | 题材指数的 d1、d5、d10、d20、d60、ytd 报酬 |
themes[].returns_backfill | object | — | 键相同,该报酬的起点早于题材第一期名单生效日时为 true |
themes[].foreign / trust / dealer | float | 亿元(TWD 100M) | date 当天成分股的估计买卖超;当天买卖超公布前为 null |
themes[].foreign_win / trust_win / dealer_win | float | 亿元(TWD 100M) | 同上,加总最近 window 个交易日 |
themes[].foreign_win_prev | float | 亿元(TWD 100M) | 再往前 window 天的外资加总 |
themes[].foreign_win_ex_top | float | 亿元(TWD 100M) | 扣掉最大成分股本身外资买卖超后的 foreign_win |
themes[].foreign_buy_members | int | 档 | 区间内外资买卖超加总为正的成分股数 |
themes[].top | object | % | {"stock_id", "name", "mv_share"}:最大成分股与它占题材市值的比重,以名单生效日计算 |
themes[].top5 | array | — | [{"stock_id", "name"}]:名单生效日市值最大的 5 档成分股 |
themes[].stats | object | — | foreign_streak、dealer_streak(±天数)、d5_return_pctl_1y、foreign_buy_days_20d、foreign_buy_days_pctl_1y:意义同 sector/overview |
flow_caps | object | 亿元(TWD 100M) | {"foreign", "trust", "dealer"}:题材 20 日买卖超加总的典型规模(P90),用于配色刻度;买卖超历史不满一年时为 null |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "window must be one of [10, 20, 60]"} | window 不正确 |
| 503 | {"error": "not_yet_effective"} | 还没有任何题材名单生效 |
theme/constituents/<slug>)。目前的代码:ai、silicon-photonics-cpo、memory、pcb-abf-substrate、thermal-cooling、robotics。returns_backfill 会标出来。*_win、连续天数与 foreign_buy_days_* 都截止在最新公布买卖超的那天,下午时段可能是前一个交易日。themes 中移除。/studio/market/twstock/theme/constituents/<slug> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
slugstring · path必填 | 题材 | theme/overview 里的题材代码 |
body = requests.get(f"{BASE_URL}/studio/market/twstock/theme/constituents/memory" , headers=headers, timeout=60).json()# Live capture 2026-11-06 (abridged with ...):# {"date": "2026-11-06", "slug": "memory", "status": "active", "snapshot_ym": "2026-10",# "published_at": "2026-10-14", "effective_date": "2026-10-15", "first_ym": "2026-10",# "list_age_days": 24, "stale_months": 1, "count": 9, "indexable": true, "gated": false,# "name": {"zh": "記憶體", "en": "Memory", "cn": "存储器"},# "intro": {"zh": "記憶體概念股是做 DRAM 與 Flash 等記憶體的公司,…", "en": "Memory stocks make DRAM, flash and other memory, …", "cn": "…"},# "changes": {"added": [], "removed": [], "prev_ym": null}, "related": [],# "stocks": [{"stock_id": "2408", "name": "南亞科", "market": "twse", "sector_slug": "semiconductor",# "chg": -4.58, "foreign": 19.32, "ret20": -34.57, "rev_yoy": 487.73, "roe": 61.61,# "foreign_share_chg_20d": -2.39, "disposal": false, "delisted": false, "last_trade_date": null,# "also": [],# "reason": {"zh": "DRAM 製造,產品含 DDR5、LPDDR5/5X 與 DDR4",# "en": "Manufactures DRAM, including DDR5, LPDDR5/5X and DDR4", "cn": "…"},# "sources": [{"kind": "filing", "date": "2026-10-12",# "label": {"en": "Nanya Technology investor conference slides, 2026-10-12", ...},# "url": "https://mopsov.twse.com.tw/nas/STR/240820261012M001.pdf"}, ...]}, ... 9 rows]}一个对象(没有 data 外层)。
| 字段 | 类型 | 说明 |
|---|---|---|
date | string | 个股数字的交易日 |
slug, status | string | 题材代码、active |
name / intro | object | {"zh", "en", "cn"} 题材名称/一段说明 |
snapshot_ym | string | 目前名单的月份 |
published_at / effective_date | string | 名单公布日/生效日 |
first_ym | string | 题材第一期名单的月份 |
list_age_days / stale_months | int | 名单生效后经过的天数/距名单月份的月数 |
count | int | 成分股数,不含已下市 |
indexable | bool | 至少 5 档成分股、且名单生效不超过 90 天时为 true |
changes | object | {"added", "removed", "prev_ym"}:相较上一期名单新增/移除的股票代码(第一期名单的 prev_ym 为 null) |
related | array | [{"slug", "overlap"}]:最多 3 个有共同成分股的其他题材,共同成分股最多的排前面 |
gated | bool | API 密钥一律是 false |
stocks[].stock_id / name | string | 代码、名称 |
stocks[].market | string | twse 或 tpex |
stocks[].sector_slug | string | 依产业类别对应的板块代码,同 sector/overview(含上柜股票);对应不到时为 null |
stocks[].chg | float | date 当天涨跌幅 % |
stocks[].foreign | float | date 当天外资的估计买卖超,亿元(TWD 100M);当天买卖超公布前为 null |
stocks[].ret20 | float | 还原权息的 20 个交易日报酬,% |
stocks[].rev_yoy | float | 最新月营收年增率,% |
stocks[].roe | float | 近四季 ROE,% |
stocks[].foreign_share_chg_20d | float | 20 个交易日内外资持股比率的变化,百分点 |
stocks[].disposal | bool | 今天处于处置期间 |
stocks[].delisted / last_trade_date | bool / string | 名单建立后已下市,以及最后交易日(否则为 null) |
stocks[].also | string[] | 同样包含这档股票的其他题材 |
stocks[].reason | object | {"zh", "en", "cn"} 这档股票列入题材的理由 |
stocks[].sources | array | [{"kind", "label", "url", "date"}]:理由的公开来源;kind 为 filing 或 news,label 为 {"zh", "en", "cn"} |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 404 | {"error": "Unknown theme"} | 没有这个代码 |
| 410 | {"error": "Theme retired", "retired": true} | 题材已停用 |
| 503 | {"error": "not_yet_effective"} | 题材名单尚未生效 |
stocks(排在最后),标 delisted: true;count 不算它们。rev_yoy、roe 与 foreign_share_chg_20d 在某档股票缺该数字时,会各自独立为 null。/studio/market/twstock/theme/<slug>/index | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
slugstring · path必填 | 题材 | theme/overview 里的题材代码 | |
rangestring · query | 截止在最新一天的日历区间(92/366/1,096 天) | 3m, 1y, 3y | 3m |
body = requests.get(f"{BASE_URL}/studio/market/twstock/theme/memory/index" , headers=headers, params={"range": "3y"}, timeout=60).json()# Live capture 2026-11-06 (abridged with ...):# {"slug": "memory", "range": "3y", "base_date": "2026-10-14", "first_ym": "2026-10",# "points": [{"date": "2023-11-06", "value": 19.82, "taiex": 31.86, "tpex": 48.39, "is_backfill": true,# "n": 9, "snapshot_ym": "2026-10"}, ...,# {"date": "2026-10-14", "value": 100.0, "taiex": 100.0, "tpex": 100.0, "is_backfill": true, "n": 9,# "snapshot_ym": "2026-10"}, ...,# {"date": "2026-11-06", "value": 79.89, "taiex": 81.65, "tpex": 72.37, "is_backfill": false,# "n": 9, "snapshot_ym": "2026-10"}]} # 728 points一个对象(没有 data 外层):{"slug", "range", "base_date", "first_ym", "points": [...]},点由旧到新。
| 字段 | 类型 | 说明 |
|---|---|---|
base_date | string | 指数为 100 的那天(题材第一期名单生效前一个交易日) |
first_ym | string | 题材第一期名单的月份 |
points[].date | string | 交易日 |
points[].value | float | 题材指数,base_date 为 100 |
points[].taiex / tpex | float | 加权指数/柜买指数的报酬指数,在 base_date 重设为 100,方便比较 |
points[].is_backfill | bool | 题材第一期名单生效前为 true(成分股取自第一期名单) |
points[].n | int | 当天指数内的成分股数 |
points[].snapshot_ym | string | 成分股所属名单的月份 |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "range must be one of ['3m', '1y', '3y']"} | range 不正确 |
| 404 | {"error": "Unknown theme"} | 没有这个代码 |
| 410 | {"error": "Theme retired", "retired": true} | 题材已停用 |
| 503 | {"error": "not_yet_effective"} | 题材名单尚未生效 |
value 除以 taiex(或 tpex)。/studio/market/twstock/chip_breadth/<scope> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
scopestring · path必填 | 分组类型 | theme, sector | |
windowint · query | 买卖超加总的交易日数 | 10, 20, 60 | 20 |
inststring · query | 分组排名依据的法人 | foreign, trust | foreign |
body = requests.get(f"{BASE_URL}/studio/market/twstock/chip_breadth/sector" , headers=headers, params={"window": 20, "inst": "foreign"}, timeout=60).json()# Live capture 2026-11-06 (abridged with ...):# {"scope": "sector", "window": 20, "inst": "foreign", "as_of": "2026-11-06", "min_group": 6,# "baseline": {"universe": "twse",# "foreign": {"buy": 648, "total": 1091, "ratio": 59.395050412465636},# "trust": {"buy": 271, "total": 1091, "ratio": 24.839596700274978}},# "groups": [{"slug": "trading_consumer", "name": "貿易百貨", "total": 21,# "foreign": {"buy": 20, "ratio": 95.23809523809523, "gap": 36, "rank": 1},# "trust": {"buy": 4, "ratio": 19.047619047619047, "gap": -6, "rank": 16}},# {"slug": "shipping", "name": "航運", "total": 28,# "foreign": {"buy": 24, "ratio": 85.71428571428571, "gap": 26, "rank": 2},# "trust": {"buy": 7, "ratio": 25.0, "gap": 0, "rank": 12}}, ... 31 groups],# "excluded": [{"slug": "glass_ceramic", "name": "玻璃陶瓷", "total": 5}],# "sources": {"institutional": {"zh": "臺灣證券交易所", "en": "TWSE", "cn": "台湾证券交易所"}}}一个对象(没有 data 外层):{"scope", "window", "inst", "as_of", "min_group", "baseline", "groups": [...], "excluded": [...], "sources"}。
| 字段 | 类型 | 说明 |
|---|---|---|
as_of | string | 买卖超区间的最后一天 |
min_group | int | 计入股票数少于此值的分组不排名(6) |
baseline.universe | string | 分组拿来比较的市场:板块用 twse,题材用 twse+tpex |
baseline.foreign / baseline.trust | object | {"buy", "total", "ratio"}:该市场在区间内买超的普通股数、计入的总数,以及比重 % |
groups[].slug / name | — | 分组代码;板块的 name 是字符串,题材的是 {"zh", "en", "cn"} |
groups[].total | int | 分组内计入的股票数 |
groups[].foreign / groups[].trust | object | {"buy", "ratio", "gap", "rank"}:买超的股票数、比重 %、比重减去基准比重的百分点(整数),以及依比重的排名 |
excluded | array | [{"slug", "name", "total"}]:低于 min_group 的分组 |
sources.institutional | object | 买卖超数据来源交易所的 {"zh", "en", "cn"} 名称 |
groups 依 inst 的排名排序;两种法人的排名都一定会有。
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "window must be one of [10, 20, 60]"} | window 不正确 |
| 400 | {"error": "inst must be one of ['foreign', 'trust']"} | inst 不正确 |
| 404 | {"error": "Unknown scope"} | scope 不是 theme/sector |
| 503 | {"error": "not_yet_effective"} | theme:还没有题材名单生效 |
| 503 | {"error": "Data temporarily unavailable. Please retry shortly."} | 上游额度用完,或取不到股票与板块的对照表 |
sector/overview 的 32 个 TWSE 板块(只有上市);题材是 theme/overview 的名单(上市+上柜),所以两者的基准不同。gap 依精确分数四舍五入,刚好一半时往远离零的方向进位。/studio/market/twstock/chip_breadth/<scope>/<slug> | 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
scopestring · path必填 | 分组类型 | theme, sector | |
slugstring · path必填 | 类别 | 板块代码(sector/overview)或题材代码(theme/overview) | |
windowint · query | 买卖超加总的交易日数 | 10, 20, 60 | 20 |
body = requests.get(f"{BASE_URL}/studio/market/twstock/chip_breadth/theme/memory" , headers=headers, params={"window": 20}, timeout=60).json()# Live capture 2026-11-06 (abridged with ...):# {"scope": "theme", "window": 20, "as_of": "2026-11-06", "price_as_of": "2026-11-06", "min_group": 6,# "baseline": {"universe": "twse+tpex",# "foreign": {"buy": 1106, "total": 1983, "ratio": 55.77407967725668},# "trust": {"buy": 333, "total": 1983, "ratio": 16.792738275340394}},# "slug": "memory", "ranked": true,# "group": {"slug": "memory", "name": {"zh": "記憶體", "en": "Memory", "cn": "存储器"}, "total": 9,# "foreign": {"buy": 1, "ratio": 11.11111111111111, "gap": -45, "rank": 5},# "trust": {"buy": 5, "ratio": 55.55555555555556, "gap": 39, "rank": 4}},# "stocks": [{"stock_id": "2408", "name": "南亞科", "market": "twse", "foreign": "sell", "trust": "sell",# "foreign_20d": -380.2, "market_cap": 11851.46, "ret_20d": -34.57, "themes": [],# "disposal": false, "notice": false},# {"stock_id": "2344", "name": "華邦電", "market": "twse", "foreign": "sell", "trust": "sell",# "foreign_20d": -35.0, "market_cap": 5688.19, "ret_20d": -32.11, "themes": [],# "disposal": false, "notice": false}, ... 9 rows],# "excluded_count": 0, "alerts_available": true,# "sources": {"institutional": {"zh": "臺灣證券交易所、證券櫃檯買賣中心", "en": "TWSE, TPEx", ...},# "alerts": {"zh": "金融監督管理委員會證券期貨局", "en": "Securities and Futures Bureau, FSC", ...}}}一个对象(没有 data 外层):排名的 scope、window、as_of、min_group 与 baseline,另外加上:
| 字段 | 类型 | 说明 |
|---|---|---|
price_as_of | string | 价格与报酬截止的那天 |
slug | string | 类别 |
group | object | 该分组在排名里的那一列(没有排名时不带 rank) |
ranked | bool | 分组低于 min_group 时为 false |
stocks[].stock_id / name / market | string | 代码、名称、twse/tpex |
stocks[].foreign / trust | string | 区间内为 buy、sell 或 flat |
stocks[].foreign_<N>d | float | 区间内外资的估计买卖超,亿元(TWD 100M);<N> = window |
stocks[].market_cap | float | 亿元(TWD 100M) |
stocks[].ret_<N>d | float | 区间报酬,%(有还原数据时为还原权息报酬) |
stocks[].themes | array | [{"slug", "name"}] 包含这档股票的所有题材(scope 为 theme 时不列出所查的题材),name = {"zh", "en", "cn"} |
stocks[].disposal / notice | bool | as_of 当天处于处置期间/有注意股公告;取不到该数据时为 null |
excluded_count | int | 没有计入的成分股数(非普通股或没有买卖超数字) |
alerts_available | bool | 读不到处置/注意股数据时为 false |
sources | object | {"institutional", "alerts"},各为 {"zh", "en", "cn"} |
stocks 只放计入的成分股(长度等于 group.total),依市值由大到小。
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "window must be one of [10, 20, 60]"} | window 不正确 |
| 404 | {"error": "Unknown scope"} | scope 不是 theme/sector |
| 404 | {"error": "Unknown group"} | 该分组类型下没有这个代码 |
| 410 | {"error": "Theme retired", "retired": true} | 题材已停用 |
| 503 | {"error": "not_yet_effective"} | 题材名单尚未生效 |
| 503 | {"error": "Data temporarily unavailable. Please retry shortly."} | 上游额度用完,或取不到股票与板块的对照表 |
disposal/notice 以 as_of 判断:处置期间涵盖当天、注意股公告在当天发布。/studio/market/twstock/screener/run JSON 请求本文(用 json= 送出;其他格式的本文一律回 400)。每个字段都可省略;{} 会回传市值最大的 300 档普通股。
| 名称 | 说明 | 可用值 | 默认 |
|---|---|---|---|
filtersarray · body | 条件,格式见下方 | ≤ 40 个条件,全部符合才算(AND) | [] |
include_typesstring[] · body | 在默认的普通股范围之外,加入这些证券类型 | etf、etn、reit、preferred、dr 的子集合 | [] |
sortobject · body | rows 的排序;null 值排在最后 | indicator = 下方任一数值键;dir = asc/desc | {"indicator": "market_cap", "dir": "desc"} |
limitint · body | 回传的列数(total 仍计算所有符合的股票) | 1–300 | 300 |
filters 的条件格式:
| 条件 | 格式 | 符合的股票 |
|---|---|---|
| 数值 | {"indicator": "per", "operator_id": 4, "value": 15} | operator_id 1 >、2 <、3 ≥、4 ≤;值为 null 时不会符合 |
| 市场 | {"indicator": "market", "op": "in", "values": ["twse"]} | op = in/not_in;值为 twse(上市)、tpex(上柜) |
| 产业 | {"indicator": "industry", "op": "in", "values": ["24", "28"]} | 交易所产业代码(见备注) |
| 题材 | {"indicator": "theme", "op": "not_in", "values": ["ai"]} | 概念股题材代码(见备注) |
| 排除 | {"indicator": "exclude", "values": ["disposal", "notice"]} | 排除今天处于处置期间的处置股,以及自快照日起公告的注意股 |
集合条件接受 1–50 个 values。未知的指标、运算子或值一律回 400,不会默默略过。
数值指标(也是每一列的数值字段):
| Key | 单位 | 说明 |
|---|---|---|
per | × | 本益比:收盘价 ÷ 近四季 EPS,采交易所公布值;亏损公司为 null |
pbr | × | 股价净值比:收盘价 ÷ 最新每股净值,采交易所公布值;交易所没有公布时(股价净值比 ≤ 0)为 null |
dividend_yield | % | 近一年现金股利 ÷ 收盘价,采交易所公布值;超过 50% 时为 null(无法比较) |
roe_ttm | % | 近四季税后净利 ÷ 平均股东权益 |
gross_margin_q / operating_margin_q | % | 最新一季;金融业不公布 |
eps_ttm | 元 | 最近四季加总 |
rev_yoy | % | 最新公布月份营收相较去年同月 |
market_cap | 亿元(TWD 100M) | 收盘价 × 流通在外股数 |
turnover_20d | 亿元(TWD 100M) | 最近 20 个交易日的平均每日成交金额 |
close | 元 | 最新收盘价 |
ret_5d / ret_20d / ret_60d | % | 5/20/60 个交易日的还原权息报酬 |
foreign_5d / foreign_20d / foreign_60d | 亿元(TWD 100M) | 5/20/60 个交易日的外资估计买卖超(每日净买卖股数 × 当日收盘价);正值 = 买超 |
trust_5d / trust_20d / trust_60d | 亿元(TWD 100M) | 投信的同一数字 |
cond = { "filters": [ {"indicator": "dividend_yield", "operator_id": 3, "value": 5}, {"indicator": "per", "operator_id": 4, "value": 15}, {"indicator": "market_cap", "operator_id": 3, "value": 300}, {"indicator": "exclude", "values": ["disposal", "notice"]}, ], "sort": {"indicator": "dividend_yield", "dir": "desc"}, "limit": 50,}body = requests.post(f"{BASE_URL}/studio/market/twstock/screener/run" , headers=headers, json=cond, timeout=60).json()# Live capture 2026-11-06 (abridged with ...):# {"as_of": "2026-11-06",# "dates": {"price": "2026-11-06", "per": "2026-11-06", "market_cap": "2026-11-06", "flows": "2026-11-06"},# "total": 42,# "columns": [{"key": "close", "name": {"zh": "收盤", "en": "Close"}, "value_format": "twd",# "value_decimals": 2, "signed": false, "colored": false, "family": null, "window": null,# "filtered": false},# {"key": "per", "name": {"zh": "本益比", "en": "P/E"}, "value_format": "x", "value_decimals": 1,# "signed": false, "colored": false, "family": null, "window": null, "filtered": true}, ... 7 columns],# "sort": {"indicator": "dividend_yield", "dir": "desc"},# "rows": [{"stock_id": "2542", "name": "興富發", "market": "twse", "sec_type": "common", "industry": "14",# "fin_quarter": "2026Q2", "rev_month": "2026-09", "adj": true, "themes": [],# "disposal": false, "notice": false,# "close": 37.75, "per": 8.74, "pbr": 1.61, "dividend_yield": 10.6, "roe_ttm": 20.583,# "gross_margin_q": 31.8475, "operating_margin_q": 25.3319, "eps_ttm": 4.32, "rev_yoy": 103.7265,# "market_cap": 812.789, "turnover_20d": 3.4225,# "ret_5d": -3.9452, "ret_20d": -1.1936, "ret_60d": -6.5688,# "foreign_5d": 3.2337, "foreign_20d": 25.2619, "foreign_60d": 24.2922,# "trust_5d": 0.3288, "trust_20d": -2.7693, "trust_60d": 16.1917}, ... 42 rows]}ids = [r["stock_id"] for r in body["rows"]]一个对象(没有 data 外层)。
| 字段 | 类型 | 说明 |
|---|---|---|
as_of | string | 快照的交易日 |
dates | object | 各数据的截止日:price、per、market_cap、flows(flows 可能比 as_of 早一天) |
total | int | 套用 limit 前的符合数 |
columns | array | 结果表的字段:默认字段(close、per、pbr、dividend_yield、roe_ttm、rev_yoy、market_cap)加上所有被筛选或排序的指标。每栏有 key、name({"zh", "en"})、value_format(x/pct/twd/twd_100m)、value_decimals、signed、colored、family、window、filtered |
sort | object | 实际套用的排序 |
rows[].stock_id / name | string | 代码、名称 |
rows[].market | string | twse 或 tpex(这里是小写) |
rows[].sec_type | string | common, etf, etn, reit, preferred, dr |
rows[].industry | string | 交易所的产业代码;交易所没有给时为 null |
rows[].fin_quarter | string | 比率字段依据的季别,例如 2026Q2(财报公布期间各股可能不同) |
rows[].rev_month | string | rev_yoy 依据的月份,例如 2026-09 |
rows[].adj | bool | 报酬无法还原权息时为 false |
rows[].themes | string[] | 这档股票所属的题材代码 |
rows[].disposal / notice | bool | 今天处于处置期间/自 as_of 起有注意股公告;取不到该数据时为 null |
rows[].<numeric key> | float | 上述所有数值指标,四舍五入到 4 位小数;缺值时为 null |
| 状态码 | 回应内容 | 情况 |
|---|---|---|
| 400 | {"error": "<what is wrong>"} | 本文不合法,例如 "body must be a JSON object"、"limit must be an integer 1–300"、"unknown indicator 'pe'" |
| 503 | {"error": "Data temporarily unavailable. Please retry shortly."} | 快照尚未就绪 |
| 503 | {"error": "themes_unavailable", "message": "..."} | 题材名单尚未生效时用了 theme 条件:拿掉它或稍后再试 |
| 503 | {"error": "alerts_unavailable", "message": "..."} | 注意股/处置数据取不到时用了 exclude 条件:拿掉它或稍候再试 |
include_types 加入。dates。market 是小写(twse/tpex),跟 market_value/all(TWSE/TPEx)不同。01 水泥工业、02 食品工业、03 塑胶工业、04 纺织纤维、05 电机机械、06 电器电缆、08 玻璃陶瓷、09 造纸工业、10 钢铁工业、11 橡胶工业、12 汽车工业、14 建材营造、15 航运业、16 观光餐旅、17 金融保险、18 贸易百货、19 综合、20 其他、21 化学工业、22 生技医疗、23 油电燃气、24 半导体、25 电脑及周边设备、26 光电、27 通信网络、28 电子零组件、29 电子通路、30 资讯服务、31 其他电子、32 文化创意、33 农业科技、34 电子商务、35 绿能环保、36 数位云端、37 运动休闲、38 居家生活、91 存托凭证。ai、silicon-photonics-cpo(矽光子/CPO)、memory(记忆体)、pcb-abf-substrate(PCB/ABF 载板)、thermal-cooling(散热)、robotics(机器人)。per 是 null,所以 per < 10 不会选到它们;空值不会符合任何数值条件。