Thống kê và xếp hạng thị trường (Insights)
Mục lục
Mọi hàm trên trang này chạy với khoá API từ cấp tài trợ Bronze trở lên. Khoá cấp Cộng đồng hoặc chạy không khoá nhận EntitlementError (mã VNSTOCK_TIER_ROUTE hoặc VNSTOCK_TIER_SOURCE), và thư viện không gửi truy vấn nào đi.
Lớp Insights() giúp bạn tự truy xuất các bảng số liệu tổng hợp của thị trường cổ phiếu Việt Nam:
xếp hạng top mã, độ rộng thị trường, mã tác động mạnh lên chỉ số, bản đồ nhiệt, dòng tiền theo nhóm
nhà đầu tư. Mỗi bảng là con số đo được từ dữ liệu giao dịch, dùng để tham khảo; đó không phải lời
khuyên đầu tư.
Hàm chia thành ba nhóm, cả ba là thuộc tính (không ngoặc):
Insights().ranking: bảy bảng xếp hạng top mã.Insights().sentiment: độ rộng, mức tác động lên chỉ số, bản đồ nhiệt.Insights().flow: dòng tiền khối ngoại, tự doanh, mua bán chủ động theo từng mã.
Các hàm không có tham số source. Nguồn cố định theo nhóm: ranking lấy từ vnd, sentiment và
flow lấy từ asean. Đọc nguồn của kết quả ở df.attrs["source"].
Tóm tắt
| Hàm | Làm gì | Cấp |
|---|---|---|
ranking.gainer() | Top mã tăng giá mạnh nhất trong phiên, theo % | Tài trợ |
ranking.loser() | Top mã giảm giá mạnh nhất trong phiên, theo % | Tài trợ |
ranking.value() | Top mã có giá trị giao dịch lớn nhất | Tài trợ |
ranking.volume() | Top mã có khối lượng tăng đột biến so với trung bình 20 phiên | Tài trợ |
ranking.deal() | Top mã có khối lượng khớp lệnh tăng đột biến so với trung bình 20 phiên | Tài trợ |
ranking.foreign_buy() | Top mã khối ngoại mua ròng nhiều nhất trong ngày | Tài trợ |
ranking.foreign_sell() | Top mã khối ngoại bán ròng nhiều nhất trong ngày | Tài trợ |
sentiment.breadth() | Chuỗi P/E, P/B và tỷ lệ mã trên MA20, MA50 của một sàn | Tài trợ |
sentiment.contribution() | 20 mã tác động mạnh nhất lên chỉ số | Tài trợ |
sentiment.heatmap() | Bản đồ nhiệt: giá, vốn hoá, giao dịch từng mã | Tài trợ |
flow.foreign() | Mua bán ròng của khối ngoại theo từng mã | Tài trợ |
flow.proprietary() | Mua bán ròng của tự doanh theo từng mã | Tài trợ |
flow.active() | Chênh lệch mua chủ động và bán chủ động theo từng mã | Tài trợ |
1. Khởi tạo
from vnstock import Insights
ins = Insights()2. Xếp hạng — Insights().ranking
Năm bảng gainer, loser, value, volume, deal cùng chữ ký:
ins.ranking.gainer(index="VNINDEX", limit=10)| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
index | str | "VNINDEX" | Chỉ số có các mã được xếp hạng, ví dụ "VNINDEX", "VN30", "HNX" |
limit | int | 10 | Số mã trả về |
Bảng xếp hạng phản ánh phiên giao dịch gần nhất. Gọi vào ngày nghỉ thì nhận số liệu của phiên trước
đó (cột last_updated cho biết mốc).
df = ins.ranking.gainer(limit=5)
df = ins.ranking.value("HNX", limit=5)
df = ins.ranking.gainer("VN30", limit=5)Cột chung của năm bảng:
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
symbol | chuỗi | Mã cổ phiếu |
exchange | chuỗi | Sàn: HOSE, HNX, UPCOM |
last_price | số | Giá gần nhất, nghìn đồng |
last_updated | ngày giờ | Mốc cập nhật, múi giờ Asia/Ho_Chi_Minh |
price_change_1d | số | Thay đổi giá so với phiên trước, nghìn đồng |
price_change_percent_1d | số | Thay đổi giá so với phiên trước, % |
total_value | số | Giá trị giao dịch trong phiên, đồng |
Cột thêm theo bảng:
| Bảng | Cột thêm | Ý nghĩa | Thứ tự xếp |
|---|---|---|---|
gainer() | avg_volume_20d, volume_spike_20d_percent | Khối lượng trung bình 20 phiên; khối lượng phiên so với mức đó, % | price_change_percent_1d giảm dần |
loser() | — | price_change_percent_1d tăng dần | |
value() | — | total_value giảm dần | |
volume() | avg_volume_20d, volume_spike_20d_percent | Như gainer() | volume_spike_20d_percent giảm dần |
deal() | deal_volume_spike_20d_percent | Khối lượng khớp lệnh so với trung bình 20 phiên, % | deal_volume_spike_20d_percent giảm dần |
volume() xếp theo mức tăng đột biến của khối lượng, không theo khối lượng tuyệt đối. Muốn mã
có khối lượng lớn nhất, gọi value() hoặc tự sắp xếp kết quả của sentiment.heatmap() theo
volume_1d.
Dữ liệu mẫu gainer(limit=3) (chạy ngày 10/10/2026, số liệu phiên 09/10/2026):
symbol exchange last_price price_change_1d price_change_percent_1d total_value volume_spike_20d_percent
0 NNC HOSE 41.70 2.70 6.923077 1.344425e+09 143.184539
1 PNJ HOSE 19.50 1.25 6.849315 1.392188e+11 60.279622
2 IDI HOSE 5.16 0.33 6.832298 8.892836e+09 650.223497
Dữ liệu mẫu value(limit=3) (cùng ngày chạy):
symbol exchange last_price price_change_1d price_change_percent_1d total_value
0 SHB HOSE 10.00 -0.050 -0.497512 1.260330e+12
1 NVL HOSE 10.95 0.700 6.829268 7.825061e+11
2 HDB HOSE 22.40 0.862 4.002229 7.703744e+11
Khối ngoại mua ròng, bán ròng — foreign_buy(), foreign_sell()
ins.ranking.foreign_buy(date=None, limit=10)
ins.ranking.foreign_sell(date=None, limit=10)| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
date | str | None | Ngày giao dịch, "YYYY-MM-DD". Để trống thì lấy hôm nay |
limit | int | 10 | Số mã trả về |
Hai hàm này không có tham số index. Để trống date vào ngày nghỉ thì nhận bảng rỗng; truyền ngày
giao dịch gần nhất.
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
symbol | chuỗi | Mã cổ phiếu |
date | ngày | Ngày giao dịch |
net_value | số | Giá trị mua ròng của khối ngoại, đồng. Số âm là bán ròng |
Dữ liệu mẫu foreign_buy(date="2026-10-09", limit=3) (chạy ngày 10/10/2026):
symbol date net_value
0 VHM 2026-10-09 00:00:00+07:00 1.616632e+11
1 SHB 2026-10-09 00:00:00+07:00 1.227550e+11
2 NVL 2026-10-09 00:00:00+07:00 7.790718e+10
TopStock ở gốc gói vnstock là lớp kiểu cũ của bảy bảng này, trả cột theo kiểu cũ và chạy đến
hết 31/12/2026. Xem Lớp tương thích.
3. Độ rộng và tâm lý — Insights().sentiment
Ba hàm cùng một tham số:
| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
exchange | str | "HOSE" | Sàn: "HOSE", "HNX", "UPCOM" |
Không có tham số khoảng thời gian.
3.1. Độ rộng thị trường — breadth()
ins.sentiment.breadth(exchange="HOSE")Trả một chuỗi theo ngày, khoảng ba năm gần nhất (lần chạy 10/10/2026 nhận 744 dòng cho HOSE, từ 10/10/2023).
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
exchange | chuỗi | Sàn |
time | ngày | Ngày giao dịch |
pe, pb | số | P/E, P/B của cả sàn |
close_price | số | Điểm đóng cửa của chỉ số sàn |
above_ma20_percent | số | Tỷ lệ mã có giá trên đường trung bình 20 phiên, từ 0 đến 1 |
above_ma50_percent | số | Tỷ lệ mã có giá trên đường trung bình 50 phiên, từ 0 đến 1 |
avg_20d_above_ma20_percent, avg_20d_above_ma50_percent | số | Trung bình 20 phiên của hai tỷ lệ trên |
position_line | số | Đường vị thế do nguồn tính kèm, cùng thang 0 đến 1 |
Dữ liệu mẫu (chạy ngày 10/10/2026, hai dòng cuối):
exchange time pe pb close_price above_ma20_percent above_ma50_percent position_line
742 HOSE 2026-10-08 00:00:00+07:00 12.24193 1.84486 1738.97 0.32938 0.29524 0.31962
743 HOSE 2026-10-09 00:00:00+07:00 12.16604 1.83343 1735.09 0.31991 0.29048 0.31149
3.2. Mã tác động lên chỉ số — contribution()
ins.sentiment.contribution(exchange="HOSE")Trả 20 dòng: 10 mã kéo chỉ số lên mạnh nhất (type="up"), rồi 10 mã kéo xuống mạnh nhất
(type="down").
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
symbol | chuỗi | Mã cổ phiếu |
point | số | Số điểm chỉ số mã này đóng góp. Âm ở nhóm down |
value | số | Mức đóng góp tương đối do nguồn tính kèm, cùng dấu với point |
type | chuỗi | up hoặc down |
time | ngày | Ngày giao dịch |
Dữ liệu mẫu (chạy ngày 10/10/2026):
symbol value point type time
0 HDB 0.05056 0.87922 up 2026-10-09 00:00:00+07:00
1 VPB 0.04160 0.72341 up 2026-10-09 00:00:00+07:00
10 BCM -0.01046 -0.18190 down 2026-10-09 00:00:00+07:00
3.3. Bản đồ nhiệt — heatmap()
ins.sentiment.heatmap(exchange="HOSE")Mỗi mã trên sàn một dòng, gồm cả chứng quyền (lần chạy 10/10/2026 nhận 769 dòng cho HOSE).
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
symbol | chuỗi | Mã |
icb_code | chuỗi | Mã ngành ICB cấp 3. Để trống với chứng quyền |
market_cap | số | Vốn hoá, tỷ đồng. Bằng 0 với chứng quyền |
close | số | Giá gần nhất, nghìn đồng |
price_change | số | Thay đổi giá so với phiên trước, nghìn đồng |
price_change_status | chuỗi | U tăng, D giảm, N đứng giá, C tăng trần, F giảm sàn |
volume_1d, value_1d | số | Khối lượng (cổ phiếu) và giá trị (đồng) giao dịch trong phiên |
volume_10d, value_10d | số | Tổng 10 phiên |
volume_1m, value_1m | số | Tổng một tháng. Lần chạy 10/10/2026, hai cột này trống ở mọi dòng |
Dữ liệu mẫu (chạy ngày 10/10/2026, lọc ba mã):
symbol icb_code market_cap close price_change price_change_status value_1d volume_1d
68 FPT 9530 109183.63082 57.9 -1.80 D 6.324469e+11 10851700.0
319 HPG 2720 169703.58685 20.1 -0.05 D 3.168289e+11 15779800.0
452 VCB 8350 473766.77783 56.7 0.10 U 1.723582e+11 3049500.0
4. Dòng tiền — Insights().flow
ins.flow.foreign(exchange="HOSE", group_by="stock")
ins.flow.proprietary(exchange="HOSE", group_by="stock")
ins.flow.active(exchange="HOSE", group_by="stock")| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
exchange | str | "HOSE" | Sàn: "HOSE", "HNX", "UPCOM" |
group_by | str | "stock" | Chỉ nhận "stock" (theo từng mã). Gộp theo ngành hay theo nhóm vốn hoá chưa hỗ trợ, nhận UnsupportedError mã VNSTOCK_ROUTE_NOT_MIGRATED |
Mỗi mã trên sàn một dòng, gồm cả chứng quyền.
| Hàm | Đo gì |
|---|---|
foreign() | Khối ngoại mua trừ bán |
proprietary() | Tự doanh công ty chứng khoán mua trừ bán |
active() | Mua chủ động trừ bán chủ động |
Ba bảng cùng bộ cột. Giá trị lớn hơn 0 là mua ròng, nhỏ hơn 0 là bán ròng:
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
symbol | chuỗi | Mã |
volume_1d, value_1d | số | Ròng trong phiên: khối lượng (cổ phiếu), giá trị (đồng) |
volume_10d, value_10d | số | Ròng cộng dồn 10 phiên |
volume_1m, value_1m, volume_3m, value_3m, volume_6m, value_6m | số | Ròng cộng dồn 1, 3, 6 tháng. Lần chạy 10/10/2026, các cột này trống ở mọi dòng |
status | chuỗi | Chỉ có ở active(). Lần chạy 10/10/2026, cột này trống ở mọi dòng |
Dữ liệu mẫu foreign() (chạy ngày 10/10/2026, lọc ba mã):
symbol volume_1d value_1d value_10d
68 FPT -2084518.0 -1.206743e+11 -2.834321e+11
319 HPG -1529275.0 -3.118097e+10 -5.344081e+10
452 VCB -369100.0 -2.099702e+10 -1.763939e+11
Dữ liệu mẫu proprietary() (cùng ngày chạy, cùng ba mã):
symbol volume_1d value_1d value_10d
68 FPT 174900.0 1.143451e+10 2.617647e+11
319 HPG -2780450.0 -5.641902e+10 -2.531500e+09
452 VCB -111201.0 -6.302143e+09 -2.341303e+09
5. Chưa hỗ trợ
Hai nhóm dưới đây có trong lớp để mã viết cho bản 3.x không gặp AttributeError, nhưng chưa có dữ
liệu. Gọi bất kỳ hàm nào của chúng nhận UnsupportedError mã VNSTOCK_ROUTE_NOT_MIGRATED:
| Nhóm | Hàm |
|---|---|
Insights().sector(ind_code) | members(), flow(), flow_intraday(), index_intraday(), valuation(), rrg() |
Insights().equity(symbol) | order_flow(), order_flow_history(), peer_compare(), rrg() |
UnsupportedError: Phiên bản này chưa hỗ trợ phương thức này
Hai nhóm của bản 3.x không còn trên Insights(), gọi sẽ nhận AttributeError:
Insights().screener(bộ lọc cổ phiếu): chưa có ở thế hệ 5.Insights().valuation(P/E, P/B toàn thị trường): đã chuyển sangAnalytics().valuation(index), trang Analytics.
Bắt lỗi theo mã, xem Xử lý lỗi:
from vnstock import Insights
from vnstock.core.exceptions import UnsupportedError
try:
df = Insights().flow.foreign(group_by="industry")
except UnsupportedError as e:
print(e.code) # VNSTOCK_ROUTE_NOT_MIGRATED