V3.0
Cập nhật lần cuối:
Thảo luậnMục lục
Hướng Dẫn Chuyển Đổi Sang Unified UI v3.0.0
Bản cập nhật v3.0.0 (11/03/2026) mang đến kiến trúc 7 Lớp & Unified UI. Tài liệu này hướng dẫn cách chuyển đổi code đang sử dụng các lớp API/Explorer cũ (vnstock_data.api, vnstock_data.explorer) sang Unified UI — giao diện hợp nhất thế hệ mới.
📌 1. Tổng Quan Những Thay Đổi Lớn
Cảnh báo
Breaking Changes: Các cách sử dụng cũ (truyền
source linh hoạt) vẫn tiếp tục được duy trì (Legacy), tuy nhiên các hàm định giá trong Market() sẽ bị gỡ bỏ trong tương lai. Unified UI là giao diện được khuyến nghị bắt buộc.
- Không cần chỉ định
source: Unified UI tự động chọn nguồn dữ liệu tối ưu nhất cho từng tính năng (KBS cho giá lịch sử, VCI cho thống kê phiên...). - Cú pháp chaining API: Mọi loại dữ liệu được phân chia vào 7 Domain chính:
Reference,Market,Fundamental,Analytics,Insights,Macro. - Tên method chuẩn hóa: Ví dụ,
history()→ohlcv(),intraday()→trades(),price_depth()→order_book().
🔄 2. Bảng Chuyển Đổi API (Mapping)
Lớp API cũ → Unified UI
Lớp cũ (vnstock_data.api) | Unified UI tương ứng (Bản >= 3.0.0) |
|---|---|
Quote(source, symbol) | Market().equity(symbol) / .index() / .etf() / .futures() / .warrant() |
Company(source, symbol) | Reference().company(symbol) |
Finance(source, symbol) | Fundamental().equity(symbol) |
Listing(source) | Reference().equity / .index / .fund / .bond |
Trading(source) | Market().equity(symbol) |
Market(source) | Analytics().valuation(index) |
TopStock(source) | Insights().ranking() |
Macro(source) | Macro().economy() / .currency() / .commodity() |
CommodityPrice(source) | Macro().commodity() |
📋 3. Chi Tiết Cập Nhật Kèm Code Mẫu
3.1 Giá lịch sử & Giao dịch (Quote → Market)
Nguyên tắc chuyển đổi:
- Khởi tạo
mkt = Market(). - Chọn đúng lớp tài sản (
equity,index,futures,etf). - Gọi hàm
ohlcv(),trades(). Các tên cũ nhưhistory()vẫn dùng được qua alias chuyển tiếp.
Cú pháp cũ:
Python
from vnstock_data.api import Quote
q = Quote(source="kbs", symbol="VIC")
df = q.history(start="2026-01-01", end="2026-03-01", interval="1D")Cú pháp mới:
Python
from vnstock_data import Market
mkt = Market()
df = mkt.equity("VIC").ohlcv(start="2026-01-01", end="2026-03-01")3.2 Thông tin công ty (Company → Reference)
Cú pháp cũ:
Python
from vnstock_data.api import Company
c = Company(source="vci", symbol="TCB")
df_profile = c.overview()Cú pháp mới:
Python
from vnstock_data import Reference
ref = Reference()
df_profile = ref.company("TCB").info()3.3 Báo cáo tài chính (Finance → Fundamental)
Cú pháp cũ:
Python
from vnstock_data.api import Finance
f = Finance(source="kbs", symbol="HPG")
income = f.income_statement(period="Y")Cú pháp mới:
Python
from vnstock_data import Fundamental
fun = Fundamental()
income = fun.equity("HPG").income_statement(period="Y")3.4 Định giá thị trường (Market → Analytics)
Cú pháp cũ:
Python
from vnstock_data.api import Market
m = Market(source="vnd")
pe = m.pe(duration="5Y")Cú pháp mới:
Python
from vnstock_data import Analytics
ana = Analytics()
pe = ana.valuation("VNINDEX").pe(duration="5Y")🚀 4. Lộ Trình Ngừng Hỗ Trợ (Deprecation Timeline)
Quan trọng
Lưu ý các mốc thời gian quan trọng nếu có API bị loại bỏ hoàn toàn trong các phiên bản sau. Trước khi ngừng hỗ trợ, hệ thống sẽ hiển thị cảnh báo song ngữ và tự động chuyển tiếp.
| Tính năng cũ | Thay thế bằng | Hạn cuối (Deadline) |
|---|---|---|
Macro().gdp(), Macro().cpi(), ... | Macro().economy().gdp(), ... | 31/8/2026 |
Macro().exchange_rate(), Macro().interest_rate() | Macro().currency().exchange_rate(), ... | 31/8/2026 |
Reference().derivatives() | Reference().futures() / .warrant() | 31/8/2026 |
Market().pe(), .pb(), .evaluation() | Analytics().valuation(index).pe(), ... | 31/8/2026 |
Thảo luận