Thông tin tham chiếu

Reference() gom các bảng ít thay đổi: hồ sơ một công ty, danh sách mã trên thị trường, phân ngành ICB, danh mục chỉ số, thông tin hợp đồng tương lai, chứng quyền, trái phiếu và lịch sự kiện. Bạn thường gọi chúng một lần, lưu lại, rồi dùng làm gốc cho các bước phân tích khác.

Tóm tắt

Hai nhóm khác của Reference() có trang riêng:

• Reference().fund: danh mục quỹ mở, hồ sơ, biểu phí, tài liệu quỹ. Xem Dữ liệu quỹ mở.
• Reference().search: tìm mã quốc tế. Xem Tài sản quốc tế.

Dữ liệu mẫu trên trang chạy ngày 10/10/2026, cắt bớt cột cho gọn.

1. Khởi tạo

from vnstock import Reference

ref = Reference()

Mỗi nhánh mở bằng thuộc tính (ref.equity, ref.index…) hoặc gọi kèm mã (ref.company("FPT"), ref.index("VN30"), ref.futures("41I1GA000")). futures, warrant, bond, index dùng được cả hai cách: ref.futures.list() lấy danh sách, ref.futures("41I1GA000").info() lấy một hợp đồng.

Mọi bảng trả về là pandas.DataFrame. Nguồn thực tế của một kết quả nằm ở df.attrs["source"], tuyến dữ liệu ở df.attrs["route"].

2. Thông tin công ty — Reference().company(symbol)

fpt = ref.company("FPT")

Nguồn mặc định là vci, trừ ownership, capital_history, insider_trading mặc định kbs.

2.1 Hồ sơ công ty — info(), overview()

fpt.info(lang="vi", source=None)
fpt.overview(lang="vi", source=None)   # tên khác của info(), cùng kết quả

Một dòng. Cột khác nhau theo nguồn:

2.2 Ban lãnh đạo — officers()

fpt.officers(filter_by="working", source=None)

Cột: symbol, name, position, total_shares (số cổ phiếu nắm giữ), rate (tỷ lệ sở hữu, dạng phần, 0.0689 là 6,89%). Nguồn kbs ghi chức vụ viết tắt và để trống hai cột số.

2.3 Cổ đông — shareholders()

fpt.shareholders(mode="detailed", source=None)

mode="detailed" (mọi cấp). Cột: symbol, name, shareholder_type (Individual, Organization), total_shares, rate (dạng phần), date (ngày cập nhật).

mode="summary" với nguồn vci (cấp tài trợ): một dòng, cột symbol, total_shares, state_percentage, foreign_percentage, other_percentage, bod_percentage, institution_percentage (tỷ lệ dạng phần), state_volume, foreigner_volume, other_volume (số cổ phiếu).

mode="summary" với source="kbs" trả bảng cơ cấu sở hữu của ownership() (mục 2.4), mở mọi cấp. KBS không có bảng một dòng.

2.4 Cơ cấu sở hữu — ownership()

fpt.ownership(source=None)

Cột: symbol, owner_type, ownership_percentage (đơn vị phần trăm, 5.67 là 5,67%), shares_owned, update_date.

Chú ý đơn vị: ownership_percentage tính bằng phần trăm, còn rate ở officers() và shareholders() tính bằng phần.

2.5 Công ty con, công ty liên kết — subsidiaries(), affiliate()

fpt.subsidiaries(filter_by="all", source=None)
fpt.affiliate(source=None)

Cột: symbol, name, rate (tỷ lệ sở hữu, dạng phần), sub_symbol (mã của công ty được góp vốn). Với FPT: all 14 dòng, subsidiary 8 dòng, affiliate 5 dòng.

2.6 Lịch sử vốn điều lệ — capital_history()

fpt.capital_history(source=None)

Cột: symbol, date (chuỗi DD/MM/YYYY), charter_capital (đồng), currency. Mới nhất ở đầu.

2.7 Sự kiện của công ty — events()

fpt.events(lang="vi", source=None)

Tham số thừa mà bản cũ nhận (ví dụ page, limit) được bỏ qua, không báo lỗi.

Nguồn vci trả 22 cột, cả tiếng Việt lẫn tiếng Anh: id, symbol, event_code, event_name_vi, event_name_en, event_title_vi, event_title_en, category, action_type_vi, action_type_en, exercise_ratio, value_per_share, và các cột ngày display_date1, display_date2, public_date, record_date, exright_date, issue_date, start_date, end_date, listing_date, payout_date. Với FPT là 234 dòng.

2.8 Giao dịch của người nội bộ — insider_trading()

fpt.insider_trading(source=None)

Cột: id, symbol, person_name, position, transaction_type, registered_volume, traded_volume, start_date, end_date, status. Ngày chạy thử, FPT trả bảng rỗng có đủ cột. Giao dịch nội bộ của FPT vẫn xem được trong events() (mã sự kiện bắt đầu bằng DD).

3. Danh sách cổ phiếu — Reference().equity

3.1 Mọi mã — list()

ref.equity.list()

Không có tham số. Cột: symbol, org_name. Ngày chạy thử: 1.754 mã.

3.2 Theo sàn — list_by_exchange()

ref.equity.list_by_exchange(source=None)
ref.equity.by_exchange()   # tên khác

Chỉ giữ cổ phiếu (bỏ chứng quyền, trái phiếu, quỹ…), như bản 3.x. Cột: symbol, exchange (HOSE, HNX, UPCOM), organ_name, organ_short_name, icb_code_lv2.

3.3 Theo nhóm — list_by_group()

ref.equity.list_by_group(group, source=None)
ref.equity.by_group(group)   # tên khác

Một cột symbol. VN30 trả 30 mã. Hai nguồn có thể đếm khác nhau cho cùng một nhóm: ngày chạy thử, HOSE có 430 mã ở vci và 406 mã ở kbs.

vn30 = ref.equity.list_by_group("VN30")

3.4 Theo ngành ICB — list_by_industry()

ref.equity.list_by_industry(icb_code=None, lang="vi", source=None)

Mỗi mã một dòng cho mỗi cấp ngành. Cột: symbol, organ_name, com_type_code, icb_level (1 tới 4), icb_code, icb_name. Không lọc: 8.202 dòng. icb_code="8355": 29 dòng.

4. Phân ngành — Reference().industry

Phân ngành ICB lấy từ nguồn vci và mở mọi cấp.

4.1 Bảng ngành ICB — list()

ref.industry.list(lang="vi", source=None)

Cột: icb_code, icb_name, icb_level. 177 ngành.

Bản 3.x với lang="en" trả bảng không có cột tên; thế hệ 5 đặt tên tiếng Anh vào icb_name.

4.2 Mã theo ngành — sectors()

ref.industry.sectors(icb_code=None, lang="vi", source=None)

Cùng tham số và cùng bảng với equity.list_by_industry() (mục 3.4).

4.3 Phân ngành riêng của KBS và CafeF

Ngoài ICB, hai nguồn có cách phân ngành riêng. Chúng nằm ở lớp tương thích, chỉ dành cho cấp tài trợ, và không phải ICB: tên ngành giữ nguyên như nguồn đăng, mã ngành không so được với icb_code.

from vnstock.explorer.kbs import Listing as KBSListing
from vnstock.explorer.cafef import Listing as CafeFListing

KBSListing().industries()               # 25 ngành của KBS
KBSListing().symbols_by_industries()    # mã kèm ngành KBS, chỉ HOSE và HNX
CafeFListing().industries()             # ngành của CafeF
CafeFListing().symbols_by_industries()  # mã kèm ngành CafeF

Bảng ngành có cột classification ("kbs" hoặc "cafef"), industry_code, industry_name, industry_level, parent_code. Bảng mã theo ngành có symbol, organ_name, classification, industry_level, industry_code, industry_name. Reference().industry.list(source="kbs") không lấy được bảng này: hàm báo UnsupportedError vì chỉ vci phục vụ ICB. Xem thêm Lớp tương thích.

5. Chỉ số — Reference().index

5.1 Danh mục chỉ số — list()

ref.index.list(source=None)

Cột: symbol, name, description, full_name, group, index_id, sector_id. 29 chỉ số, thuộc các nhóm HOSE Indices, Sector Indices, Investment Indices, VNX Indices, HNX Indices, UPCOM Indices. Danh mục không có VNINDEX, HNXINDEX, UPCOMINDEX.

Lọc theo nhóm bằng IndexGroup, kiểu liệt kê có ở gốc gói. IndexGroup có bốn giá trị: HOSE, SECTOR, INVESTMENT, VNX; thuộc tính full_name trả đúng chuỗi ở cột group.

from vnstock import IndexGroup

indices = ref.index.list()
sector = indices[indices["group"] == IndexGroup.SECTOR.full_name]   # "Sector Indices", 10 chỉ số

IndexGroup kế thừa str, nên IndexGroup.HOSE truyền thẳng được vào chỗ nhận chuỗi, ví dụ ref.equity.list_by_group(IndexGroup.HOSE) giống list_by_group("HOSE").

5.2 Một chỉ số — index(symbol).info(), .description()

ref.index("VN30").info()          # một dòng, cùng cột với list()
ref.index("VN30").description()   # chuỗi: "30 cổ phiếu vốn hóa lớn nhất & thanh khoản tốt nhất HOSE"

Chỉ số không có trong danh mục (kể cả VNINDEX) thì info() trả bảng rỗng và description() trả None.

5.3 Nhóm mã — groups()

ref.index.groups()

Các nhóm dùng được cho list_by_group() và members(). Cột: group_name, group_code, category, description. 16 nhóm: BOND, CW, ETF, FU_INDEX, HNX, HNX30, HOSE, UPCOM, VN100, VN30, VNALL, VNMidCap, VNSI, VNSmallCap, VNX50, VNXALL.

5.4 Mã thành phần — members(), list_by_group()

ref.index.members(group=None, source=None, *, symbol=None)
ref.index.list_by_group(group="VN30", source=None)
ref.index.by_group(group="VN30")     # tên khác
ref.index("VN30").members(source=None)

Một cột symbol. VNINDEX, HNXINDEX, UPCOMINDEX được đọc là cả sàn HOSE, HNX, UPCOM (ngày chạy thử VNINDEX trả 406 mã). Thiếu mã nhóm ở members() thì báo TypeError.

ref.index.members("VN30")     # 30 mã: ACB, BID, BSR, ...

6. ETF, hợp đồng tương lai, chứng quyền, trái phiếu

6.1 Danh sách — mọi cấp

ref.etf.list(source=None)          # mặc định kbs; nhận kbs, vci
ref.futures.list(source=None)      # mặc định vci; nhận vci, kbs
ref.warrant.list(source=None)      # mặc định vci; nhận vci, kbs
ref.bond.list(bond_type="all")     # không có source

Ba hàm đầu trả một cột symbol. Số mã khác nhau theo nguồn: ngày chạy thử, ETF có 24 mã ở kbs và 21 mã ở vci; hợp đồng tương lai có 8 mã ở vci và 14 mã ở kbs; chứng quyền có 339 mã ở vci.

Mã hợp đồng tương lai trong danh sách có dạng mã KRX, ví dụ 41I1GA000, không phải dạng VN30F2611.

bond.list():

Với "all", bảng có hai cột symbol, type (corporate hoặc government). Ngày chạy thử: 97 mã doanh nghiệp, 6 mã chính phủ. Nếu phần chính phủ không lấy được, hàm vẫn trả phần doanh nghiệp kèm cảnh báo UserWarning; gọi bond.list("government") để xem lỗi đầy đủ. Phần doanh nghiệp lỗi thì cả lời gọi báo lỗi.

6.2 Một hợp đồng tương lai — futures(symbol).info() (Tài trợ)

ref.futures("41I1GA000").info()

Nguồn kbs, không có tham số source. Một dòng. Cột: symbol, full_name, underlying_symbol, exchange, first_trading_date, last_trading_date, reference_price, ceiling_price, floor_price, open_price, high_price, low_price, close_price (điểm chỉ số), open_interest, basis, foreign_buy_volume, foreign_sell_volume.

Mã hợp đồng nhận cả dạng viết tắt quen thuộc (VN30F1M, VN30F2M) lẫn mã định danh KRX 9 ký tự lấy từ ref.futures.list(). Thư viện tự động chuyển đổi mã sang chuẩn của nguồn kbs.

6.3 Một chứng quyền — warrant(symbol).info() (Tài trợ)

ref.warrant("CACB2515").info()

Nguồn kbs. Một dòng. Cột: symbol, issuer, underlying_symbol, exercise_price, exercise_ratio (chuỗi, ví dụ 1.7245:1), first_trading_date, last_trading_date (chuỗi DD/MM/YYYY), listed_share, exchange, warrant_type, underlying_price, reference_price, ceiling_price, floor_price, match_price (nghìn đồng), total_volume, foreign_room, foreign_buy_volume, foreign_sell_volume, break_even_point, break_even_point_diff, intrinsic_value.

6.4 Một trái phiếu — bond(symbol).info() (Tài trợ)

ref.bond("BAB124016").info()

Nguồn kbs. Một dòng, gồm biến động giá và chỉ số tài chính của tổ chức phát hành theo kỳ báo cáo gần nhất. Cột: symbol, change_1m, change_1y, current_ratio, debt_ratio, roe, roa, pe, pb, report_period.

Lấy mã từ ref.bond.list("corporate").

7. Lịch sự kiện — Reference().events

7.1 Sự kiện doanh nghiệp toàn thị trường — calendar()

ref.events.calendar(start=None, end=None, event_type=None, page=0, limit=20000)

Nguồn vci, không có tham số source. Cột: symbol, event_name, event_title, ex_right_date, record_date, payout_date, value (đồng mỗi cổ phiếu), ratio, organ_name, public_date, issue_date, event_type (mã sự kiện như DIV, ISS, AIS, DDIND, DDINS, EGME, AGME).

ref.events.calendar(start="2026-10-05", end="2026-10-09", event_type="dividend")

7.2 Lịch thị trường — market()

ref.events.market(start=None, end=None, event_type=None)

Nguồn builtin: bảng có sẵn trong thư viện, không gửi truy vấn. Cột: date, event_name, event_type, duration. Cả bảng có 355 dòng từ năm 2000; năm 2026 có 15 dòng.

8. Trạng thái phiên — Reference().market.status()

ref.market.status()

Thư viện 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, nên không gửi truy vấn và mọi cấp gọi được. source="mas" hỏi nguồn MAS, dành cho cấp tài trợ. Cột: exchange, asset_type, status, timestamp, last_trading_date.

9. Khác với bản 4.x và 3.x

Bảng chuyển đổi đầy đủ: Chuyển từ vnstock 4.x, Chuyển từ vnstock_data 3.x.

10. Đã ngừng

Các tên dưới đây vẫn còn để code cũ tìm thấy, nhưng gọi là báo UnsupportedError mã VNSTOCK_FEATURE_REMOVED.

company(s).trading_stats() và company(s).ratio_summary() còn tên trong thư viện nhưng chưa có dữ liệu ở bản này: gọi là báo UnsupportedError mã VNSTOCK_ROUTE_NOT_FROZEN. Thống kê giao dịch nằm ở Dữ liệu thị trường, chỉ số tài chính ở Dữ liệu cơ bản.

Lỗi và cách bắt: xem Xử lý lỗi. Nguồn mặc định của mọi hàm: xem Nguồn dữ liệu.