Tra cứu danh mục mã chứng khoán Việt Nam bằng Python

Trước khi hỏi giá của một mã, người ta hỏi có những mã nào. Ba phương thức trong client.meta trả lời đúng ba câu hỏi mở đầu đó, và tất cả đều trả về pandas.DataFrame.

Đây là danh mục, không phải số liệu: không cột nào ở đây mang đơn vị, trừ exercise_price của chứng quyền.

import finlens

client = finlens.client()

tickers = client.meta.symbols(exchange="HOSE")["symbol"].tolist()
df = client.eod.stock.ohlcv(tickers[:50], start="2026-01-01")

df["symbol"].tolist() là cầu nối giữa trang này và mọi trang còn lại: lấy danh sách mã ở đây rồi đưa thẳng sang client.eod, client.intraday hay client.financials.

client.meta.symbols(exchange="HOSE")     # đúng
client.meta.symbols("HOSE")              # TypeError

symbols() — danh mục mã và chứng chỉ quỹ

client.meta.symbols(
    *,
    exchange=None,
    icb=None,
    kind=None,
    company_type=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Bốn bộ lọc cộng dồn với nhau: khai cả exchange lẫn icb là hỏi giao của hai điều kiện, không phải hợp.

exchange là tên sàn giao dịch, không phải tên chỉ số. "VNINDEX" là mã chỉ số của HOSE và nó nhận một lỗi 400 ở đây chứ không phải một bảng rỗng — kiểu ExchangeArg biến lỗi đó thành một gạch đỏ ngay trong IDE.

Cột trả về

Mười cột luôn có mặt đúng dtype kể cả khi bộ lọc không khớp dòng nào, nên bạn không cần bọc if not df.empty quanh lời gọi. Frame sắp tăng dần theo symbol.

Mỗi dòng mang sẵn cả hai cấp ngành

icb_level4 là cấp được gán trực tiếp trong dữ liệu; icb_level2 đã được máy chủ suy ra qua chuỗi cha và đặt sẵn trên mỗi dòng. Nhờ vậy bạn gộp theo ngành lớn bằng một phép groupby, không phải gọi thêm sectors() rồi tự nối cây:

df = client.meta.symbols()

df.groupby("icb_name2")["symbol"].count().sort_values(ascending=False)

Và vì bộ lọc icb nhận cả hai cấp, bạn hỏi được ngành lớn mà không cần biết nó gồm những ngành con nào:

ngan_hang = client.meta.symbols(icb="8300")     # mã cấp 2 — cả ngành ngân hàng
chi_tiet  = client.meta.symbols(icb="8355")     # mã cấp 4

Máy chủ tra cấp giúp bạn, nên không có tham số icb_level ở phương thức này để phải nhớ. Mã thuộc cấp 1 hoặc cấp 3 nhận 400 kèm giải thích, chứ không phải một bảng rỗng. Không nhớ mã thì tra bằng client.meta.sectors() ở mục dưới.

quy = client.meta.symbols(kind="fund")          # đúng
quy = client.meta.symbols(company_type="QU")    # sai

# Ngân hàng trên HOSE, kèm tên gọi tắt
nh = client.meta.symbols(exchange="HOSE", company_type="NH")
nh[["symbol", "short_name", "icb_name4"]]

# Mọi mã chứng khoán (không gồm chứng chỉ quỹ) trên UPCOM
upcom = client.meta.symbols(exchange="UPCOM", kind="stock")

sectors() — cây ngành ICB

client.meta.sectors(
    *,
    level=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Nguồn duy nhất của mã ngành cho mọi tham số icb trong thư viện — kể cả client.eod.sector.ohlcv() và client.eod.sector.investor.flow(). Một bảng ngành chép tay sẽ đúng lúc bạn chép và sai vào một lúc nào đó bạn không biết; lời gọi này thì không.

Frame sắp tăng dần theo level rồi icb, nên một lời gọi mang cả hai cấp đọc ra được là một cái cây chứ không phải một danh sách phẳng trộn lẫn.

Không có cột tên tiếng Anh. name_vi là tên duy nhất, và đó là trạng thái vĩnh viễn chứ không phải một khoảng trống tạm thời — phát một cột toàn null để bạn tự đoán thì tệ hơn không phát.

nganh = client.meta.sectors(level=2)
len(nganh)
# 19

# Dựng lại cây bằng chính bảng này
ca_cay = client.meta.sectors()
con_cua = ca_cay.groupby("parent_icb")["icb"].apply(list)

Chỉ hai cấp được phục vụ. Cấp 1 và cấp 3 có tồn tại trong chuẩn ICB nhưng không cấp nào trong hai cấp đó có dữ liệu tổng hợp, nên chúng nhận 400 chứ không trả một bảng rỗng — và kiểu IcbLevelArg chặn chúng ngay lúc gõ code.

cap4 = ca_cay[ca_cay["level"] == 4]
cap2 = ca_cay[ca_cay["level"] == 2]

cap4.merge(cap2, left_on="parent_icb", right_on="icb")     # sai — ghép hụt

warrants() — danh mục chứng quyền có bảo đảm

client.meta.warrants(
    *,
    underlying=None,
    active_only=True,
    refresh=False,
    on_error="warn",
) -> DataFrame

Chứng quyền nào đang niêm yết trên mã cơ sở nào, kèm điều khoản hợp đồng.

underlying là mã của cổ phiếu cơ sở, không phải mã của chứng quyền. Mã chứng quyền (CHPG2525) nằm ở cột symbol của kết quả.

cq = client.meta.warrants(underlying="HPG")
cq.attrs["finlens"]["units"]["exercise_price"]
# 'VND'

active_only=True giữ lại những mã có ngày đáo hạn từ hôm nay trở đi theo giờ Việt Nam — chứng quyền đáo hạn đúng hôm nay vẫn còn trong bảng. maturity_date là tín hiệu duy nhất cho biết một chứng quyền còn hạn, nên đừng tìm một cột trạng thái nào khác.

# Chứng quyền còn hạn trên HPG
cq = client.meta.warrants(underlying="HPG")
cq[["symbol", "issuer", "exercise_price", "maturity_date"]]

# Tra một mã đã hết hạn gặp trong dữ liệu lịch sử
cu = client.meta.warrants(active_only=False)
df = client.eod.warrant.ohlcv(cu["symbol"].tolist()[:5])

Lời gọi này chỉ trả danh mục. Giá và khối lượng giao dịch của chính chứng quyền nằm ở client.eod.warrant.ohlcv() — xem Dữ liệu cuối ngày.

Độ phủ — và cách tự đếm lại

Danh mục hiện có hơn 1.600 mã trên cả ba sàn: UPCOM đông nhất, rồi tới HOSE, rồi HNX. Cây ngành có 19 ngành cấp 2 và khoảng một trăm ngành cấp 4.

Những con số này đổi theo từng đợt niêm yết mới, nên đừng chép chúng vào code — đếm lại bằng chính thư viện:

df = client.meta.symbols()

len(df)                                  # tổng số mã
df["exchange"].value_counts()            # phân bố theo sàn
df["kind"].value_counts()                # cổ phiếu và chứng chỉ quỹ
len(client.meta.sectors(level=4))        # số ngành chi tiết
len(client.meta.warrants())              # chứng quyền còn hạn

df.attrs["finlens"]["truncated"]     # True nghĩa là bảng chưa đầy đủ
client.limits()["max_rows"]          # hạn mức hiệu lực của khoá bạn đang dùng

Cache 24 giờ

Kết quả của cả ba phương thức được cache 24 giờ — danh mục đổi theo tháng chứ không theo phiên. Dùng refresh=True khi bạn biết vừa có mã mới niêm yết:

df = client.meta.symbols(refresh=True)

Bản async

Cả ba phương thức đều có bản bất đồng bộ với cùng chữ ký:

import asyncio
import finlens

async def main():
    async with finlens.AsyncClient() as client:
        df = await client.meta.symbols(exchange="HOSE")
        tickers = df["symbol"].tolist()

asyncio.run(main())

Xem tiếp