Nguồn dữ liệu
Mục lục
Thư viện vnstock chạy trên máy của bạn và gửi truy vấn thẳng tới nguồn bên thứ ba. Mỗi hàm có
một nguồn mặc định. Hàm nào có tham số source thì bạn chọn được nguồn khác trong danh sách hàm
đó nhận. Trang này liệt kê cả hai cho thế hệ 5. Trong các bảng, dấu — nghĩa là hàm không có
tham số source và luôn dùng nguồn mặc định.
Nguồn mặc định có thể đổi giữa các bản khi một nguồn ngừng phục vụ. Đọc nguồn thực tế của một kết quả ở df.attrs["source"].
Ba quy tắc
source=có tác dụng thật. Hỏi nguồn nào thì nhận dữ liệu của nguồn đó. Viết hoa hay thường đều được. Nguồn hàm không có, hay gõ sai tên, thì nhậnUnsupportedErrornêu các nguồn dùng được cho hàm đó.- Không tự chuyển nguồn. Nguồn bạn chọn (hoặc nguồn mặc định) lỗi thì bạn nhận ngoại lệ, không nhận dữ liệu của nguồn khác. Muốn dự phòng, tự viết vòng thử (ví dụ ở cuối trang).
- Cấp quyền giới hạn cả nguồn. Cấp Khách và Cộng đồng chỉ dùng được một số nguồn. Gọi nguồn
ngoài cấp thì nhận
EntitlementErrormãVNSTOCK_TIER_SOURCE, và thư viện không gửi truy vấn nào đi. Xem nguồn của cấp mình bằngvnstock policy.
Mã nguồn
source= | Dùng cho |
|---|---|
vci | Giá cổ phiếu, thông tin công ty, báo cáo tài chính, danh sách mã, phân ngành ICB, lịch sự kiện |
kbs | Bảng giá, sổ lệnh, chỉ số, phái sinh, chứng quyền, ETF, trái phiếu, thành phần chỉ số, một số thông tin công ty |
vnd | Xếp hạng thị trường, định giá P/E, P/B |
mas | Báo cáo tài chính, trạng thái thị trường (khi chọn rõ) |
asean | Vĩ mô, dòng tiền, độ rộng thị trường |
binance | Tiền mã hoá |
dukascopy | Ngoại hối, hàng hoá thế giới, chỉ số thế giới, tìm kiếm mã quốc tế |
cafef, digiinvest | Quỹ mở |
vcb | Tỷ giá ngân hàng Vietcombank |
builtin | Bảng có sẵn trong thư viện (danh sách và thông tin chỉ số, lịch thị trường, trạng thái phiên tính từ lịch giao dịch), không gửi truy vấn |
Nguồn đã ngừng: mbk, fmarket, btmc, spl. Truyền chúng vào thì nhận UnsupportedError mã
VNSTOCK_FEATURE_REMOVED, kèm nguồn dùng thay nếu có. Nguồn của bản cũ không có ở thế hệ 5
(msn, tcbs, fxsb, fmp, dnse) cũng báo lỗi, kèm tên các nguồn dùng được.
Ngoài source= ở từng lời gọi, bạn đổi được nguồn mặc định của một hàm cho cả chương trình bằng
set_route(). Thứ tự chọn nguồn: source= của lời gọi, rồi set_route(), rồi nguồn mặc định.
from vnstock.ui.config import set_route
set_route("market.equity.trades", "kbs", "quote", "Quote", "intraday")set_route() chỉ nhận nguồn có sẵn trong thư viện; ba đối số cuối giữ cho tương thích và không
được dùng.
Market
Cổ phiếu: Market().equity(symbol)
| Hàm | Mặc định | source= nhận |
|---|---|---|
ohlcv (history) | vci | vci, kbs, vnd, mas, asean |
trades (intraday) | vci | vci, kbs, vnd, mas, asean |
quote (price_board) | kbs | kbs, vci, asean |
order_book (price_depth) | kbs | kbs, vci, mas, asean |
volume_profile (matched_by_price) | kbs | kbs, vci |
session_stats (trading_stats) | vci | vci, kbs, asean |
block_trades (put_through) | kbs | kbs, vci, asean |
odd_lot | kbs | kbs, vci, asean |
foreign_flow, proprietary_flow, trade_history | vci | vci |
Hai hàm cố ý lấy nguồn khác vnstock_data 3.x:
ohlcvlấy từ VCI (bản cũ: KBS). Giá điều chỉnh sau sự kiện quyền của hai nguồn lệch nhau vài đồng. Muốn số như bản cũ, truyềnsource="kbs".tradeslấy từ VCI (bản cũ: VND). Mặc định trả 100 lệnh mỗi lần gọi; VCI trả tối đa 1.000 lệnh mỗi lần và hỗ trợ phân trang qualast_id. Cần lấy khối lượng lớn một lần thì dùngsource="kbs"kèmlimit=.
ETF, trái phiếu, chỉ số, phái sinh, chứng quyền
| Hàm | Mặc định | source= nhận |
|---|---|---|
Market().etf(s).ohlcv, .trades | kbs | như cổ phiếu |
Market().etf(s).quote, .order_book, .block_trades, .odd_lot | kbs | như cổ phiếu |
Market().bond(s).ohlcv, .trades | kbs | như cổ phiếu |
Market().bond(s).quote, .order_book | kbs | như cổ phiếu |
Market().index(s).ohlcv | kbs; nến 1m tới 1H: vci | kbs, vci |
Market().index(s).quote, .trades | kbs | kbs |
Market().index(s).trade_history | vci | — |
Market().futures(s).ohlcv, Market().warrant(s).ohlcv | kbs; nến 1m tới 1H: vci | kbs, vci |
Market().futures(s).quote, .trades, .order_book | kbs | kbs |
Market().warrant(s).quote, .trades, .order_book | kbs | kbs |
Market().index(s, scope="global").ohlcv, .trades | dukascopy | dukascopy |
ETF và trái phiếu lấy giá lịch sử và khớp lệnh từ KBS, như bản cũ. Nến trong phiên (1m tới 1H)
của chỉ số, hợp đồng tương lai và chứng quyền lấy từ VCI khi bạn không ghi source=, như bản cũ;
nến ngày, tuần, tháng vẫn lấy từ KBS.
Market().index(symbol, scope="global") đọc chỉ số thế giới từ Dukascopy, thời gian theo UTC.
Khi nguồn từ chối truy cập tự động, lời gọi báo ChallengeRequiredError (mã
VNSTOCK_SOURCE_CHALLENGE) và thư viện không thử lại.
Tài sản quốc tế
| Hàm | Mặc định | source= nhận |
|---|---|---|
Market().crypto(s).ohlcv | binance | binance |
Market().crypto(s) các hàm khác (trades, order_book, quote, vwap…) | binance | binance |
Market().forex(s).ohlcv | dukascopy | dukascopy |
Market().commodity(s).ohlcv | dukascopy | dukascopy |
Giá tiền mã hoá tính theo đồng định giá của cặp trên Binance (ví dụ USDT cho BTCUSDT). Thời gian
của nhóm này theo UTC; timezone= khác UTC ở ngoại hối, hàng hoá, chỉ số thế giới nhận lỗi kèm
cách đổi giờ bằng df["time"].dt.tz_convert("Asia/Ho_Chi_Minh").
Tiền mã hoá chỉ có nguồn binance. Truyền nguồn khác, ví dụ source="msn" của mã 4.x, thì nhận
lỗi chỉ sang source="binance".
Hàm toàn thị trường
| Hàm | Mặc định |
|---|---|
Market().quote(symbols) (price_board) | kbs |
Market().odd_lot(symbols), Market().put_through(symbols) | kbs, trả đúng các mã truyền vào |
Market().fund(s).history, .holdings… | cafef; digiinvest cho dividends |
Quỹ mở xem riêng ở Dữ liệu quỹ mở.
Reference
| Hàm | Mặc định | source= nhận |
|---|---|---|
Reference().company(s).info, .overview, .shareholders, .officers, .subsidiaries, .affiliate, .events | vci | vci, kbs |
Reference().company(s).ownership, .capital_history, .insider_trading | kbs | kbs |
Reference().company(s).shareholders(mode="summary") | vci | vci |
Reference().equity.list | vci | — |
Reference().equity.list_by_group | vci | vci, kbs |
Reference().equity.list_by_exchange, .list_by_industry | vci | vci |
Reference().industry.list, .sectors | vci | vci |
Reference().index.list | builtin | builtin |
Reference().index(s).info, .description | builtin | — |
Reference().index.groups | kbs | — |
Reference().index.members, Reference().index(s).members, Reference().index.list_by_group | kbs, đọc VNINDEX, HNXINDEX, UPCOMINDEX là cả sàn HOSE, HNX, UPCOM | kbs, vci |
Reference().etf.list | kbs | kbs, vci |
Reference().futures.list, Reference().warrant.list | vci | vci, kbs |
Reference().futures(s).info, Reference().warrant(s).info, Reference().bond(s).info | kbs | — |
Reference().bond.list | kbs (doanh nghiệp), vci (chính phủ) | — |
Reference().events.calendar | vci | — |
Reference().events.market | builtin | — |
Reference().market.status | builtin | builtin, mas |
Reference().search.symbol, .info | dukascopy | — |
Reference().fund.list | cafef | cafef, digiinvest |
Reference().market.status() tính trạng thái phiên ngay trên máy từ lịch giao dịch và lịch nghỉ có
sẵn trong thư viện, như bản 4.x, nên không gửi truy vấn và mọi cấp đều gọi được.
source="mas" hỏi nguồn MAS, dành cho cấp tài trợ.
Reference().bond.list() mặc định gộp hai danh sách: trái phiếu doanh nghiệp từ KBS và trái phiếu
chính phủ từ VCI. Nếu phần trái phiếu chính phủ không lấy được (nguồn này bị chặn ở một số mạng),
thư viện trả phần doanh nghiệp kèm một cảnh báo UserWarning; phần doanh nghiệp lỗi thì cả lời gọi
báo lỗi. Gọi riêng bond.list("government") để xem lỗi đầy đủ của phần chính phủ.
Market().equity(symbol).volume_profile() (tên cũ matched_by_price) trả khối lượng khớp theo từng
bước giá, gồm mua, bán và chưa xác định. Hàm này dành cho cấp tài trợ.
Bản 4.x đổi nguồn phân ngành sang KBS khi chạy trên Google Colab. Thế hệ 5 không đổi nguồn theo môi trường.
Fundamental, Macro, Insights, Analytics, Retail
| Hàm | Mặc định | source= nhận |
|---|---|---|
Fundamental().equity(s).income_statement, .balance_sheet, .cash_flow, .ratio | vci | vci, kbs, mas |
Fundamental().equity(s).note | vci | — |
Macro().economy().*, Macro().currency().* | asean | — |
Macro().global_macro.* (tên khác Macro().world) | asean | — |
Insights().ranking.* | vnd | — |
Insights().sentiment.*, Insights().flow.* | asean | — |
Analytics().valuation(index).pe, .pb, .evaluation | vnd | — |
Retail().exchange_rate | vcb | — |
Cấp quyền và nguồn
Cấp Khách và Cộng đồng chỉ dùng được các nguồn kbs, vci, builtin, dukascopy, binance,
vcb. Gọi source="vnd", "mas", "asean", "cafef" ở hai cấp này thì nhận EntitlementError
mã VNSTOCK_TIER_SOURCE, và thư viện không tự đổi sang nguồn được phép. Cấp tài trợ dùng được mọi
nguồn. Danh sách này do chính sách từ vnstocks.com quy định và có thể thay đổi; vnstock policy
cho biết danh sách đang áp cho máy của bạn.
Tự viết dự phòng
Thư viện không tự chuyển nguồn. Muốn thử nguồn thứ hai khi nguồn đầu lỗi, viết vòng thử và chỉ bắt lỗi kết nối hay lỗi nguồn, không bắt lỗi cấp quyền hay lỗi tham số:
from vnstock import Market
from vnstock.core.exceptions import NetworkError, ProviderError
def ohlcv_with_fallback(symbol, start, end, sources=("vci", "kbs")):
last_error = None
for source in sources:
try:
return Market().equity(symbol).ohlcv(start=start, end=end, source=source)
except (NetworkError, ProviderError) as e:
last_error = e
raise last_error
df = ohlcv_with_fallback("FPT", "2026-09-01", "2026-09-30")
print(df.attrs["source"])Hai nguồn có thể cho số khác nhau ở giá điều chỉnh. Ghi lại df.attrs["source"] cùng kết quả để
biết số lấy từ đâu.