Vnstock Logo

Kiến trúc thư viện

Cộng đồng

Mục lục

Trang này giúp bạn hiểu cách thư viện sắp xếp các hàm, trước khi đọc tài liệu của từng nhóm dữ liệu. Đọc xong, bạn biết nên gọi hàm theo lối nào, chọn nguồn ra sao, và đọc gì trong kết quả trả về.

Tóm tắt

Lối vàoImportDành choTài liệu
Giao diện hợp nhấtfrom vnstock import Market, Reference, ...Mã mới. Đây là lối gọi chính.Các trang Reference, Market, Fundamental…
Lớp kiểu cũfrom vnstock import Quote, Listing, ... hoặc from vnstock.api import ...Mã viết cho vnstock 4.x hoặc vnstock_data 3.xLớp kiểu cũ và mô-đun theo nguồn
Mô-đun theo nguồnfrom vnstock.explorer.vci import QuoteMã viết cho vnstock_data.explorerLớp kiểu cũ và mô-đun theo nguồn

Cả ba lối cùng đi qua một lõi xử lý. Lớp kiểu cũ và mô-đun theo nguồn chỉ đổi cách gọi và tên cột về như bản cũ, rồi chuyển lời gọi sang giao diện hợp nhất. Cấp tài khoản, nguồn và lỗi vì thế giống nhau ở cả ba lối.

Thư viện chạy ở đâu

vnstock là thư viện Python chạy trên máy của bạn: máy tính cá nhân, máy chủ hay notebook do bạn quản lý. Khi bạn gọi một hàm, truy vấn đi thẳng từ máy bạn tới nguồn bên thứ ba, không qua máy chủ trung chuyển nào của Vnstock. Lõi xử lý nhận phản hồi, kiểm tra và chuẩn hoá về một bộ cột cố định, rồi lớp Python đổi thành pandas.DataFrame.

Máy chủ vnstocks.com dùng để xác nhận khoá API, cấp tài khoản, hạn mức sử dụng của bạn và phát chính sách cấp quyền. Dữ liệu bạn truy xuất không đi qua đó.

Giao diện hợp nhất

Bảy lớp nằm ở gốc gói. Mỗi lớp là một nhóm dữ liệu:

LớpNhóm dữ liệuVí dụTài liệu
ReferenceDanh sách mã, thông tin công ty, ngành, chỉ số, lịch sự kiệnReference().equity.list()Tham chiếu
MarketGiá, khớp lệnh, bảng giá, sổ lệnh của cổ phiếu, chỉ số, ETF, phái sinh, quỹ, tài sản quốc tếMarket().equity("FPT").ohlcv()Thị trường
FundamentalBáo cáo tài chính, chỉ số tài chínhFundamental().equity("FPT").income_statement()Cơ bản
MacroKinh tế vĩ mô, tiền tệMacro().economy().gdp()Vĩ mô
InsightsXếp hạng, dòng tiền, tâm lý thị trườngInsights().ranking.gainer()Insights
AnalyticsĐịnh giá P/E, P/B của chỉ sốAnalytics().valuation("VNINDEX").pe()Analytics
RetailTỷ giá ngân hàngRetail().exchange_rate()Retail
Python
from vnstock import Market, Reference, Fundamental

Các lớp này được nạp lười: import vnstock chưa nạp Market hay Reference, chỉ nạp khi bạn dùng tới tên đó lần đầu. Lệnh import vì thế nhanh, và trình soạn thảo vẫn gợi ý tên, chữ ký và docstring như bình thường.

Cấu trúc một lời gọi

Lời gọi đọc từ trái sang phải theo ba bậc: lớp, nhóm tài sản (kèm mã nếu có), rồi hàm lấy dữ liệu.

Python
Market().equity("FPT").ohlcv(start="2026-10-01", end="2026-10-09")
#  lớp     nhóm(mã)     hàm(tham số)

Có ba dạng:

DạngVí dụKhi nào
Lớp().nhóm(mã).hàm()Market().equity("FPT").trades()Dữ liệu của một mã
Lớp().nhóm.hàm()Reference().equity.list()Dữ liệu của cả nhóm, không cần mã
Lớp().hàm()Market().quote(["FPT", "VCB"])Dữ liệu nhiều mã một lần

Tên hàm dùng chung một bộ từ cho mọi nhóm tài sản: ohlcv là nến giá, trades là khớp lệnh, quote là bảng giá, order_book là sổ lệnh. Tên cũ như history, intraday, price_board, price_depth vẫn gọi được và chạy đúng hàm tương ứng.

Chọn nguồn

Mỗi hàm có một nguồn mặc định. Hàm có tham số source thì bạn chọn được nguồn khác:

Python
from vnstock import Market

df = Market().equity("FPT").ohlcv(start="2026-10-01", end="2026-10-09")                # nguồn mặc định
df = Market().equity("FPT").ohlcv(start="2026-10-01", end="2026-10-09", source="kbs")  # chọn nguồn
  • source= viết hoa hay thường đều được.
  • Thư viện 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.
  • Nguồn hàm không có thì nhận UnsupportedError mã VNSTOCK_CAPABILITY_UNAVAILABLE, kèm các nguồn dùng được:
Text
Nguồn 'tcbs' không phục vụ market.equity.ohlcv. Nguồn dùng được: 'vci', 'asean', 'mas', 'kbs', 'vnd'.
  • Nguồn đã ngừng (fmarket, mbk, btmc…) thì nhận UnsupportedError mã VNSTOCK_FEATURE_REMOVED, kèm nguồn dùng thay nếu có.
  • Nguồn thực tế của một kết quả nằm ở df.attrs["source"].

Bảng nguồn mặc định và các giá trị source= của từng hàm ở trang Nguồn dữ liệu.

Cấp tài khoản đổi lượng dữ liệu, không đổi cách gọi

Khách (không khoá), Cộng đồng và các cấp tài trợ dùng cùng một thư viện, cùng tên hàm, cùng tham số. Cấp tài khoản chỉ quyết định ba điều:

  • Hàm nào chạy được. Gọi hàm ngoài cấp thì nhận EntitlementError mã VNSTOCK_TIER_ROUTE.
  • Nguồn nào dùng được. Khách và Cộng đồng dùng kbs, vci, builtin, dukascopy, binance, vcb. Gọi nguồn khác thì nhận EntitlementError mã VNSTOCK_TIER_SOURCE.
  • Lấy được bao nhiêu. Khách và Cộng đồng có trần số dòng, số kỳ báo cáo và độ dài lịch sử.

Ở hai trường hợp đầu, thư viện báo lỗi trước khi gửi truy vấn nào đi. Ở trường hợp thứ ba, bạn vẫn nhận bảng, chỉ ngắn hơn. Thư viện cảnh báo bằng UserWarning, mỗi loại cắt một lần trong một phiên chạy, nói cấp nào đã cắt và cắt bao nhiêu, và ghi con số vào df.attrs (xem bảng bên dưới). Mức cụ thể của từng cấp ở trang Cấp quyền và giới hạn.

Kết quả luôn là pandas.DataFrame

Hàm lấy dữ liệu của giao diện hợp nhất luôn trả pandas.DataFrame. Thư viện không in rồi trả None: khi không lấy được dữ liệu, bạn nhận ngoại lệ có mã lỗi (xem Xử lý lỗi).

Ví dụ, chạy ngày 10/10/2026:

Python
from vnstock import Market

df = Market().equity("FPT").ohlcv(start="2026-10-01", end="2026-10-09")
print(df.head(3))
Text
                       time  open  high   low  close   volume
0 2026-10-01 07:00:00+07:00  63.0  63.1  62.6   62.7  3434926
1 2026-10-02 07:00:00+07:00  62.7  63.2  62.1   62.1  3199600
2 2026-10-05 07:00:00+07:00  62.2  62.8  61.9   61.9  2513400

Kiểu cột được đặt sẵn, bạn không cần đổi:

Loại cộtKiểu pandasGhi chú
Thời điểmdatetime64[ns, Asia/Ho_Chi_Minh]Tài sản trong nước theo giờ Việt Nam. Tiền mã hoá, ngoại hối, hàng hoá, chỉ số thế giới theo UTC.
Ngàydatetime64[ns, Asia/Ho_Chi_Minh]0 giờ của ngày đó, cùng múi giờ với các cột thời điểm để so sánh được với nhau
Số thựcfloat64
Số nguyênint64, hoặc Int64 khi cột có ô trống
Nhóm lặp lại (sàn, loại…)category
Chữstring
Đúng/saiboolean

Lớp kiểu cũ có vài ngoại lệ để giữ hành vi bản cũ: Listing().symbols_by_group() trả pandas.Series, vnstock.api.Market đặt ngày làm chỉ mục, và mô-đun theo nguồn nhận to_df=False để trả chuỗi JSON. Chi tiết ở Lớp kiểu cũ và mô-đun theo nguồn.

df.attrs: kết quả này đến từ đâu

Mỗi bảng mang theo một từ điển df.attrs ghi lại cách nó được tạo ra. Lõi xử lý ghi phần này sau khi nhận xong phản hồi, nên mọi hàm ghi theo cùng một cách.

Python
print(df.attrs["source"], df.attrs["route"], df.attrs["length"])
# vci market.equity.ohlcv 7
KhoáÝ nghĩa
sourceNguồn đã dùng, ví dụ vci
routeTên thao tác, ví dụ market.equity.ohlcv. Đây cũng là tên bạn thấy trong thông báo lỗi và bảng cấp quyền.
symbol, start, end, intervalTham số của lời gọi, khi hàm có
lengthSố dòng trả về, sau khi đã áp trần của cấp
requested_atThời điểm truy vấn đầu tiên rời máy bạn, giờ UTC
latency_msThời gian từ lúc gửi tới lúc nhận xong, mili giây
request_countSố truy vấn đã gửi, tính cả lần thử lại
access_domain, access_protocol, access_methodTên miền đã liên hệ (chỉ tên miền gốc), giao thức, phương thức
source_name, organisationTên nguồn và tổ chức vận hành nguồn
terms_url, robots_txtĐường dẫn điều khoản và tóm tắt tệp robots.txt của nguồn, để bạn tự đối chiếu
tool, is_tool_only, disclaimerTên công cụ và tuyên bố miễn trừ ngắn
algorithm_role, algorithm_participationThư viện chỉ chuyển và chuẩn hoá dữ liệu (technical_connector), hay tính thêm từ dữ liệu gốc (derived_calculation, ở Analytics và Insights)
cap_tier, tier_cap_rows, tier_cap_history_days, tier_cap_periods, tier_cap_level, cap_rows_droppedChỉ có khi cấp tài khoản đã cắt kết quả: cấp nào, trần bao nhiêu, bỏ bao nhiêu dòng
request_cap_rows, request_cap_windowChỉ có khi một lần truy vấn tới nguồn chạm trần số nến, áp dụng cho mọi cấp

Khoá nào có còn tuỳ hàm. Bảng không đi qua mạng (dữ liệu có sẵn trong thư viện, hoặc bảng rỗng) không có requested_at.

df.attrs là tính năng của pandas: phép lọc, cắt dòng thường giữ nó, nhưng một số phép như merge hay concat có thể làm mất. Muốn giữ lại, đọc nó ngay sau lời gọi.

Trích dẫn nguồn gốc

Khi bài nghiên cứu cần ghi số liệu lấy từ đâu, dùng vnstock.cite() để có một dòng trích dẫn:

Python
import vnstock

print(vnstock.cite(df))
Text
market.equity.ohlcv via <tên miền của nguồn>, retrieved 2026-10-10T09:08:22.498000Z (vnstock, source=vci)

Dòng này gồm tên thao tác, tên miền gốc đã liên hệ, thời điểm truy xuất theo UTC và nguồn. Bảng không đi qua mạng thì nhận "No data origin was recorded for this result.", thư viện không đoán.

Muốn xem đủ, dùng vnstock.provenance.summary(df). Hàm trả một đoạn nhiều dòng tiếng Việt: công cụ, thời gian truy xuất, nguồn và tổ chức, thao tác, tên miền, vai trò của thư viện, tóm tắt robots.txt, đường dẫn điều khoản tham khảo, tuyên bố miễn trừ.

Python
from vnstock import provenance

print(provenance.summary(df))
record = provenance.read(df)   # cùng thông tin, dạng đối tượng
record.to_dict()               # dạng dict, tiện ghi vào phụ lục
Text
[Thông tin nguồn gốc dữ liệu - vnstock]
• Công cụ: vnstock (phần mềm chạy trên máy người dùng, chỉ đóng vai trò công cụ hỗ trợ)
• Thời gian truy xuất: 2026-10-10T09:08:22.498Z
• Nguồn kết nối: Vietcap (vci) — Công ty CP Chứng khoán Vietcap
• Thao tác: market.equity.ohlcv
...

Đường dẫn điều khoản và tóm tắt robots.txt chỉ để tham khảo; điều khoản của nguồn có thể đổi bất cứ lúc nào. Bạn tự đối chiếu và tuân thủ điều khoản của nguồn mình dùng.

Tự tra cứu hàm: show_api() và show_doc()

Bạn không cần mở trang web để xem một lớp có hàm gì.

Python
from vnstock import show_api, show_doc, Market, Reference, Analytics

show_api()                    # các lớp gốc
show_api(Market())            # cây hàm của Market, đi xuống cả các nhóm con
show_doc(Reference().equity)  # hàm của một nhóm, kèm chữ ký và dòng mô tả đầu
Text
EquityReference — 6 method(s)
  by_exchange      () -> 'pd.DataFrame'
      Tên khác của :meth:`list_by_exchange`, vẫn dùng được.
  by_group         (group: 'str') -> 'pd.DataFrame'
      Tên khác của :meth:`list_by_group`, vẫn dùng được.
  list             () -> 'pd.DataFrame'
      Lấy danh sách toàn bộ mã cổ phiếu.
  ...

show_api() không kèm đối số liệt kê sáu lớp Market, Fundamental, Reference, Analytics, Insights, Macro. Lớp Retail có một hàm, xem bằng show_doc(Retail()). Mọi hàm công khai đều có docstring hai thứ tiếng, nên help(Market().equity("FPT").ohlcv) cũng đọc được trong notebook.

Ngôn ngữ thông báo

Cảnh báo, thông báo lỗi và đầu ra dòng lệnh hiện cả tiếng Việt lẫn tiếng Anh (tiếng Việt trước) khi bạn chưa chọn. Đổi lâu dài bằng dòng lệnh:

Shell
vnstock settings language          # xem đang dùng gì
vnstock settings language vi       # chỉ tiếng Việt
vnstock settings language en       # chỉ tiếng Anh
vnstock settings language default  # trở lại song ngữ

Chỉ đổi cho một lần chạy thì đặt biến môi trường VNSTOCK_LANG=vi (hoặc en, both). Ngôn ngữ chỉ đổi chữ hiển thị. Tên cột, mã lỗi và dữ liệu giữ nguyên. Xem thêm ở Đăng nhập và dòng lệnh.

Khi nguồn từ chối truy cập

Lõi xử lý tự lo việc thử lại khi cần. Khi nguồn từ chối hẳn (giới hạn tốc độ, chặn truy cập, đòi xác minh), lời gọi dừng ngay và báo lỗi có mã, không âm thầm đổi nguồn. Các lỗi hay gặp bắt được thẳng từ gốc gói:

Python
from vnstock import Market, RateLimitedError, DataSourceBlockedError, ChallengeRequiredError

try:
    df = Market().equity("FPT").trades()
except RateLimitedError:
    ...  # chờ một lúc rồi gọi lại, hoặc giảm tần suất

Bản vnstock_data từng có bộ ngắt mạch: sau nhiều lần bị từ chối, thư viện tạm ngừng gọi một máy chủ trong một khoảng thời gian. Thế hệ 5 không giữ trạng thái đó, vì mỗi lời gọi bị từ chối đã dừng ngay. Hai hàm cũ vẫn gọi được để mã cũ không lỗi:

Python
import vnstock

vnstock.circuit_status()  # {}  luôn rỗng: không có máy chủ nào đang bị tạm ngừng
vnstock.reset_circuit()   # 0   luôn bằng 0: không có gì để xoá

CircuitOpenError vẫn có ở gốc gói để câu except cũ không lỗi khi import. Danh sách đủ các lỗi và cách xử lý ở Xử lý lỗi.

Lớp kiểu cũ và mô-đun theo nguồn

Mã viết cho bản cũ chạy tiếp mà không phải viết lại:

Python
# vnstock 4.x, vnstock_data 3.x
from vnstock import Quote

df = Quote(symbol="FPT", source="vci").history(start="2026-10-01", end="2026-10-09")

# vnstock_data.explorer
from vnstock.explorer.vci import Quote

df = Quote("FPT").history(start="2026-10-01", end="2026-10-09")

Hai lời gọi trên trả đúng bảng của Market().equity("FPT").ohlcv(..., source="vci"). Lớp kiểu cũ ở gốc gói gồm Quote, Listing, Company, Finance, Trading, TopStock, Fund; vnstock.api có thêm Market và Macro kiểu cũ. Mô-đun theo nguồn còn vci, kbs, mas, asean, cafef, misc, msn. Import vnstock.explorer báo DeprecationWarning; một số tên có ngày ngừng. Tra cứu đủ từng lớp, từng hàm ở Lớp kiểu cũ và mô-đun theo nguồn.

Mã mới nên gọi thẳng giao diện hợp nhất: tên hàm thống nhất, cột chuẩn hoá, và không có ngày ngừng.

Tags

vnstock
thế hệ 5