台股 API

40 个端点 · 行情 · 基本面 · 筹码面 · 其他 · 板块与题材 · 选股器

最后更新 2026-11
Base URL
https://api.blave.org
认证
每个请求都要带 api-key 与 secret-key 请求头
权限
API plan or Blave Agent plan
频率限制
每组密钥、每个 IP 各 5 分钟 500 次

通用规则

  • stock_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 档);不要拿单股端点对整个股票池跑循环。

台股清单

GET/studio/market/twstock/list
数据起始
快照(目前上市柜的证券)
更新频率
服务器缓存 24 小时

参数

无。

范例

Python
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_idstring代码
namestring名称
closefloat | null最新日收盘价(上游没有数据时为 null,例如暂停交易)
marketstringTWSE(上市)或 TPEx(上柜)
industry_codestring | nullTWSE/TPEx 原始的数字产业别代码,原样传回(不解码)。ETF/非公司型证券为 null。常见代码:15 航运业、17 金融保险业、22 生技医疗业、24 半导体业、25 电脑及周边设备业、26 光电业、27 通信网络业、28 电子零组件业、29 电子通路业、30 资讯服务业、31 其他电子业
listing_datestring | nullYYYY-MM-DD;ETF/非公司型证券为 null

错误

只有共用错误(两个市场都失败时回 500)。

备注

  • 用来建立股票池。抽样时要分散到各产业:代码依产业分段,用 [:N] 截断会集中在少数几个产业。
  • 清单明显少于约 2,400 档,代表其中一个市场加载失败,应视为数据不完整,不是下市。
  • 其中一个市场加载失败时,服务器缓存缩短为 10 分钟。

个股基本信息

GET/studio/market/twstock/info/<stock_id>
数据起始
快照
更新频率
服务器缓存 24 小时

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则

范例

Python
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 共用同一份缓存。

台股日K(原始)

GET/studio/market/twstock/price/<stock_id>
数据起始
1994-10-01
更新频率
每日,台北时间约 14:00

参数

名称说明可用值默认
stock_id
string · path必填
上市或上柜股票/ETF 代码英文字母/数字(可含点),≤ 8 字符,例如 2330、0050、00878、006208
start
string · query
起始日,含当日YYYY-MM-DD完整历史
end
string · query
结束日,含当日YYYY-MM-DD最新一天

范例

Python
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 由旧到新排序。

字段类型单位说明
datestringYYYY-MM-DD交易日
stock_idstring—股票代码
open / high / low / closefloat元未还原价格
spreadfloat元与前一日收盘价的差额
volumeint股成交股数
turnover_valueint元成交金额
turnover_countint笔成交笔数

错误

状态码回应内容情况
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 档),不要对这个端点跑循环。
  • 最早提供到 1994-10-01;较晚上市的代码起始日较晚。
  • 当日那一列取自 TWSE/TPEx 官方收盘档,在公布后出现(台北时间约 14:00)。
  • 服务器缓存:5 分钟。

台股日K(还原)

GET/studio/market/twstock/price_adj/<stock_id>
数据起始
1994-10-01(同 /price)
更新频率
每日

参数

同 /price/<stock_id>。

范例

Python
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 序列有新数据时重建。
  • 服务器缓存:5 分钟。

即时报价

GET/studio/market/twstock/quote/<stock_id>
数据起始
只有快照,没有历史
更新频率
约每 10 秒

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则

范例

Python
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 / closefloat今日至今的 OHLC
change_price / change_ratefloat与前一日收盘价的涨跌(元/%)
average_pricefloat成交均价
volumeint最新一笔的成交量
total_volumeint今日累计成交量
amount / total_amountfloat最新一笔/累计成交金额
yesterday_volumeint前一日成交量
buy_price / buy_volumefloat / int最佳买价
sell_price / sell_volumefloat / int最佳卖价
volume_ratiofloat量比
quote_timestringYYYY-MM-DD HH:MM:SS,是完整时间戳,不像其他端点只有 date
stock_idstring代码
tick_typeint0 无法判断、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."}上游配额耗尽

备注

  • 只用来盘中看价:没有历史,不能拿来回测。
  • 服务器缓存:10 秒。

即时报价(批次)

GET/studio/market/twstock/quote
数据起始
只有快照,没有历史
更新频率
约每 10 秒

参数

名称说明可用值默认
stock_ids
string · query必填
代码逗号分隔,≤ 50 档

范例

Python
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."}上游配额耗尽

备注

  • 服务器缓存:10 秒。

即时报价(全市场)

GET/studio/market/twstock/quote/all
数据起始
只有快照,没有历史
更新频率
约每 10 秒

参数

无。

范例

Python
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."}上游配额耗尽

备注

  • 服务器缓存:10 秒。

现股分线

GET/studio/market/twstock/minute/ohlcv/<stock_id>/<schema>
数据起始
2019-01(逐档回补)
更新频率
盘中即时 K 棒;收盘后以官方数据修正

参数

名称说明可用值默认
stock_id
string · path必填
代码目前上市柜的 TWSE/TPEx 代码,或 TAIEX(加权指数)
schema
string · path必填
K 棒周期1m, 5m, 15m, 30m, 60m, 1d
start
string · query
起始日YYYY-MM-DDend − 该周期的最大区间
end
string · query
结束日(含当日)YYYY-MM-DD今天(UTC)
adjust
string · query
1 = 还原(后复权)OHLC,因子同 /price_adj;volume 一律不还原0, 1, true, false0

每次请求的最大区间(end − start):1m 31 天 · 5m 62 天 · 15m 93 天 · 30m 186 天 · 60m 365 天 · 1d 3650 天。

范例

Python
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": [...]}.

字段类型单位说明
tsstringUTC ISO 格式K 棒开始时间(以分钟起点标记);台北时间 13:30 那根是收盘集合竞价
open / high / low / closefloat元价格
volumeint张,不是股成交量。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 但取不到还原因子:绝不会默默改给未还原数据

备注

  • 涵盖范围随查询扩充:任何上市柜股票都可以查;第一次查询会先补近 30 天左右的数据,并把这档列入即时追踪,之后再回补完整历史(2019-01 起)。要查好几年的历史前,先看 minute/ohlcv/symbols。
  • 区间内没有数据时回 200 与 []。
  • 还在形成中的 K 棒不会回传;要即时价格用 /quote/<stock_id>。
  • 长区间请切成多段,每段都在该周期的上限内。

现股分线覆盖清单

GET/studio/market/twstock/minute/ohlcv/symbols
数据起始
快照
更新频率
即时

参数

无。

范例

Python
covered = requests.get(f"{BASE_URL}/studio/market/twstock/minute/ohlcv/symbols", headers=headers, timeout=30).json()["data"]

回应

{"data": ["2330", "TAIEX", ...]}:已经有分钟线数据的代码(目前上市柜的股票加上 TAIEX),已排序。

错误

只有共用错误。

分K(旧版)

GET/studio/market/twstock/kbar/<stock_id>
数据起始
2019-01-01
更新频率
区间含今天时服务器缓存 60 秒,否则 5 分钟

参数

名称说明可用值默认
stock_id
string · path必填
代码目前上市柜的 TWSE/TPEx 代码,或 TAIEX
start
string · query
起始日YYYY-MM-DD今天 − 6 天
end
string · query
结束日;end − start ≤ 31 天YYYY-MM-DD今天

范例

Python
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": [...]},由旧到新。

字段类型说明
datestringYYYY-MM-DD(台北时间)
minutestringHH:MM:SS 台北时间,K 棒开始时间(09:00–13:30)
stock_idstring代码
open / high / low / closefloat元
volumeint张

错误

状态码回应内容情况
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。上市柜股票没有分钟数据时回 [](这个端点不会触发回补)。
  • 今天的 K 棒是盘中暂定数据,台北时间约 16:10 后由官方数据取代。
  • 只有 minute/ohlcv/symbols 涵盖的代码有数据。

市值

GET/studio/market/twstock/market_value/<stock_id>
数据起始
2004-01-01
更新频率
每日

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD完整历史
end
string · query
结束日YYYY-MM-DD最新

范例

Python
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 上游配额耗尽。

备注

  • 服务器缓存:5 分钟。

市值排名

GET/studio/market/twstock/market_value/all
数据起始
快照(最新公布日)
更新频率
每日(收盘后)

参数

名称说明可用值默认
top
int · query
只留市值前 N 名1–3000全部(约 2,400)

范例

回应

{"date": "YYYY-MM-DD", "twse_ex_etf_market_value": int, "data": [...]},依市值由大到小排序。

字段类型说明
datestring实际采用的基准日(最新公布日;可能比今天晚一天)
twse_ex_etf_market_valueint元。同一基准日 market == "TWSE" 且非 ETF 各列的加总。这是全市场分母,不会因 top 而缩小
data[].rankint名次,从 1 起算
data[].stock_idstring代码
data[].namestring名称
data[].marketstring"TWSE"(上市)或 "TPEx"(上柜),取自 TWSE/TPEx 的上市柜名册
data[].market_valueint元
data[].is_etfbool排行中的 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."}上游配额耗尽

备注

  • 范围是上市+上柜+ETF(不含兴柜;ETN 没有数据)。要回答「市值前 N 大」这类问题,用这个端点,不要对 /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 筛选的结果和分母不可能对不上。
  • 服务器缓存:30 分钟。

本益比/净值比/殖利率

GET/studio/market/twstock/per/<stock_id>
数据起始
2005-10-01
更新频率
每日

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD完整历史
end
string · query
结束日YYYY-MM-DD最新

范例

Python
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": [...]}.

字段类型说明
datestring交易日
stock_idstring代码
dividend_yieldfloat殖利率(%)
PERfloat本益比
PBRfloat股价净值比

错误

400 stock_id 无效、404 没有数据、503 上游配额耗尽。

备注

  • 要对很多档股票做价值筛选,用 batch/per。
  • 当日那一列取自 TWSE/TPEx 官方公布数据,在当天下午出现。
  • 服务器缓存:5 分钟。

综合损益表

GET/studio/market/twstock/financials/<stock_id>
数据起始
默认 2013-01-01;可指定更早
更新频率
每季

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD2013-01-01
end
string · query
结束日YYYY-MM-DD今天

范例

Python
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": [...]},长格式(每季每个科目一列)。

字段类型说明
datestring季末日(03-31/06-30/09-30/12-31)
stock_idstring代码
typestring科目代码,例如 Revenue、GrossProfit、OperatingIncome、NetIncome、EPS、TAX、OtherComprehensiveIncome
valuefloat数值(元;EPS 为每股元)
origin_namestring中文科目名称,遇到不认得的 type 代码时用它辨识

错误

400 stock_id 无效、404 没有数据、503 上游配额耗尽。

备注

  • start 默认为 2013-01-01;送更早的 start 就会拿到更早的数据(2330 最早到 2000-06-30)。
  • 服务器缓存:24 小时。

资产负债表

GET/studio/market/twstock/balance_sheet/<stock_id>
数据起始
默认 2013-01-01;可指定更早
更新频率
每季

参数

同 /financials/<stock_id>。

范例

Python
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)。
  • 服务器缓存:24 小时。

现金流量表

GET/studio/market/twstock/cashflow/<stock_id>
数据起始
默认 2013-01-01;可指定更早
更新频率
每季

参数

同 /financials/<stock_id>。

范例

Python
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:同一个代码的中文名称在不同年度会在全形与半形括号之间切换:

typeorigin_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)。
  • 服务器缓存:24 小时。

月营收

GET/studio/market/twstock/monthly_revenue/<stock_id>
数据起始
2000-01-01
更新频率
每月

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD2000-01-01
end
string · query
结束日YYYY-MM-DD今天

范例

Python
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": [...]},每月一列。

字段类型说明
datestring营收月份的下一个月的第一天:2024-01-01 那列是 revenue_year: 2023、revenue_month: 12。绝不要拿它当营收期间
stock_idstring代码
countrystring市场,观察到的值是 Taiwan
create_timestring每一列都观察到是空字符串("")
revenueint月营收,单位为元,不是千元。这是从数量级推得的,上游没有注明:2330 的 revenue_year 2024, revenue_month 1 回 215785127000,只有读成元(NT$215.8bn)才是合理的数字
revenue_monthint营收月份(1–12),营收期间看这个,不要看 date
revenue_yearint营收年度

错误

400 stock_id 无效、404 没有数据、503 上游配额耗尽。

备注

  • 服务器缓存:24 小时。

财务比率

GET/studio/market/twstock/ratios/<stock_id>
数据起始
2013-03-31 (2013 Q1)
更新频率
每季

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始季末日YYYY-MM-DD2013-01-01
end
string · query
结束季末日YYYY-MM-DD今天

范例

Python
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。

字段类型说明
datestring季末日(03-31/06-30/09-30/12-31),不是财报公开的日期
stock_idstring代码
<ratio>_qfloat | null单季
<ratio>_ttmfloat | null近四季(四个单季加总);四季中任一季缺数据就是 null
debt_ratio, current_ratio, quick_ratio, equity_multiplierfloat | 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."}比率数据库还没准备好,稍后重试,绝不要当成「没有数据」

备注

  • 单季 ROE/ROA 没有年化;每股数字用的股数是由净利 ÷ EPS 推得;银行、证券、保险业有几个比率永远是 null(没有毛利率、流动比率等)。
  • 每列标的是季末日,但财报要再过几周才公开。回测时要把每一列移到它可取得的日期(法定申报期限,与财报相同),直接用 date 对齐会有前视偏差。
  • 缺少科目或分母为零时回 null,绝不会是 0。
  • 不包含:本益比/股价净值比/殖利率(每日数据,用 per/<stock_id>),以及月营收相关比率(自己用 monthly_revenue/<stock_id> 算年增/月增)。
  • 很多档股票 → GET /studio/market/twstock/batch/ratios?stock_ids=...(每次 ≤ 50 档)。
  • 2013-03-31 是硬下限:送更早的 start 也拿不到更早的数据。
  • 由更新财报的同一支排程重算,每天两次(13:30 与 23:00 UTC)。
  • 服务器缓存:6 小时。

股利事件

GET/studio/market/twstock/dividend/<stock_id>
数据起始
依个股而定(2330:2005-06-19)
更新频率
请求时发现数据过期就更新

参数

名称说明可用值默认
stock_id
string · path必填
代码目前上市柜的代码(4–6 位数字,结尾可带一个英文字母)
start
string · query
起始生效日严格 YYYY-MM-DD完整历史
end
string · query
结束生效日严格 YYYY-MM-DD完整历史

区间过滤用三层递补的生效日:有 cash_ex_date 用它,否则 stock_ex_date,再否则 record_date;刚公告、还没有除息日的事件也会出现。

范例

Python
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_datestring权利分派基准日 YYYY-MM-DD
periodstring股利所属期间,是不透明的标签(114年第3季、113、不適用…);当字符串比较,不要解析成年份
announce_datestring公告日;不明时为 ""
cash_ex_datestring除息交易日;没有或未定时为 ""
stock_ex_datestring除权交易日;没有时为 ""
pay_datestring现金股利发放日;不明时为 ""
cashfloat每股现金股利(元,盈余+公积)
stockfloat每股股票股利(元面额,盈余+公积)
stock_ratiofloatstock / 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。

个股新闻

GET/studio/market/twstock/news/<stock_id>
数据起始
约 2020 年年中(2021-02 左右之前很稀疏)
更新频率
请求时抓取

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD今天 − 6 天
end
string · query
结束日;end − start ≤ 31 天YYYY-MM-DD今天

范例

Python
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": [...]},每天多则新闻(含周末)。

字段类型说明
datestring发布时间
stock_idstring代码
titlestring标题
sourcestring发布来源
linkstring网址

错误

状态码回应内容情况
400{"error": "Date range exceeds 31 days"} 或日期解析错误的信息区间太长/日期格式错误
503{"error": "Upstream rate limit. Please retry shortly."}上游配额耗尽

备注

  • 涵盖大约从 2020 年年中开始(最早有 2020-08 的数据;真正的起点没有公开),直到 2021-02 左右都很稀疏,一天只有几篇或没有;更早的日期可能回 []。
  • 每一天的文章在第一次请求该日时抓取。
  • 服务器缓存:5 分钟。

三大法人买卖超

GET/studio/market/twstock/institutional/<stock_id>
数据起始
依个股而定(2330:2012-05-02)
更新频率
每日

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD完整历史
end
string · query
结束日YYYY-MM-DD最新

范例

Python
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。
  • 个股层级,不做分组。这些是各类别的原始字段,要怎么分组由你决定。Blave 自己的个股页面(网站、App、AI 对话)把外资自营商算进外资,与交易所自己的字段命名一致,并把自营商视为自行买卖加避险。全市场端点(GET /studio/market/twmarket/institutional)的分组方式不同,见该节。
  • 当日那一列取自 TWSE/TPEx 官方公布数据,在交易所公布后出现。
  • 服务器缓存:5 分钟。

融资融券

GET/studio/market/twstock/margin/<stock_id>
数据起始
依个股而定(2330:2001-01-05)
更新频率
每日

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD完整历史
end
string · query
结束日YYYY-MM-DD最新

范例

Python
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 上游配额耗尽。

备注

  • 服务器缓存:5 分钟。

股权持股分级表

GET/studio/market/twstock/shareholding/<stock_id>
数据起始
依个股而定(2330:2010-01-29)
更新频率
每周,周五

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD完整历史
end
string · query
结束日YYYY-MM-DD最新

范例

Python
data = requests.get(f"{BASE_URL}/studio/market/twstock/shareholding/2330", headers=headers,                    params={"start": "2024-01-01", "end": "2024-03-31"}, timeout=60).json()["data"]

回应

{"stock_id", "data": [...]},每个日期 × 级距一列。

字段类型说明
datestring周数据日期
stock_idstring代码
levelstring持股级距:1-999、1,000-5,000、5,001-10,000、10,001-15,000、15,001-20,000、20,001-30,000、30,001-40,000、40,001-50,000、50,001-100,000、100,001-200,000、200,001-400,000、400,001-600,000、600,001-800,000、800,001-1,000,000、more than 1,000,001、total、差異數調整(說明4)
peopleint股东人数
unitint持有股数
percentfloat占已发行股数 %

错误

400 stock_id 无效、404 没有数据、503 上游配额耗尽。

备注

  • 数字是 TDCC(集保结算所)公布的股权分散表。
  • 服务器缓存:5 分钟。

外资持股

GET/studio/market/twstock/foreign_shareholding/<stock_id>
数据起始
默认 2013-01-01;可指定更早
更新频率
每日

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD2013-01-01
end
string · query
结束日YYYY-MM-DD今天

范例

Python
data = requests.get(f"{BASE_URL}/studio/market/twstock/foreign_shareholding/2330", headers=headers,                    params={"start": "2026-01-01"}, timeout=60).json()["data"]

回应

{"stock_id", "data": [...]},每天一列。

字段说明
date, stock_id日期、代码
ForeignInvestmentShares外资持有股数
ForeignInvestmentSharesRatio外资持股比率(%)
ForeignInvestmentRemainingShares外资尚可投资股数
ForeignInvestmentRemainRatio外资尚可投资比率(%)
ForeignInvestmentUpperLimitRatio外资持股上限(%)
ChineseInvestmentUpperLimitRatio陆资持股上限(%)
NumberOfSharesIssued已发行股数

错误

400 stock_id 无效、404 没有数据、503 上游配额耗尽。

备注

  • start 默认为 2013-01-01;送更早的 start 就会拿到更早的数据(2330 最早到 2004-02-12)。
  • 服务器缓存:24 小时。

八大行库买卖超

GET/studio/market/twstock/gov_bank/<stock_id>
数据起始
2021-06-30
更新频率
每日

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD今天 − 6 天
end
string · query
结束日;end − start ≤ 31 天YYYY-MM-DD今天

范例

Python
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."}上游配额耗尽

备注

  • 服务器缓存:5 分钟。

借券成交明细

GET/studio/market/twstock/lending/<stock_id>
数据起始
2001-05-01
更新频率
每日

参数

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
start
string · query
起始日YYYY-MM-DD完整历史
end
string · query
结束日YYYY-MM-DD最新

范例

Python
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 上游配额耗尽。

备注

  • 服务器缓存:5 分钟。

分点买卖超(依个股)

GET/studio/market/twstock/broker/stock/<stock_id>
数据起始
2021-06-30
更新频率
每日,台北时间约 21:30 之后

参数

查单日送 date,查区间送 start(+ end);两者都送时以 start 为准。

名称说明可用值默认
stock_id
string · path必填
代码见本类别共通规则
date
string · query
单日YYYY-MM-DD今天
start
string · query
区间起点YYYY-MM-DD
end
string · query
区间终点;区间 ≤ 366 天(含头尾)YYYY-MM-DDstart

范例

Python
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": [...]},每个分点每天一列。

字段类型说明
datestring交易日
stock_idstring代码
broker_idstring分点代码(可能含英文字母,例如 920A)
broker_namestring分点名称
pricefloat成交量加权平均价
buy / sellint买进/卖出股数

错误

状态码回应内容情况
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."}数据暂时无法取得,请重试;不要当成「没有成交」

备注

  • 没有数据的日子(假日、2021-06-28 以前,或当天约 21:30 以前)回 200 + []。
  • 区间查询是真的有效:start/end 设 2026-09-06 → 2026-09-13,broker/stock/<stock_id> 与 broker/trader/<trader_id> 都回了涵盖五个交易日的数据。
  • 服务器缓存:5 分钟。

分点买卖超(依分点)

GET/studio/market/twstock/broker/trader/<trader_id>
数据起始
2021-06-30
更新频率
每日,台北时间约 21:30 之后

参数

date/start/end 规则同 /broker/stock/<stock_id>。

名称说明可用值默认
trader_id
string · path必填
分点代码,从 /broker/search 取得英文字母、数字、-(例如 9217、920A)
date
string · query
单日YYYY-MM-DD今天
start
string · query
区间起点YYYY-MM-DD
end
string · query
区间终点;区间 ≤ 366 天(含头尾)YYYY-MM-DDstart

范例

Python
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"}。

备注

  • 服务器缓存:5 分钟。

注意股/处置股

GET/studio/market/twstock/alerts
数据起始
TWSE 2001-01;TPEx 注意 2002-02、处置 2003-09
更新频率
每日台北时间 17:45、21:30 与 07:00

参数

给 date,或 start/end,或都不给(= 今天,台北时间)。

名称说明可用值默认
date
string · query
单日:当天生效中的处置,以及当天公告的注意严格 YYYY-MM-DD;不能与 start/end 同时使用
start
string · query
区间第一天严格 YYYY-MM-DD有 stock_id 时为 2001-01-01,否则为 end − 365 天
end
string · query
区间最后一天(含当日)严格 YYYY-MM-DD今天(start 较晚时改用它)
kind
string · query
公告类型disposal(处置)、notice(注意)两者
market
string · query
交易所twse, tpex两者
stock_id
string · query
单一代码;不受 366 天上限限制见本类别共通规则全部

区间的意思:处置的期间(start–end)与查询区间有重叠就回传,注意则是公告 date 落在区间内才回传。不带 stock_id 时区间最多 366 天(含头尾),全市场更长的区间要拆开查(一次查一个日历年刚好放得下)。与本类别的默认不同,start/end/date 都会严格验证。

范例

回应

{"start", "end", "data": [...]};start/end 回显实际采用的区间(送 date 时两者都等于 date)。各列依 date、market、kind、stock_id 排序。每则公告一列。

字段类型说明
datestring公告日 YYYY-MM-DD(处置从下一个交易日起生效)
stock_idstring代码,包含权证、ETF 与可转债(例如 037060、45402)
stock_namestring | null公告上的名称
marketstringtwse(上市)或 tpex(上柜)
kindstringdisposal 或 notice
countint交易所的累计次数(累计/累计次数)
start, endstring | null处置期间,头尾两天都算;注意为 null
conditionstring | null处置:公告上的触发条件(連續三次、連續3個營業日、最近十個營業日已有六次 …)。注意:引用的款次(第一款、第五款);没有时为 null
measurestring | null处置类型:第一次處置、第二次處置、再次處置、人工管制撮合、收足五成款券 …;注意与早期 TPEx 的列为 null
match_minutesint | null处置:从内文读出「约每N分钟撮合一次」的 N。内文没写时(约 2011 年以前的 TWSE 处置内文都是空白,以及不是撮合类的措施)与注意皆为 null
reasonstring | null公告全文;交易所没有公布内文时为 null(2011-03 以前的 TWSE 处置都没有)(处置为处置内容,注意为注意交易资讯)
close, pefloat | 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 分钟),要逐列读,绝不要假设固定值。
  • 不包含处置前的候选名单(处置候选)。
  • 引用时请注明「数据来源:台湾证券交易所、证券柜台买卖中心」。
  • TWSE 的起始日同时涵盖处置与注意。
  • TPEx 傍晚的公告可能要到 07:00 那次才出现。

台股批次查询

GET/studio/market/twstock/batch/<data_type>
数据起始
依 data_type 而定(同单一个股端点)
更新频率
依 data_type 而定

参数

名称说明可用值默认
data_type
string · path必填
数据集price, price_adj, per, institutional, shareholding, foreign_shareholding, financials, balance_sheet, monthly_revenue, ratios, dividend
stock_ids
string · query必填
代码逗号分隔,≤ 50
start
string · query
起始日YYYY-MM-DD(只有 dividend 会严格验证)依 data_type 而定
end
string · query
结束日YYYY-MM-DD依 data_type 而定

范例

Python
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

备注

  • 全市场(约 2,000 档)大约是 40 次呼叫;绝不要把单股端点展开成大量平行请求。
  • 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。

台股板块轮动

GET/studio/market/twstock/sector/overview
数据起始
快照(最近一个交易日)
更新频率
每日;类股指数约台北时间 14:00 后,买卖超较晚

参数

名称说明可用值默认
window
int · query
相对强弱与区间买卖超加总用的交易日数10, 20, 6020

范例

回应

一个对象(没有 data 外层):{"date", "summary", "sectors": [...], "concentration", "flow_caps"}。sectors 是 32 个 TWSE 类股指数,顺序固定。

字段类型单位说明
datestring—类股指数的最新交易日
summary.up / summary.downint个板块date 当天收涨/收跌的板块数
summary.migrations_todayint个板块date 当天换象限的板块数
summary.foreign_total / summary.trust_totalfloat亿元(TWD 100M)最新公布日的全市场外资/投信买卖超(官方合计)
summary.foreign_streak / summary.trust_streakint天连续买超(+N)或卖超(−N)天数
summary.margin_changefloat亿元(TWD 100M)最新公布日的全市场融资余额增减
summary.margin_pctlint0–100margin_change 在过去一年的百分位;历史不满一年时为 null
sectors[].slug / name / groupstring—板块代码(sector/constituents/<slug> 用这个)、中文名称、elec(电子)/fin(金融)/trad(传产)
sectors[].weightfloat%板块市值 ÷ 所有已归板块票的市值
sectors[].returnsobject%d1、d5、d10、d20、d60、ytd 指数报酬(ytd 以前一年最后收盘价为基准)
sectors[].rsfloat指数(100 = 加权指数)window 期间的相对强弱:100 ×(板块收盘 ÷ window 天前的板块收盘)÷(加权指数收盘 ÷ window 天前的加权指数收盘)
sectors[].momentumfloat指数(100 = 持平)100 + rs 的 5 日变化
sectors[].quadrantstring—leading(rs ≥ 100,momentum ≥ 100)、weakening(rs ≥ 100,momentum < 100)、lagging(两者都 < 100)、improving(rs < 100,momentum ≥ 100)
sectors[].migration_daysint交易日停留在目前象限的连续交易日数(最多往回看 90 个交易日)
sectors[].tailarray—date 之前 4 天的 [rs, momentum] 数对,由旧到新
sectors[].clampedbool—rs、momentum 或 tail 中任一点被截顶时为 true(见备注)
sectors[].foreign / trust / dealerfloat亿元(TWD 100M)date 当天外资/投信/自营商的估计买卖超
sectors[].foreign_win / trust_win / dealer_winfloat亿元(TWD 100M)同上,加总最近 window 个交易日
sectors[].foreign_win_prevfloat亿元(TWD 100M)再往前 window 天的外资加总
sectors[].stats.rs_up_streakint天rs 连续上升的天数
sectors[].stats.foreign_streak / dealer_streakint天连续买超(+N)/卖超(−N)天数
sectors[].stats.d5_return_pctl_1yint0–1005 日报酬在过去一年的百分位
sectors[].stats.foreign_buy_days_20dint天最近 20 天中外资买超的天数
sectors[].stats.foreign_buy_days_pctl_1yint0–100这个天数在过去一年的百分位
concentration.top3_buy_sharefloat0–1当天外资流入板块的正向金额中,前 3 大板块所占的比重
flow_capsobject亿元(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."}上游配额耗尽

备注

  • 板块是 TWSE 的 32 个类股指数(只有上市)。成分股、权重与买卖超都用上市普通股计算;上柜股票不属于任何板块。
  • 板块买卖超是估计值(每档股票当日净买卖股数 × 当日收盘价,再依板块加总)。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。

台股板块上涨比例

GET/studio/market/twstock/sector/breadth
数据起始
最多往回 730 个日历日
更新频率
每日,约台北时间 14:00 后

参数

名称说明可用值默认
days
int · query
从今天往回算的日历日数≥ 1;超过 730 一律当作 730365

范例

Python
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": [...]},两个平行数组,每个交易日一个元素,由旧到新。

字段类型单位说明
datesstring[]—交易日(YYYY-MM-DD)
pct_upfloat[]%当天收涨的类股指数占当天有涨跌数字的类股指数比重(多数日子是 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."}上游配额耗尽

备注

  • 平盘的板块算作没有上涨;当天没有涨跌数字的板块不列入当天的分母。
  • 服务器缓存:5 分钟。

台股板块成分股

GET/studio/market/twstock/sector/constituents/<slug>
数据起始
快照(最近一个交易日)
更新频率
每日(收盘后)

参数

名称说明可用值默认
slug
string · path必填
板块sector/overview 列出的 32 个板块代码之一

范例

Python
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 档成分股,由大到小。

字段类型单位说明
datestring—价格的交易日
totalint档板块的成分股档数
stocks[].stock_id / namestring—代码、名称
stocks[].chgfloat%date 当天涨跌幅
stocks[].foreignfloat亿元(TWD 100M)date 当天外资的估计买卖超(净买卖股数 × 收盘价)
stocks[].themesarray—[{"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 档改依代码排序。
  • 服务器缓存:30 分钟。

台股题材族群

GET/studio/market/twstock/theme/overview
数据起始
快照(最近一个交易日)
更新频率
每日,收盘后

参数

名称说明可用值默认
window
int · query
区间买卖超加总用的交易日数10, 20, 6020

范例

回应

一个对象(没有 data 外层):{"date", "list_ym", "first_ym", "list_age_days", "stale_months", "pctl_includes_backfill", "summary", "themes": [...], "flow_caps"}。

字段类型单位说明
datestring—题材指数的最新交易日
list_ymstring—最新一期题材名单的月份,YYYY-MM
first_ymstring—所有题材中最早一期名单的月份
list_age_days / stale_monthsint天/月最新名单的新旧:生效后经过的天数、距名单月份的月数
pctl_includes_backfillbool—某个百分位的一年历史往前跨过名单生效日时为 true
summary.up / summary.downint个题材date 当天上涨/下跌的题材数
summary.top / summary.bottomobject%{"slug", "d20"}:20 日报酬最好与最差的题材
summary.foreign_topobject亿元(TWD 100M){"slug", "foreign_win", "foreign_win_ex_top", "top_name"}:扣掉最大权值股后,外资买超最多的题材
themes[].slugstring—题材代码(其他题材端点用这个)
themes[].nameobject—{"zh", "en", "cn"}
themes[].countint档目前名单的成分股数(不含已下市)
themes[].snapshot_ymstring—该题材目前名单的月份
themes[].indexablebool—题材至少有 5 档成分股、且名单生效不超过 90 天时为 true
themes[].returnsobject%题材指数的 d1、d5、d10、d20、d60、ytd 报酬
themes[].returns_backfillobject—键相同,该报酬的起点早于题材第一期名单生效日时为 true
themes[].foreign / trust / dealerfloat亿元(TWD 100M)date 当天成分股的估计买卖超;当天买卖超公布前为 null
themes[].foreign_win / trust_win / dealer_winfloat亿元(TWD 100M)同上,加总最近 window 个交易日
themes[].foreign_win_prevfloat亿元(TWD 100M)再往前 window 天的外资加总
themes[].foreign_win_ex_topfloat亿元(TWD 100M)扣掉最大成分股本身外资买卖超后的 foreign_win
themes[].foreign_buy_membersint档区间内外资买卖超加总为正的成分股数
themes[].topobject%{"stock_id", "name", "mv_share"}:最大成分股与它占题材市值的比重,以名单生效日计算
themes[].top5array—[{"stock_id", "name"}]:名单生效日市值最大的 5 档成分股
themes[].statsobject—foreign_streak、dealer_streak(±天数)、d5_return_pctl_1y、foreign_buy_days_20d、foreign_buy_days_pctl_1y:意义同 sector/overview
flow_capsobject亿元(TWD 100M){"foreign", "trust", "dealer"}:题材 20 日买卖超加总的典型规模(P90),用于配色刻度;买卖超历史不满一年时为 null

错误

状态码回应内容情况
400{"error": "window must be one of [10, 20, 60]"}window 不正确
503{"error": "not_yet_effective"}还没有任何题材名单生效

备注

  • 题材是 Blave 整理、每月公布的概念股名单(上市+上柜),每档都附理由与公开来源(见 theme/constituents/<slug>)。目前的代码:ai、silicon-photonics-cpo、memory、pcb-abf-substrate、thermal-cooling、robotics。
  • 题材指数是等权重、还原权息(总报酬)。题材第一期名单生效前的部分用第一期名单回补,所以那段报酬带有后见之明,returns_backfill 会标出来。
  • 买卖超是估计值:每档成分股当日净买卖股数 × 当日收盘价,再加总。*_win、连续天数与 foreign_buy_days_* 都截止在最新公布买卖超的那天,下午时段可能是前一个交易日。
  • 已停用的题材会从 themes 中移除。

台股题材成分股

GET/studio/market/twstock/theme/constituents/<slug>
数据起始
快照(目前名单)
更新频率
每日,收盘后;名单每月更新

参数

名称说明可用值默认
slug
string · path必填
题材theme/overview 里的题材代码

范例

回应

一个对象(没有 data 外层)。

字段类型说明
datestring个股数字的交易日
slug, statusstring题材代码、active
name / introobject{"zh", "en", "cn"} 题材名称/一段说明
snapshot_ymstring目前名单的月份
published_at / effective_datestring名单公布日/生效日
first_ymstring题材第一期名单的月份
list_age_days / stale_monthsint名单生效后经过的天数/距名单月份的月数
countint成分股数,不含已下市
indexablebool至少 5 档成分股、且名单生效不超过 90 天时为 true
changesobject{"added", "removed", "prev_ym"}:相较上一期名单新增/移除的股票代码(第一期名单的 prev_ym 为 null)
relatedarray[{"slug", "overlap"}]:最多 3 个有共同成分股的其他题材,共同成分股最多的排前面
gatedboolAPI 密钥一律是 false
stocks[].stock_id / namestring代码、名称
stocks[].marketstringtwse 或 tpex
stocks[].sector_slugstring依产业类别对应的板块代码,同 sector/overview(含上柜股票);对应不到时为 null
stocks[].chgfloatdate 当天涨跌幅 %
stocks[].foreignfloatdate 当天外资的估计买卖超,亿元(TWD 100M);当天买卖超公布前为 null
stocks[].ret20float还原权息的 20 个交易日报酬,%
stocks[].rev_yoyfloat最新月营收年增率,%
stocks[].roefloat近四季 ROE,%
stocks[].foreign_share_chg_20dfloat20 个交易日内外资持股比率的变化,百分点
stocks[].disposalbool今天处于处置期间
stocks[].delisted / last_trade_datebool / string名单建立后已下市,以及最后交易日(否则为 null)
stocks[].alsostring[]同样包含这档股票的其他题材
stocks[].reasonobject{"zh", "en", "cn"} 这档股票列入题材的理由
stocks[].sourcesarray[{"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。

台股题材指数

GET/studio/market/twstock/theme/<slug>/index
数据起始
近 3 年,滚动(各题材第一期名单之前为回补)
更新频率
每日,收盘后

参数

名称说明可用值默认
slug
string · path必填
题材theme/overview 里的题材代码
range
string · query
截止在最新一天的日历区间(92/366/1,096 天)3m, 1y, 3y3m

范例

Python
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_datestring指数为 100 的那天(题材第一期名单生效前一个交易日)
first_ymstring题材第一期名单的月份
points[].datestring交易日
points[].valuefloat题材指数,base_date 为 100
points[].taiex / tpexfloat加权指数/柜买指数的报酬指数,在 base_date 重设为 100,方便比较
points[].is_backfillbool题材第一期名单生效前为 true(成分股取自第一期名单)
points[].nint当天指数内的成分股数
points[].snapshot_ymstring成分股所属名单的月份

错误

状态码回应内容情况
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)。

法人买超家数比例

GET/studio/market/twstock/chip_breadth/<scope>
数据起始
快照(最新收盘)
更新频率
每晚,收盘后

参数

名称说明可用值默认
scope
string · path必填
分组类型theme, sector
window
int · query
买卖超加总的交易日数10, 20, 6020
inst
string · query
分组排名依据的法人foreign, trustforeign

范例

回应

一个对象(没有 data 外层):{"scope", "window", "inst", "as_of", "min_group", "baseline", "groups": [...], "excluded": [...], "sources"}。

字段类型说明
as_ofstring买卖超区间的最后一天
min_groupint计入股票数少于此值的分组不排名(6)
baseline.universestring分组拿来比较的市场:板块用 twse,题材用 twse+tpex
baseline.foreign / baseline.trustobject{"buy", "total", "ratio"}:该市场在区间内买超的普通股数、计入的总数,以及比重 %
groups[].slug / name—分组代码;板块的 name 是字符串,题材的是 {"zh", "en", "cn"}
groups[].totalint分组内计入的股票数
groups[].foreign / groups[].trustobject{"buy", "ratio", "gap", "rank"}:买超的股票数、比重 %、比重减去基准比重的百分点(整数),以及依比重的排名
excludedarray[{"slug", "name", "total"}]:低于 min_group 的分组
sources.institutionalobject买卖超数据来源交易所的 {"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."}上游额度用完,或取不到股票与板块的对照表

备注

  • 计入的股票是区间内有买卖超数字的普通股(不含 ETF、ETN、REIT、特别股与存托凭证)。买超指区间的估计买卖超(每日净买卖股数 × 收盘价)大于 0。
  • 板块是 sector/overview 的 32 个 TWSE 板块(只有上市);题材是 theme/overview 的名单(上市+上柜),所以两者的基准不同。
  • 比重相同时,计入股票较多的分组排前面,再依代码排序。
  • gap 依精确分数四舍五入,刚好一半时往远离零的方向进位。

法人买超族群成分股

GET/studio/market/twstock/chip_breadth/<scope>/<slug>
数据起始
快照(最新收盘)
更新频率
每晚,收盘后

参数

名称说明可用值默认
scope
string · path必填
分组类型theme, sector
slug
string · path必填
类别板块代码(sector/overview)或题材代码(theme/overview)
window
int · query
买卖超加总的交易日数10, 20, 6020

范例

回应

一个对象(没有 data 外层):排名的 scope、window、as_of、min_group 与 baseline,另外加上:

字段类型说明
price_as_ofstring价格与报酬截止的那天
slugstring类别
groupobject该分组在排名里的那一列(没有排名时不带 rank)
rankedbool分组低于 min_group 时为 false
stocks[].stock_id / name / marketstring代码、名称、twse/tpex
stocks[].foreign / truststring区间内为 buy、sell 或 flat
stocks[].foreign_<N>dfloat区间内外资的估计买卖超,亿元(TWD 100M);<N> = window
stocks[].market_capfloat亿元(TWD 100M)
stocks[].ret_<N>dfloat区间报酬,%(有还原数据时为还原权息报酬)
stocks[].themesarray[{"slug", "name"}] 包含这档股票的所有题材(scope 为 theme 时不列出所查的题材),name = {"zh", "en", "cn"}
stocks[].disposal / noticeboolas_of 当天处于处置期间/有注意股公告;取不到该数据时为 null
excluded_countint没有计入的成分股数(非普通股或没有买卖超数字)
alerts_availablebool读不到处置/注意股数据时为 false
sourcesobject{"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 判断:处置期间涵盖当天、注意股公告在当天发布。

台股选股器

POST/studio/market/twstock/screener/run
数据起始
快照(最新收盘,全市场)
更新频率
每晚,收盘后

参数

JSON 请求本文(用 json= 送出;其他格式的本文一律回 400)。每个字段都可省略;{} 会回传市值最大的 300 档普通股。

名称说明可用值默认
filters
array · body
条件,格式见下方≤ 40 个条件,全部符合才算(AND)[]
include_types
string[] · body
在默认的普通股范围之外,加入这些证券类型etf、etn、reit、preferred、dr 的子集合[]
sort
object · body
rows 的排序;null 值排在最后indicator = 下方任一数值键;dir = asc/desc{"indicator": "market_cap", "dir": "desc"}
limit
int · body
回传的列数(total 仍计算所有符合的股票)1–300300

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)投信的同一数字

范例

回应

一个对象(没有 data 外层)。

字段类型说明
as_ofstring快照的交易日
datesobject各数据的截止日:price、per、market_cap、flows(flows 可能比 as_of 早一天)
totalint套用 limit 前的符合数
columnsarray结果表的字段:默认字段(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
sortobject实际套用的排序
rows[].stock_id / namestring代码、名称
rows[].marketstringtwse 或 tpex(这里是小写)
rows[].sec_typestringcommon, etf, etn, reit, preferred, dr
rows[].industrystring交易所的产业代码;交易所没有给时为 null
rows[].fin_quarterstring比率字段依据的季别,例如 2026Q2(财报公布期间各股可能不同)
rows[].rev_monthstringrev_yoy 依据的月份,例如 2026-09
rows[].adjbool报酬无法还原权息时为 false
rows[].themesstring[]这档股票所属的题材代码
rows[].disposal / noticebool今天处于处置期间/自 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 不会选到它们;空值不会符合任何数值条件。
  • 每次请求都即时计算(不缓存)。