API CK Đài Loan

31 endpoint · Dữ liệu thị trường · Cơ bản · Dòng tiền tổ chức · Khác

Cập nhật lần cuối 2026-10
URL gốc
https://api.blave.org
Xác thực
Gửi header api-key + secret-key trong mọi request
Quyền truy cập
API plan or Blave Agent plan
Giới hạn tần suất
500 request / 5 phút cho mỗi key và mỗi IP
Xác thực và lỗi Dữ liệu này gồm những gì

Quy ước

  • stock_id — mã TWSE (上市) / TPEx (上櫃), ví dụ 2330, 0050, 00878, 006208. Gồm chữ cái và chữ số (cho phép dấu chấm), ≤ 8 ký tự, nếu không sẽ trả về 400 {"error": "Invalid stock_id"}.
  • start / end — YYYY-MM-DD, bao gồm cả ngày đó. Trừ khi endpoint ghi khác, hai tham số này không được kiểm tra định dạng (việc lọc là phép so sánh chuỗi), nên hãy luôn gửi YYYY-MM-DD.
  • Quota upstream đã hết → 503 {"error": "Upstream rate limit. Please retry shortly."} — thử lại sau.
  • Với nhiều cổ phiếu, dùng batch/<data_type> (≤ 50 mã mỗi lần gọi); không bao giờ lặp một endpoint đơn mã trên cả rổ cổ phiếu.

Danh sách cổ phiếu Đài Loan

GET/studio/market/twstock/list
Dữ liệu từ
Snapshot (các chứng khoán đang niêm yết)
Tần suất cập nhật
Cache máy chủ 24 giờ

Tham số

Không có.

Ví dụ

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

Phản hồi

{"data": [...]}, ~2,400 dòng (上市 + 上櫃, gồm cả ETF; không gồm 興櫃).

TrườngKiểuMô tả
stock_idstringMã
namestringTên
closefloat | nullGiá đóng cửa ngày mới nhất (null khi upstream không có, ví dụ bị tạm ngừng giao dịch)
marketstringTWSE (上市) hoặc TPEx (上櫃)
industry_codestring | nullMã 產業別 dạng số gốc của TWSE/TPEx, trả nguyên trạng (không giải mã). null với ETF / chứng khoán không phải cổ phiếu doanh nghiệp. Các mã thường gặp: 15 航運業, 17 金融保險業, 22 生技醫療業, 24 半導體業, 25 電腦及週邊設備業, 26 光電業, 27 通信網路業, 28 電子零組件業, 29 電子通路業, 30 資訊服務業, 31 其他電子業
listing_datestring | nullYYYY-MM-DD; null với ETF / chứng khoán không phải cổ phiếu doanh nghiệp

Lỗi

Chỉ có các lỗi dùng chung (500 nếu cả hai thị trường đều lỗi).

Ghi chú

  • Dùng để dựng rổ cổ phiếu. Khi lấy mẫu, hãy trải đều qua các ngành — mã được xếp theo nhóm ngành, nên cắt bằng [:N] sẽ dồn vào một vài ngành.
  • Danh sách ngắn hơn rõ rệt so với ~2,400 nghĩa là một thị trường tải thất bại — hãy coi là dữ liệu không đầy đủ, không phải hủy niêm yết.
  • Cache máy chủ rút xuống 10 phút khi một thị trường tải thất bại.

Thông tin cổ phiếu Đài Loan

GET/studio/market/twstock/info/<stock_id>
Dữ liệu từ
Snapshot
Tần suất cập nhật
Cache máy chủ 24 giờ

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục

Ví dụ

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

Phản hồi

{"stock_id": "<stock_id>", "data": {...}}; data có cùng các trường với một dòng của /list.

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id"}Không qua kiểm tra định dạng
404{"error": "Stock not found"}Không phải chứng khoán đang niêm yết

Ghi chú

  • Phục vụ từ cùng một cache với /list.

Giá ngày cổ phiếu Đài Loan (gốc)

GET/studio/market/twstock/price/<stock_id>
Dữ liệu từ
1994-10-01
Tần suất cập nhật
Hằng ngày, khoảng 14:00 giờ Đài Bắc

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
Mã cổ phiếu / ETF niêm yết (上市) hoặc OTC (上櫃)Chữ cái/chữ số (cho phép dấu chấm), ≤ 8 ký tự — ví dụ 2330, 0050, 00878, 006208
start
string · query
Ngày đầu tiên, bao gồm cả ngày đóYYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày cuối cùng, bao gồm cả ngày đóYYYY-MM-DDngày mới nhất hiện có

Ví dụ

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}, ...]

Phản hồi

{"stock_id": "<stock_id>", "data": [ ... ]}, các dòng sắp xếp tăng dần theo date.

TrườngKiểuĐơn vịMô tả
datestringYYYY-MM-DDNgày giao dịch
stock_idstring—Mã cổ phiếu
open / high / low / closefloatTWDGiá chưa điều chỉnh
spreadfloatTWDThay đổi so với giá đóng cửa phiên trước
volumeintcổ phiếu (股)Khối lượng giao dịch
turnover_valueintTWDGiá trị giao dịch
turnover_countintlệnh khớp (筆)Số lệnh khớp

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id"}stock_id không qua kiểm tra định dạng
404{"error": "No data found for stock_id: <stock_id>"}Mã không xác định / upstream không có dữ liệu
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết — thử lại sau

Ghi chú

  • start / end không được kiểm tra định dạng: giá trị sai định dạng sẽ được lọc bằng phép so sánh chuỗi thay vì trả về 400, nên hãy luôn gửi YYYY-MM-DD.
  • Dùng price_adj để backtest tổng lợi nhuận; endpoint này trả giá chưa điều chỉnh.
  • Với nhiều cổ phiếu, dùng batch/price (≤ 50 mã mỗi lần gọi) thay vì lặp endpoint này.
  • 1994-10-01 là ngày sớm nhất được cung cấp; các mã niêm yết sau thì bắt đầu muộn hơn.
  • Dòng của ngày hiện tại lấy từ tệp giá đóng cửa chính thức của TWSE / TPEx và xuất hiện sau khi các tệp này được công bố (khoảng 14:00 giờ Đài Bắc).
  • Cache máy chủ: 5 phút.

Giá ngày cổ phiếu Đài Loan (đã điều chỉnh)

GET/studio/market/twstock/price_adj/<stock_id>
Dữ liệu từ
1994-10-01 (giống /price)
Tần suất cập nhật
Hằng ngày

Tham số

Giống /price/<stock_id>.

Ví dụ

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"]

Phản hồi

Cùng cấu trúc và các trường với /price/<stock_id>; open / high / low / close là giá đã điều chỉnh, volume / turnover_* giống hệt chuỗi gốc.

Lỗi

Giống /price/<stock_id>.

Ghi chú

  • Điều chỉnh tiến (後復權 / 向後調整) cho cổ tức tiền mặt và cổ tức cổ phiếu: giá giai đoạn đầu giữ nguyên như khi giao dịch; từ mỗi ngày trừ cổ tức trở đi, giá được nhân với hệ số lũy kế, nên giá điều chỉnh gần đây cao hơn giá gốc. Dùng cho backtest tổng lợi nhuận.
  • Được dựng lại khi chuỗi /price gốc có dữ liệu mới.
  • Cache máy chủ: 5 phút.

Báo giá thời gian thực cổ phiếu Đài Loan

GET/studio/market/twstock/quote/<stock_id>
Dữ liệu từ
Chỉ có snapshot — không có lịch sử
Tần suất cập nhật
Khoảng mỗi 10 giây

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục

Ví dụ

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}

Phản hồi

{"stock_id": "<stock_id>", "data": {...}}; data là một object phẳng.

TrườngKiểuMô tả
open / high / low / closefloatOHLC của hôm nay tính đến hiện tại
change_price / change_ratefloatThay đổi so với giá đóng cửa phiên trước (TWD / %)
average_pricefloatGiá khớp bình quân
volumeintKhối lượng của tick mới nhất
total_volumeintKhối lượng lũy kế hôm nay
amount / total_amountfloatGiá trị giao dịch của tick mới nhất / lũy kế
yesterday_volumeintKhối lượng của phiên trước
buy_price / buy_volumefloat / intGiá mua tốt nhất
sell_price / sell_volumefloat / intGiá bán tốt nhất
volume_ratiofloatTỷ lệ khối lượng
quote_timestringYYYY-MM-DD HH:MM:SS — dấu thời gian đầy đủ, khác với date chỉ có ngày ở các endpoint khác
stock_idstringMã
tick_typeint0 không xác định, 1 bên bán chủ động (賣盤成交), 2 bên mua chủ động (買盤成交)

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id"}Không qua kiểm tra định dạng
404{"error": "No data found for stock_id: <stock_id>"}Không có báo giá
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết

Ghi chú

  • Chỉ để xem giá trong phiên — không có lịch sử, không dùng để backtest.
  • Cache máy chủ: 10 giây.

Báo giá thời gian thực cổ phiếu Đài Loan (hàng loạt)

GET/studio/market/twstock/quote
Dữ liệu từ
Chỉ có snapshot — không có lịch sử
Tần suất cập nhật
Khoảng mỗi 10 giây

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_ids
string · queryBắt buộc
MãPhân tách bằng dấu phẩy, ≤ 50 mã

Ví dụ

Python
data = requests.get(f"{BASE_URL}/studio/market/twstock/quote", headers=headers,                    params={"stock_ids": "2330,2317"}, timeout=30).json()["data"]# {"2330": {...}, "2317": {...}}

Phản hồi

{"data": {"<stock_id>": {...quote fields...}, ...}}; các trường giống /quote/<stock_id>. Mã không có báo giá sẽ không xuất hiện.

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "stock_ids parameter required"}Thiếu
400{"error": "stock_ids exceeds max 50 per request"}Quá nhiều
400{"error": "Invalid stock_id in list"}Có mã không qua kiểm tra định dạng
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết

Ghi chú

  • Cache máy chủ: 10 giây.

Báo giá thời gian thực cổ phiếu Đài Loan (toàn bộ)

GET/studio/market/twstock/quote/all
Dữ liệu từ
Chỉ có snapshot — không có lịch sử
Tần suất cập nhật
Khoảng mỗi 10 giây

Tham số

Không có.

Ví dụ

Python
rows = requests.get(f"{BASE_URL}/studio/market/twstock/quote/all", headers=headers, timeout=30).json()["data"]

Phản hồi

{"data": [{...quote fields...}, ...]} (~2,800 dòng); các trường giống /quote/<stock_id>.

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết

Ghi chú

  • Cache máy chủ: 10 giây.

OHLCV nến phút cổ phiếu Đài Loan

GET/studio/market/twstock/minute/ohlcv/<stock_id>/<schema>
Dữ liệu từ
2019-01 (bổ sung dần theo từng mã)
Tần suất cập nhật
Nến thời gian thực trong phiên; hiệu chỉnh theo dữ liệu chính thức sau khi đóng cửa

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãMột mã TWSE/TPEx đang niêm yết, hoặc TAIEX (加權指數)
schema
string · pathBắt buộc
Khung thời gian nến1m, 5m, 15m, 30m, 60m, 1d
start
string · query
Ngày bắt đầuYYYY-MM-DDend − khoảng tối đa của khung thời gian đó
end
string · query
Ngày kết thúc, bao gồm cả ngày đóYYYY-MM-DDhôm nay (UTC)
adjust
string · query
1 = OHLC điều chỉnh tiến (後復權), cùng hệ số với /price_adj; volume không bao giờ được điều chỉnh0, 1, true, false0

Khoảng tối đa mỗi request (end − start): 1m 31 ngày · 5m 62 ngày · 15m 93 ngày · 30m 186 ngày · 60m 365 ngày · 1d 3650 ngày.

Ví dụ

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}, ...]}

Phản hồi

{"stock_id", "schema", "data": [...]}.

TrườngKiểuĐơn vịMô tả
tsstringUTC ISOThời điểm mở nến (nhãn tính theo đầu phút); nến 13:30 giờ Đài Bắc là phiên khớp lệnh định kỳ đóng cửa
open / high / low / closefloatTWDGiá
volumeintlô (張), không phải cổ phiếuKhối lượng. Nến TAIEX luôn mang volume: 0 ở mọi khung thời gian — chỉ số không có khối lượng nên không cung cấp; đừng đọc nó như một con số giá trị giao dịch

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id (must be a listed TWSE/TPEx security)"}Không niêm yết
400{"error": "Invalid schema. Allowed: [...]"}Khung thời gian không hợp lệ
400{"error": "Invalid adjust (use 0 or 1)"}adjust không hợp lệ
400{"error": "Invalid date format. Use YYYY-MM-DD"}Ngày sai định dạng
400{"error": "date_range_too_large", "message": "...", "max_days": <n>}Khoảng thời gian vượt giới hạn
503{"error": "market data temporarily unavailable"}Lỗi đọc kho dữ liệu
503{"error": "adjust factors temporarily unavailable"}adjust=1 nhưng không lấy được hệ số — không bao giờ âm thầm trả dữ liệu chưa điều chỉnh

Ghi chú

  • Phạm vi dữ liệu mở rộng theo nhu cầu: có thể truy vấn bất kỳ cổ phiếu niêm yết nào; lần truy vấn đầu tiên nạp sẵn ~30 ngày gần nhất và đưa cổ phiếu vào diện theo dõi thời gian thực, sau đó lịch sử sâu (2019-01 →) mới được bổ sung. Hãy kiểm tra minute/ohlcv/symbols trước khi yêu cầu nhiều năm lịch sử.
  • Khoảng thời gian không có dữ liệu trả về 200 kèm [].
  • Nến đang hình thành không được trả về; dùng /quote/<stock_id> để lấy giá thời gian thực.
  • Hãy chia các khoảng dài thành nhiều đoạn nằm trong giới hạn của từng khung thời gian.

Các mã đã có nến phút

GET/studio/market/twstock/minute/ohlcv/symbols
Dữ liệu từ
Snapshot
Tần suất cập nhật
Thời gian thực

Tham số

Không có.

Ví dụ

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

Phản hồi

{"data": ["2330", "TAIEX", ...]} — các mã đã có dữ liệu nến phút trên đĩa (cổ phiếu đang niêm yết cùng với TAIEX), đã sắp xếp.

Lỗi

Chỉ có các lỗi dùng chung.

Nến 1 phút cổ phiếu Đài Loan (cũ)

GET/studio/market/twstock/kbar/<stock_id>
Dữ liệu từ
2019-01-01
Tần suất cập nhật
Cache máy chủ 60 giây khi khoảng thời gian có hôm nay, ngược lại là 5 phút

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãMột mã TWSE/TPEx đang niêm yết, hoặc TAIEX
start
string · query
Ngày bắt đầuYYYY-MM-DDhôm nay − 6 ngày
end
string · query
Ngày cuối cùng; end − start ≤ 31 ngàyYYYY-MM-DDhôm nay

Ví dụ

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"]

Phản hồi

{"stock_id", "data": [...]}, sắp xếp tăng dần.

TrườngKiểuMô tả
datestringYYYY-MM-DD (giờ Đài Bắc)
minutestringHH:MM:SS giờ Đài Bắc, thời điểm bắt đầu nến (09:00–13:30)
stock_idstringMã
open / high / low / closefloatTWD
volumeintLô (張)

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id (must be a listed TWSE/TPEx security)"}Không niêm yết
400{"error": "Date range exceeds 31 days"}Khoảng thời gian quá dài, hoặc ngày sai định dạng

Ghi chú

  • Endpoint cũ — nên dùng minute/ohlcv/<stock_id>/1m. Cổ phiếu niêm yết chưa có dữ liệu phút sẽ trả về [] (endpoint này không kích hoạt việc nạp dữ liệu).
  • Nến của hôm nay là dữ liệu tạm tính trong phiên và được thay bằng nến chính thức sau ~16:10 giờ Đài Bắc.
  • Chỉ những mã có trong minute/ohlcv/symbols mới có dữ liệu.

Vốn hóa thị trường cổ phiếu Đài Loan

GET/studio/market/twstock/market_value/<stock_id>
Dữ liệu từ
2004-01-01
Tần suất cập nhật
Hằng ngày

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày cuối cùngYYYY-MM-DDmới nhất

Ví dụ

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

Phản hồi

{"stock_id", "data": [{"date", "stock_id", "market_value"}]}; market_value tính bằng TWD.

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • Cache máy chủ: 5 phút.

Xếp hạng vốn hóa thị trường cổ phiếu Đài Loan

GET/studio/market/twstock/market_value/all
Dữ liệu từ
Snapshot (ngày công bố mới nhất)
Tần suất cập nhật
Hằng ngày (cuối ngày)

Tham số

TênMô tảGiá trị hợp lệMặc định
top
int · query
Chỉ giữ N mã đứng đầu theo vốn hóa thị trường1–3000tất cả (~2,400)

Ví dụ

Phản hồi

{"date": "YYYY-MM-DD", "twse_ex_etf_market_value": int, "data": [...]}, sắp xếp giảm dần theo vốn hóa thị trường.

TrườngKiểuMô tả
datestringNgày dữ liệu thực tế được dùng (ngày công bố mới nhất; có thể chậm hơn hôm nay một ngày)
twse_ex_etf_market_valueintTWD. Tổng các dòng có market == "TWSE" và không phải ETF, trong cùng ngày dữ liệu. Đây là mẫu số toàn thị trường — không bị thu hẹp theo top
data[].rankintThứ hạng, tính từ 1
data[].stock_idstringMã
data[].namestringTên
data[].marketstring"TWSE" (上市) hoặc "TPEx" (上櫃), lấy từ danh sách niêm yết của TWSE / TPEx
data[].market_valueintTWD
data[].is_etfbooltrue với các ETF trong bảng xếp hạng (359 trên 2,370 dòng vào ngày 2026-09-17). false nghĩa là "không nằm trong tập ETF", không phải "đã xác nhận không phải ETF": chứng khoán không có phân loại ngành — ví dụ REIT 01010T — là false, và vẫn nằm trong twse_ex_etf_market_value

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "top must be an integer between 1 and 3000"}top không hợp lệ
404{"error": "No recent market value data available"} (hoặc thông báo danh sách niêm yết chưa đầy đủ)Không có dữ liệu gần đây
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết

Ghi chú

  • Rổ cổ phiếu gồm 上市 + 上櫃 + ETF (không gồm 興櫃; ETN không có dữ liệu). Với các câu hỏi kiểu "top N theo vốn hóa", hãy dùng endpoint này thay vì lặp /market_value/<stock_id>.
  • rank và twse_ex_etf_market_value thuộc hai tập hợp khác nhau. rank tính trên toàn thị trường — 上市 + 上櫃, gồm cả ETF — và không thay đổi khi mẫu số được thêm vào. Mẫu số chỉ gồm 上市 và loại trừ ETF (industry_category thuộc {ETF, 上櫃ETF, 上櫃指數股票型基金(ETF)}); REIT và cổ phiếu ưu đãi không bị loại khỏi mẫu số. Vì vậy market_value / twse_ex_etf_market_value chỉ là tỷ trọng trong chỉ số với dòng có market là "TWSE" và không phải ETF — dòng TPEx hoặc ETF chia cho mẫu số này không phải là tỷ trọng — còn rank vẫn là thứ hạng toàn thị trường. Đừng đọc hai giá trị này như cùng một bảng xếp hạng.
  • market là nhãn sàn niêm yết, không phải cờ ETF — is_etf mới là cờ ETF. Hãy dùng nó để có rổ cổ phiếu không chứa ETF. Đừng suy ra ETF từ tiền tố của stock_id (00 là thông lệ thị trường chứ không phải cam kết, và nó bỏ sót REIT 01xxxT), cũng đừng lấy lại phân loại từ nơi khác. is_etf chính là tiêu chí dùng để tính twse_ex_etf_market_value, nên bộ lọc theo is_etf và mẫu số không bao giờ lệch nhau.
  • Cache máy chủ: 30 phút.

P/E / P/B / tỷ suất cổ tức cổ phiếu Đài Loan

GET/studio/market/twstock/per/<stock_id>
Dữ liệu từ
2005-10-01
Tần suất cập nhật
Hằng ngày

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày cuối cùngYYYY-MM-DDmới nhất

Ví dụ

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}, ...]

Phản hồi

{"stock_id", "data": [...]}.

TrườngKiểuMô tả
datestringNgày giao dịch
stock_idstringMã
dividend_yieldfloatTỷ suất cổ tức (%)
PERfloatGiá trên thu nhập (P/E)
PBRfloatGiá trên giá trị sổ sách (P/B)

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • Để sàng lọc giá trị trên nhiều cổ phiếu, dùng batch/per.
  • Dòng của ngày hiện tại lấy từ dữ liệu công bố chính thức của TWSE / TPEx và xuất hiện ngay buổi chiều hôm đó.
  • Cache máy chủ: 5 phút.

Báo cáo kết quả kinh doanh cổ phiếu Đài Loan

GET/studio/market/twstock/financials/<stock_id>
Dữ liệu từ
Mặc định 2013-01-01; sớm hơn nếu yêu cầu
Tần suất cập nhật
Hằng quý

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DD2013-01-01
end
string · query
Ngày cuối cùngYYYY-MM-DDhôm nay

Ví dụ

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")

Phản hồi

{"stock_id", "data": [...]}, định dạng dài (mỗi khoản mục mỗi quý một dòng).

TrườngKiểuMô tả
datestringNgày cuối quý (03-31 / 06-30 / 09-30 / 12-31)
stock_idstringMã
typestringMã khoản mục, ví dụ Revenue, GrossProfit, OperatingIncome, NetIncome, EPS, TAX, OtherComprehensiveIncome
valuefloatGiá trị (TWD; EPS tính bằng TWD trên mỗi cổ phiếu)
origin_namestringNhãn tiếng Trung — dùng để nhận biết các mã type chưa quen

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • start mặc định là 2013-01-01; gửi start sớm hơn thì nhận được các dòng sớm hơn (2330 lùi về đến 2000-06-30).
  • Cache máy chủ: 24 giờ.

Bảng cân đối kế toán cổ phiếu Đài Loan

GET/studio/market/twstock/balance_sheet/<stock_id>
Dữ liệu từ
Mặc định 2013-01-01; sớm hơn nếu yêu cầu
Tần suất cập nhật
Hằng quý

Tham số

Giống /financials/<stock_id>.

Ví dụ

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

Phản hồi

Cùng định dạng dài với /financials/<stock_id>. Các mã type chính: CashAndCashEquivalents, TotalAssets, TotalLiabilities, TotalEquity. Các mã kết thúc bằng _per là % trên tổng tài sản.

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • start mặc định là 2013-01-01; gửi start sớm hơn thì nhận được các dòng sớm hơn (2330 lùi về đến 2012-12-31).
  • Cache máy chủ: 24 giờ.

Báo cáo lưu chuyển tiền tệ cổ phiếu Đài Loan

GET/studio/market/twstock/cashflow/<stock_id>
Dữ liệu từ
Mặc định 2013-01-01; sớm hơn nếu yêu cầu
Tần suất cập nhật
Hằng quý

Tham số

Giống /financials/<stock_id>.

Ví dụ

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

Phản hồi

Cùng định dạng dài với /financials/<stock_id>. Các mã type chính (là mã riêng của bộ dữ liệu upstream; tập đầy đủ thay đổi theo công ty và theo năm, nên hãy coi phản hồi là danh sách chuẩn và dùng origin_name cho những mã không có bên dưới). Hãy lọc theo type, không lọc theo origin_name — nhãn của cùng một mã chuyển qua lại giữa ngoặc toàn chiều rộng và nửa chiều rộng qua các năm:

typeorigin_name
CashFlowsFromOperatingActivities營業活動之淨現金流入（流出）
CashProvidedByInvestingActivities投資活動之淨現金流入（流出）
CashFlowsProvidedFromFinancingActivities籌資活動之淨現金流入（流出）
PropertyAndPlantAndEquipment取得不動產、廠房及設備 (capex, giá trị âm)
Depreciation / AmortizationExpense折舊費用 / 攤銷費用
CashBalancesIncrease本期現金及約當現金增加（減少）數
CashBalancesBeginningOfPeriod / CashBalancesEndOfPeriod期初（年初）/ 期末現金及約當現金餘額

Các khoản mục dòng tiền là lũy kế từ đầu năm (YTD), theo cách công bố tại Đài Loan: dòng 03-31 chỉ là Q1, 06-30 là Q1–Q2, 09-30 là Q1–Q3, 12-31 là cả năm. Để có số liệu một quý, hãy trừ đi quý trước đó trong cùng năm (Q1 không cần trừ) — vì vậy hãy lấy dữ liệu với start từ tháng Một. CashBalancesEndOfPeriod là số dư cuối quý; CashBalancesBeginningOfPeriod là số dư đầu năm. Endpoint này không có tham số period — luôn trả về YTD (chế độ xem từng quý ?period=quarter chỉ có ở route biểu đồ trên web, không có ở đây).

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • start mặc định là 2013-01-01; gửi start sớm hơn thì nhận được các dòng sớm hơn (2330 lùi về đến 2012-03-31).
  • Cache máy chủ: 24 giờ.

Doanh thu tháng cổ phiếu Đài Loan

GET/studio/market/twstock/monthly_revenue/<stock_id>
Dữ liệu từ
2000-01-01
Tần suất cập nhật
Hằng tháng

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DD2000-01-01
end
string · query
Ngày cuối cùngYYYY-MM-DDhôm nay

Ví dụ

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}, ...]

Phản hồi

{"stock_id", "data": [...]}, mỗi tháng một dòng.

TrườngKiểuMô tả
datestringNgày đầu tiên của tháng sau tháng doanh thu — 2024-01-01 mang revenue_year: 2023, revenue_month: 12. Không bao giờ dùng nó làm kỳ doanh thu
stock_idstringMã
countrystringThị trường — giá trị quan sát được là Taiwan
create_timestringQuan sát thấy rỗng ("") ở mọi dòng
revenueintDoanh thu tháng tính bằng TWD (元), không phải nghìn — suy ra từ độ lớn, upstream không ghi rõ: 2330 với revenue_year 2024, revenue_month 1 trả về 215785127000, con số này chỉ hợp lý khi đọc theo 元 (215.8 tỷ NT$)
revenue_monthintTháng doanh thu (1–12) — dùng trường này, không dùng date, để xác định kỳ
revenue_yearintNăm doanh thu

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • Cache máy chủ: 24 giờ.

Chỉ số tài chính cổ phiếu Đài Loan

GET/studio/market/twstock/ratios/<stock_id>
Dữ liệu từ
2013-03-31 (2013 Q1)
Tần suất cập nhật
Hằng quý

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày cuối quý đầu tiênYYYY-MM-DD2013-01-01
end
string · query
Ngày cuối quý cuối cùngYYYY-MM-DDhôm nay

Ví dụ

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")

Phản hồi

{"stock_id", "data": [...]}, định dạng rộng: mỗi quý một dòng, cũ nhất trước, mỗi chỉ số một cột. Mỗi chỉ số là một float làm tròn đến 4 chữ số thập phân, hoặc null.

TrườngKiểuMô tả
datestringNgày cuối quý (03-31 / 06-30 / 09-30 / 12-31) — không phải ngày báo cáo được công bố
stock_idstringMã
<ratio>_qfloat | nullRiêng quý đó
<ratio>_ttmfloat | nullBốn quý gần nhất (cộng bốn quý đơn lẻ); null nếu thiếu bất kỳ quý nào trong bốn quý
debt_ratio, current_ratio, quick_ratio, equity_multiplierfloat | nullChỉ số bảng cân đối kế toán cuối kỳ — không có hậu tố

<ratio> (mỗi chỉ số có cả _q và _ttm):

NhómChỉ sốĐơn vị
Khả năng sinh lờigross_margin, operating_margin, pretax_margin, net_margin, opex_ratio, roe, roa% (đã ×100)
Trên mỗi cổ phiếueps, revenue_per_share, fcf_per_shareTWD trên mỗi cổ phiếu
Tăng trưởngrevenue_yoy, revenue_qoq, operating_income_yoy, net_income_yoy, eps_yoy% (đã ×100)
Cơ cấuinterest_coveragelần
Hiệu quả hoạt độngreceivable_turnover, inventory_turnover, asset_turnover, cfo_to_net_incomelần
Dòng tiềnfcfTWD, số tiền gốc (không phải nghìn)

Các cột không có hậu tố: debt_ratio, current_ratio, quick_ratio là % (đã ×100 — hệ số thanh toán hiện hành 2.46× trả về là 245.7635); equity_multiplier tính bằng lần.

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id"}Mã không qua kiểm tra định dạng
404{"error": "No data found for stock_id: <id>"}Mã này không có báo cáo tài chính (các ETF như 0050 / 00878), hoặc không có dòng nào trong khoảng start–end
503{"error": "Data temporarily unavailable. Please retry shortly."}Kho chỉ số chưa sẵn sàng — thử lại sau, không bao giờ đọc thành "không có dữ liệu"

Ghi chú

  • ROE / ROA của một quý không được quy đổi theo năm; các số liệu trên mỗi cổ phiếu dùng số lượng cổ phiếu suy ra từ lợi nhuận ròng ÷ EPS; ngân hàng, công ty chứng khoán và công ty bảo hiểm có một số chỉ số luôn là null (không có biên lợi nhuận gộp, hệ số thanh toán hiện hành, v.v.).
  • Các dòng được gắn ngày cuối quý, nhưng báo cáo của một quý chỉ được công bố sau đó vài tuần. Khi backtest, hãy dời mỗi dòng về ngày dữ liệu thực sự có sẵn (hạn nộp báo cáo theo luật định, giống với các báo cáo tài chính) — ghép theo date là lookahead bias.
  • Thiếu khoản mục hoặc mẫu số bằng không sẽ cho null, không bao giờ là 0.
  • Không bao gồm: P/E / P/B / tỷ suất cổ tức (hằng ngày — per/<stock_id>) và các chỉ số doanh thu tháng (tự tính YoY / MoM từ monthly_revenue/<stock_id>).
  • Nhiều cổ phiếu → GET /studio/market/twstock/batch/ratios?stock_ids=... (≤ 50 mã mỗi lần gọi).
  • 2013-03-31 là giới hạn dưới cứng: start sớm hơn cũng không trả về dữ liệu cũ hơn.
  • Được tính lại bởi chính job làm mới các báo cáo tài chính, hai lần mỗi ngày (13:30 và 23:00 UTC).
  • Cache máy chủ: 6 giờ.

Sự kiện cổ tức cổ phiếu Đài Loan

GET/studio/market/twstock/dividend/<stock_id>
Dữ liệu từ
Tùy từng mã (2330: 2005-06-19)
Tần suất cập nhật
Làm mới khi có request nếu dữ liệu đã cũ

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãMã đang niêm yết (4–6 chữ số, có thể kèm một chữ cái ở cuối)
start
string · query
Ngày hiệu lực đầu tiênbắt buộc đúng YYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày hiệu lực cuối cùngbắt buộc đúng YYYY-MM-DDtoàn bộ lịch sử

Việc lọc theo khoảng dùng ngày hiệu lực ba bậc: cash_ex_date nếu có, nếu không thì stock_ex_date, nếu không nữa thì record_date — các sự kiện vừa công bố, chưa có ngày trừ cổ tức, vẫn xuất hiện.

Ví dụ

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}, ...]

Phản hồi

{"stock_id", "data": [...]}, mỗi dòng công bố một dòng.

TrườngKiểuMô tả
record_datestring權利分派基準日 YYYY-MM-DD
periodstring股利所屬期間 — một nhãn không có cấu trúc (114年第3季, 113, 不適用, …); hãy so sánh dạng chuỗi, đừng phân tích thành năm
announce_datestring公告日; "" khi không rõ
cash_ex_datestring除息交易日; "" khi không có / chưa quyết định
stock_ex_datestring除權交易日; "" khi không có
pay_datestring現金股利發放日; "" khi không rõ
cashfloatCổ tức tiền mặt trên mỗi cổ phiếu (TWD, 盈餘 + 公積)
stockfloatCổ tức cổ phiếu trên mỗi cổ phiếu (元面額, 盈餘 + 公積)
stock_ratiofloatstock / 10 — tỷ lệ điều chỉnh kiểu chia tách

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id"}Không qua kiểm tra định dạng
400{"error": "Invalid start date, expected YYYY-MM-DD"} (hoặc end)Ngày sai định dạng
404{"error": "No data found for stock_id: <id>"} / {"error": "No dividend records for stock_id: <id>"}Không niêm yết, hoặc hoàn toàn không có lịch sử cổ tức
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết

Ghi chú

  • Các dòng giá trị bằng không (cash == 0 và stock == 0) vẫn được giữ — đó là quyết định không chia cổ tức đã được công bố.
  • Ngày hiệu lực có thể nằm trong tương lai (đã công bố nhưng chưa đến ngày trừ cổ tức) — lần gọi toàn bộ lịch sử của 2330 kéo dài đến một ngày sau thời điểm request một tuần. Hãy tự lọc theo ngày nếu bạn chỉ cần các sự kiện đã qua.
  • Cổ phiếu hợp lệ, có lịch sử nhưng không có sự kiện nào trong khoảng sẽ trả về 200 + [] (khác với 404).
  • Cổ phiếu đã hủy niêm yết trả về 404.

Tin tức cổ phiếu Đài Loan

GET/studio/market/twstock/news/<stock_id>
Dữ liệu từ
Khoảng giữa năm 2020 (thưa thớt cho đến khoảng 2021-02)
Tần suất cập nhật
Lấy khi có request

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày bắt đầuYYYY-MM-DDhôm nay − 6 ngày
end
string · query
Ngày cuối cùng; end − start ≤ 31 ngàyYYYY-MM-DDhôm nay

Ví dụ

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"]

Phản hồi

{"stock_id", "data": [...]}, mỗi ngày vài bài (gồm cả cuối tuần).

TrườngKiểuMô tả
datestringThời điểm đăng
stock_idstringMã
titlestringTiêu đề
sourcestringNguồn đăng
linkstringURL

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Date range exceeds 31 days"} hoặc một thông báo lỗi phân tích ngàyKhoảng thời gian quá dài / ngày sai định dạng
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết

Ghi chú

  • Dữ liệu bắt đầu từ khoảng giữa năm 2020 (có dòng sớm nhất từ 2020-08; điểm bắt đầu thực sự không được ghi nhận) và thưa thớt — mỗi ngày vài bài hoặc không có bài nào — cho đến khoảng 2021-02; các ngày sớm hơn có thể trả về [].
  • Bài viết của mỗi ngày được lấy ở request đầu tiên cho ngày đó.
  • Cache máy chủ: 5 phút.

Nhà đầu tư tổ chức cổ phiếu Đài Loan

GET/studio/market/twstock/institutional/<stock_id>
Dữ liệu từ
Tùy từng mã (2330: 2012-05-02)
Tần suất cập nhật
Hằng ngày

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày cuối cùngYYYY-MM-DDmới nhất

Ví dụ

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}, ...]

Phản hồi

{"stock_id", "data": [...]}, định dạng rộng, mỗi ngày một dòng. Mọi giá trị tính bằng cổ phiếu (股).

TrườngMô tả
date, stock_idNgày, mã
foreign_buy / foreign_sell外資 (không gồm tự doanh nước ngoài)
trust_buy / trust_sell投信
dealer_self_buy / dealer_self_sell自營商自行買賣
dealer_hedge_buy / dealer_hedge_sell自營商避險
foreign_dealer_self_buy / foreign_dealer_self_sell外資自營商 (phần lớn là 0)

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • Mua ròng = *_buy − *_sell.
  • Tầng từng cổ phiếu — không gộp nhóm. Đây là các cột gốc theo từng loại; gộp nhóm thế nào là do bạn quyết định. Các bề mặt theo từng cổ phiếu của chính Blave (web, app, AI chat) tính 外資自營商 vào 外資, khớp với cách đặt tên cột của chính các sàn, và coi 自營商 là 自行買賣 cộng 避險. Endpoint toàn thị trường (GET /studio/market/twmarket/institutional) gộp nhóm theo cách khác — xem mục đó.
  • Dòng của ngày hiện tại lấy từ dữ liệu công bố chính thức của TWSE / TPEx và xuất hiện khi các sàn đã công bố.
  • Cache máy chủ: 5 phút.

Giao dịch ký quỹ cổ phiếu Đài Loan

GET/studio/market/twstock/margin/<stock_id>
Dữ liệu từ
Tùy từng mã (2330: 2001-01-05)
Tần suất cập nhật
Hằng ngày

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày cuối cùngYYYY-MM-DDmới nhất

Ví dụ

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"]   # 融資使用率

Phản hồi

{"stock_id", "data": [...]}, mỗi ngày một dòng. Giá trị tính bằng lô (張), không phải cổ phiếu — đã đối chiếu với TWSE MI_MARGN: với ngày 2026-09-15, 2330 trả về margin_balance: 29282 và margin_limit: 6483092, khớp chính xác với 今日餘額 29,282 và 次一營業日限額 6,483,092 do chính TWSE công bố cho ngày đó. Mỗi dòng mang date và stock_id riêng; khi đọc toàn bộ lịch sử (không có start / end), hãy lấy mọi con số từ cùng một dòng — margin_limit được công bố lại mỗi ngày và thay đổi theo thời gian.

TrườngMô tả
margin_buy / margin_sell融資買進 / 賣出
margin_cash_repay融資現金償還
margin_balance / margin_prev_balance融資今日 / 前日餘額
margin_limit融資限額 — 次一營業日限額 của TWSE được công bố vào ngày của dòng đó, tức là hạn mức áp dụng cho ngày làm việc KẾ TIẾP (2330 ngày 2026-09-15: 6,483,092 lô)
short_buy / short_sell融券買進 / 賣出
short_cash_repay融券現金償還
short_balance / short_prev_balance融券今日 / 前日餘額
short_limit融券限額
offset_loan_short資券相抵

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • Cache máy chủ: 5 phút.

Phân bố sở hữu cổ phần cổ phiếu Đài Loan

GET/studio/market/twstock/shareholding/<stock_id>
Dữ liệu từ
Tùy từng mã (2330: 2010-01-29)
Tần suất cập nhật
Hằng tuần, thứ Sáu

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày cuối cùngYYYY-MM-DDmới nhất

Ví dụ

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"]

Phản hồi

{"stock_id", "data": [...]}, mỗi cặp ngày × nhóm một dòng.

TrườngKiểuMô tả
datestringNgày của tuần dữ liệu
stock_idstringMã
levelstringNhóm sở hữu: 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）
peopleintSố cổ đông
unitintSố cổ phiếu nắm giữ
percentfloat% trên số cổ phiếu đã phát hành

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • Số liệu là bảng phân bố sở hữu cổ phần do TDCC (集保結算所) công bố.
  • Cache máy chủ: 5 phút.

Sở hữu của khối ngoại cổ phiếu Đài Loan

GET/studio/market/twstock/foreign_shareholding/<stock_id>
Dữ liệu từ
Mặc định 2013-01-01; sớm hơn nếu yêu cầu
Tần suất cập nhật
Hằng ngày

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DD2013-01-01
end
string · query
Ngày cuối cùngYYYY-MM-DDhôm nay

Ví dụ

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

Phản hồi

{"stock_id", "data": [...]}, mỗi ngày một dòng.

TrườngMô tả
date, stock_idNgày, mã
ForeignInvestmentSharesSố cổ phiếu khối ngoại nắm giữ
ForeignInvestmentSharesRatioTỷ lệ sở hữu của khối ngoại (%)
ForeignInvestmentRemainingSharesSố cổ phiếu khối ngoại còn được mua
ForeignInvestmentRemainRatioTỷ lệ còn lại (%)
ForeignInvestmentUpperLimitRatioGiới hạn sở hữu của khối ngoại (%)
ChineseInvestmentUpperLimitRatioGiới hạn sở hữu của nhà đầu tư Trung Quốc đại lục (%)
NumberOfSharesIssuedSố cổ phiếu đã phát hành

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • start mặc định là 2013-01-01; gửi start sớm hơn thì nhận được các dòng sớm hơn (2330 lùi về đến 2004-02-12).
  • Cache máy chủ: 24 giờ.

Mua/bán của ngân hàng quốc doanh cổ phiếu Đài Loan

GET/studio/market/twstock/gov_bank/<stock_id>
Dữ liệu từ
2021-06-30
Tần suất cập nhật
Hằng ngày

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày bắt đầuYYYY-MM-DDhôm nay − 6 ngày
end
string · query
Ngày cuối cùng; end − start ≤ 31 ngàyYYYY-MM-DDhôm nay

Ví dụ

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"]

Phản hồi

{"stock_id", "data": [...]}, tối đa 8 dòng mỗi ngày (mỗi ngân hàng một dòng), sắp xếp theo ngày, ngân hàng.

TrườngMô tả
date, stock_idNgày, mã
bank_nameNgân hàng
buy / sellSố cổ phiếu mua / bán
buy_amount / sell_amountGiá trị mua / bán (TWD)

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Date range exceeds 31 days"} hoặc một thông báo lỗi phân tích ngàyKhoảng thời gian quá dài / ngày sai định dạng
503{"error": "Upstream rate limit. Please retry shortly."}Quota upstream đã hết

Ghi chú

  • Cache máy chủ: 5 phút.

Cho vay chứng khoán cổ phiếu Đài Loan

GET/studio/market/twstock/lending/<stock_id>
Dữ liệu từ
2001-05-01
Tần suất cập nhật
Hằng ngày

Tham số

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
start
string · query
Ngày đầu tiênYYYY-MM-DDtoàn bộ lịch sử
end
string · query
Ngày cuối cùngYYYY-MM-DDmới nhất

Ví dụ

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

Phản hồi

{"stock_id", "data": [...]}, mỗi ngày vài dòng.

TrườngMô tả
date, stock_idNgày, mã
transaction_type競價 / 議借
volumeKhối lượng
fee_rateLãi suất phí cho vay
closeGiá đóng cửa
original_return_dateNgày hoàn trả ban đầu
original_lending_periodThời hạn cho vay ban đầu

Lỗi

400 stock_id không hợp lệ, 404 không có dữ liệu, 503 hết quota upstream.

Ghi chú

  • Cache máy chủ: 5 phút.

Mua/bán của môi giới theo cổ phiếu

GET/studio/market/twstock/broker/stock/<stock_id>
Dữ liệu từ
2021-06-30
Tần suất cập nhật
Hằng ngày, sau khoảng 21:30 giờ Đài Bắc

Tham số

Gửi date cho một ngày, hoặc start (+ end) cho một khoảng; start được ưu tiên nếu gửi cả hai.

TênMô tảGiá trị hợp lệMặc định
stock_id
string · pathBắt buộc
MãXem quy ước chung của danh mục
date
string · query
Một ngàyYYYY-MM-DDhôm nay
start
string · query
Đầu khoảngYYYY-MM-DD
end
string · query
Cuối khoảng; khoảng ≤ 366 ngày, tính cả hai đầuYYYY-MM-DDstart

Ví dụ

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"]

Phản hồi

{"stock_id", "data": [...]}, mỗi chi nhánh mỗi ngày một dòng.

TrườngKiểuMô tả
datestringNgày giao dịch
stock_idstringMã
broker_idstringMã chi nhánh (có thể gồm cả chữ và số, ví dụ 920A)
broker_namestringTên chi nhánh
pricefloatGiá khớp bình quân gia quyền theo khối lượng
buy / sellintSố cổ phiếu mua / bán

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid stock_id"}Không qua kiểm tra định dạng
400{"error": "Invalid date (YYYY-MM-DD)"}Ngày sai định dạng
400{"error": "start/end range is <n> days; max 366 (inclusive) — split into smaller ranges"}Khoảng thời gian quá dài
503{"error": "Upstream rate limit. Please retry shortly."}Dữ liệu tạm thời không khả dụng — thử lại; đừng đọc thành "không có giao dịch"

Ghi chú

  • Ngày không có dữ liệu (ngày nghỉ, trước 2021-06-28, hoặc hôm nay trước ~21:30) trả về 200 + [].
  • Truy vấn theo khoảng đang hoạt động: start / end trên 2026-09-06 → 2026-09-13 trả về các dòng trải trên năm ngày giao dịch khác nhau, với cả broker/stock/<stock_id> lẫn broker/trader/<trader_id>.
  • Cache máy chủ: 5 phút.

Mua/bán của môi giới theo chi nhánh

GET/studio/market/twstock/broker/trader/<trader_id>
Dữ liệu từ
2021-06-30
Tần suất cập nhật
Hằng ngày, sau khoảng 21:30 giờ Đài Bắc

Tham số

Cùng quy tắc date / start / end với /broker/stock/<stock_id>.

TênMô tảGiá trị hợp lệMặc định
trader_id
string · pathBắt buộc
Mã chi nhánh lấy từ /broker/searchChữ cái, chữ số, - (ví dụ 9217, 920A)
date
string · query
Một ngàyYYYY-MM-DDhôm nay
start
string · query
Đầu khoảngYYYY-MM-DD
end
string · query
Cuối khoảng; khoảng ≤ 366 ngày, tính cả hai đầuYYYY-MM-DDstart

Ví dụ

Python
rows = requests.get(f"{BASE_URL}/studio/market/twstock/broker/trader/9217", headers=headers,                    params={"date": "2026-08-07"}, timeout=60).json()["data"]

Phản hồi

{"trader_id", "data": [...]}, mỗi cổ phiếu mỗi ngày một dòng; các trường date, broker_id, broker_name, stock_id, price, buy, sell (giống /broker/stock).

Lỗi

Giống /broker/stock/<stock_id>, kèm 400 {"error": "Invalid trader_id"} khi mã không hợp lệ.

Ghi chú

  • Cache máy chủ: 5 phút.

Công bố cảnh báo và xử lý cổ phiếu Đài Loan

GET/studio/market/twstock/alerts
Dữ liệu từ
TWSE 2001-01; TPEx cảnh báo 2002-02, xử lý 2003-09
Tần suất cập nhật
Hằng ngày lúc 17:45, 21:30 và 07:00 giờ Đài Bắc

Tham số

Truyền date, hoặc start / end, hoặc không truyền gì (= hôm nay, giờ Đài Bắc).

TênMô tảGiá trị hợp lệMặc định
date
string · query
Một ngày: các quyết định xử lý đang có hiệu lực trong ngày đó, các cảnh báo được công bố trong ngày đóbắt buộc đúng YYYY-MM-DD; không dùng cùng start / end
start
string · query
Ngày đầu tiên của khoảngbắt buộc đúng YYYY-MM-DD2001-01-01 khi có stock_id, ngược lại là end − 365 ngày
end
string · query
Ngày cuối cùng của khoảng (bao gồm cả ngày đó)bắt buộc đúng YYYY-MM-DDhôm nay (hoặc start nếu muộn hơn)
kind
string · query
Loại công bốdisposal (處置), notice (注意)cả hai
market
string · query
Sàn giao dịchtwse, tpexcả hai
stock_id
string · query
Một mã; gỡ bỏ giới hạn 366 ngàyXem quy ước chung của danh mụctất cả

Ý nghĩa của khoảng: một quyết định xử lý được trả về khi thời hạn của nó (start–end) giao với khoảng truy vấn, một cảnh báo được trả về khi date công bố nằm trong khoảng. Không có stock_id thì khoảng tối đa là 366 ngày, tính cả hai đầu — hãy chia nhỏ các khoảng toàn thị trường dài hơn (mỗi lần gọi một năm dương lịch là vừa). Khác với mặc định của danh mục, start / end / date được kiểm tra nghiêm ngặt.

Ví dụ

Phản hồi

{"start", "end", "data": [...]}; start / end trả lại khoảng thực tế được dùng (cả hai bằng date khi gửi date). Các dòng sắp xếp theo date, market, kind, stock_id. Mỗi công bố một dòng.

TrườngKiểuMô tả
datestringNgày công bố YYYY-MM-DD (quyết định xử lý có hiệu lực từ ngày giao dịch kế tiếp)
stock_idstringMã — gồm cả chứng quyền, ETF và trái phiếu chuyển đổi (ví dụ 037060, 45402)
stock_namestring | nullTên như trong công bố
marketstringtwse (上市) hoặc tpex (上櫃)
kindstringdisposal hoặc notice
countintSố lần lũy kế của sàn (累計 / 累計次數)
start, endstring | nullThời hạn xử lý, tính cả hai ngày đầu cuối; null với cảnh báo
conditionstring | nullXử lý: điều kiện kích hoạt như trong công bố (連續三次, 連續3個營業日, 最近十個營業日已有六次 …). Cảnh báo: các điều khoản được viện dẫn (第一款、第五款); null nếu không có
measurestring | nullLoại xử lý: 第一次處置, 第二次處置, 再次處置, 人工管制撮合, 收足五成款券 …; null với cảnh báo và với các dòng TPEx thời kỳ đầu
match_minutesint | nullXử lý: N trong 「約每N分鐘撮合一次」 đọc từ nội dung; null khi nội dung không nêu (mọi quyết định xử lý của TWSE trước ~2011 — phần nội dung để trống — và các biện pháp không liên quan đến khớp lệnh) và với cảnh báo
reasonstring | nullToàn văn công bố; null khi sàn không công bố nội dung (mọi quyết định xử lý của TWSE trước 2011-03) (xử lý là 處置內容, cảnh báo là 注意交易資訊)
close, pefloat | nullGiá đóng cửa và P/E tại thời điểm công bố; luôn là null với các quyết định xử lý của TWSE

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Invalid start date, expected YYYY-MM-DD"} (hoặc end)start / end sai định dạng
400{"error": "start must not be after end"}Khoảng bị đảo ngược
400{"error": "Invalid date, expected YYYY-MM-DD"}date sai định dạng
400{"error": "use either date or start/end"}date được gửi cùng start hoặc end
400{"error": "Invalid stock_id"}Không qua kiểm tra định dạng
400{"error": "kind must be one of ['disposal', 'notice']"} / {"error": "market must be one of ['twse', 'tpex']"}Giá trị không xác định
400{"error": "start/end range is <n> days; max 366 (inclusive) without stock_id — split into smaller ranges"}Khoảng trên 366 ngày mà không có stock_id
503{"error": "Data temporarily unavailable. Please retry shortly."}Một bảng bạn yêu cầu hiện không phục vụ được (không được làm mới trong 48 giờ, hoặc không đọc được) — thử lại sau, không bao giờ đọc thành "không có công bố". Chỉ các bảng kind / market được yêu cầu mới được kiểm tra

Ghi chú

  • Quyết định xử lý được công bố sau giờ đóng cửa và có hiệu lực từ ngày giao dịch kế tiếp — date là ngày công bố, start là ngày đầu tiên có hiệu lực. Để hỏi "có đang bị xử lý vào ngày D không", dùng date=D (hoặc start=end=D), không dùng ngày công bố.
  • Một cổ phiếu có thể có các thời hạn xử lý chồng lên nhau (một 第二次處置 được công bố trong thời hạn của lần đầu).
  • start / end là thời hạn theo công bố; ngày nghỉ thị trường hoặc tạm ngừng giao dịch trong thời hạn đó sẽ kéo dài ngày kết thúc thực tế, điều mà dữ liệu không ghi nhận.
  • match_minutes theo quy định tại thời điểm đó (TPEx 5 / 20 phút → 2 từ 2026-08-10) — hãy đọc theo từng dòng, không bao giờ giả định một giá trị.
  • Không bao gồm danh sách ứng viên trước khi xử lý (處置候選).
  • Khi trích dẫn, ghi 「資料來源：臺灣證券交易所、證券櫃檯買賣中心」.
  • Ngày bắt đầu của TWSE áp dụng cho cả xử lý lẫn cảnh báo.
  • Công bố buổi tối của TPEx có thể lần đầu xuất hiện ở lượt chạy 07:00.

Truy vấn hàng loạt cổ phiếu Đài Loan

GET/studio/market/twstock/batch/<data_type>
Dữ liệu từ
Tùy data_type (giống endpoint đơn mã)
Tần suất cập nhật
Tùy data_type

Tham số

TênMô tảGiá trị hợp lệMặc định
data_type
string · pathBắt buộc
Bộ dữ liệuprice, price_adj, per, institutional, shareholding, foreign_shareholding, financials, balance_sheet, monthly_revenue, ratios, dividend
stock_ids
string · queryBắt buộc
MãPhân tách bằng dấu phẩy, ≤ 50
start
string · query
Ngày đầu tiênYYYY-MM-DD (chỉ kiểm tra nghiêm ngặt với dividend)tùy data_type
end
string · query
Ngày cuối cùngYYYY-MM-DDtùy data_type

Ví dụ

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

Phản hồi

{"data_type", "data": {"<stock_id>": [...rows...]}, "failed": [...]}. Các dòng giống hệt endpoint đơn mã tương ứng.

  • failed — các mã mà việc lấy dữ liệu phía máy chủ thất bại (giới hạn tần suất hoặc lỗi upstream); hãy thử lại các mã đó.
  • Mã không có trong cả data lẫn failed thì thực sự không có dữ liệu.

Lỗi

Mã trạng tháiNội dung phản hồiTrường hợp
400{"error": "Unsupported data_type '<x>'. Supported: [...]"}data_type không hợp lệ
400{"error": "stock_ids parameter required"}Thiếu
400{"error": "stock_ids exceeds max 50 per request"}Quá nhiều
400{"error": "Invalid stock_id in list"}Có mã không qua kiểm tra định dạng
400{"error": "Invalid start date, expected YYYY-MM-DD"}Chỉ với dividend

Ghi chú

  • Toàn thị trường (~2,000 cổ phiếu) cần ~40 lần gọi; không bao giờ gọi tỏa ra các endpoint đơn mã.
  • ratios (財務比率): các dòng của mỗi mã chính là các dòng định dạng rộng theo quý của /ratios/<stock_id> ("data": {"2330": [{"date": "2026-06-30", "stock_id": "2330", "roe_q": 11.3934, ...}], "2317": [...]}). Mã không có báo cáo tài chính (ETF) không xuất hiện trong cả data lẫn failed (không trả 404); khi kho chỉ số chưa sẵn sàng, mọi mã đều nằm trong failed (không trả 503).
  • dividend khác với /dividend/<stock_id>: nó chỉ đọc dữ liệu đã lưu (không làm mới), mã không xác định hoặc cổ phiếu không có lịch sử cổ tức sẽ lặng lẽ không xuất hiện (không trả 404), và sự cố quota upstream thể hiện trong failed, không phải bằng 503.