Vnstock Logo

Kiến trúc thư viện

Cập nhật lần cuối:

Thảo luận

Giới thiệu

Thư viện `vnstock_data` được thiết kế với cấu trúc hướng mô-đun, dễ mở rộng, dễ tích hợp, và dễ chuyển đổi nguồn dữ liệu chỉ qua một tham số cấu hình. Đây là bộ công cụ dữ liệu chứng khoán - kinh tế - tài sản toàn diện, sẵn sàng hỗ trợ bạn xây dựng mọi sản phẩm từ phân tích, giao dịch, đến dự báo thị trường.

Kiến trúc hệ thống

Triết Lý Thiết Kế

Đặc điểmÝ nghĩa
Adapter PatternMột chuẩn giao tiếp duy nhất, dễ dàng thay đổi nhà cung cấp dữ liệu thông qua các hàm hoạt động như adapter trung gian.
Phân lớp rõ ràngMỗi lớp đại diện cho một nhóm dữ liệu chuyên biệt: Quote, Trading, Finance, v.v.
Tương lai mở rộngThêm nguồn mới không làm phá vỡ cấu trúc của thư viện trong tương lai.
Tối ưu hiệu suất & bảo trìQuản lý dễ dàng các thay đổi nguồn cấp, cập nhật tính năng mới linh hoạt.

Hướng Dẫn Sử Dụng

Gợi ý

`vnstock_data` hỗ trợ **2 cách tiếp cận** khi gọi dữ liệu, phù hợp cho cả nhu cầu linh hoạt lẫn nhu cầu ổn định.

Gọi hàm qua Adapter chung

Tối ưu cho sự linh hoạt và khả năng hoán đổi nguồn dữ liệu.

Bạn khởi tạo lớp với tham số source, và sử dụng hàm tương ứng.
Điều này cho phép dễ dàng chuyển đổi giữa các nguồn mà không cần sửa đổi code nhiều.

from vnstock_data import Quote, Trading, Finance, Listing, Company, CommodityPrice, Macro

quote = Quote(source="vci", symbol="VCI")
df = quote.history(start="2024-02-01", end="2025-04-18", interval="1D")
df.head()

Ưu điểm:

  • Linh hoạt thay đổi source theo nhu cầu (ví dụ: VCI ➔ VND ➔ MAS...).
  • Một chuẩn code chung áp dụng cho nhiều nhà cung cấp.

⚠️ Lưu ý:

  • Không phải nguồn nào cũng hỗ trợ đầy đủ tất cả các phương thức.
  • Nếu nguồn không hỗ trợ hàm gọi, sẽ có thông báo lỗi (NotImplementedError).

📌 Tham khảo: Sơ đồ kiến trúc & bảng tra cứu nguồn dữ liệu để biết nguồn nào hỗ trợ hàm nào.

Gọi hàm qua Module Nguồn Dữ Liệu

Tối ưu cho sự ổn định và kiểm soát chặt chẽ.

Bạn import trực tiếp từ module nội bộ của nhà cung cấp (ví dụ explorer.vci, explorer.mas,...).

from vnstock_data.explorer.vci import Quote, Trading, Finance, Listing, Company

quote = Quote(symbol="VCI")
df = quote.history(start="2024-02-01", end="2025-04-18", interval="1D")
df.head()

Ưu điểm:

  • Tránh lỗi "không hỗ trợ" vì đã cố định nguồn.
  • Phù hợp khi bạn biết chắc mình chỉ làm việc với một nhà cung cấp nhất định.

Khuyến nghị:

  • Dùng cách này trong các hệ thống production cần sự ổn định cao.
  • Hoặc khi cần tận dụng các tính năng riêng biệt của từng nguồn.

Tra cứu các loại dữ liệu & nguồn cấp

Mỗi lớp (Adapter) được thiết kế để phục vụ cho các nghiệp vụ cụ thể.
Dưới đây là bảng tổng hợp toàn bộ phương thức theo từng lớp và nhà cung cấp hỗ trợ:

Phương Thức Của Lớp Listing

Tra cứu mã chứng khoán, phân ngành, chỉ số, trái phiếu, chứng quyền.

Phương thứcVCIVNDMô tả
all_symbolsDanh sách chứng khoán niêm yết
industryPhân ngành
symbols_by_industriesMã chứng khoán theo phân ngành ICB
symbols_by_exchangeMã chứng khoán theo sàn giao dịch
industries_icbDanh sách phân ngành ICB
symbols_by_groupMã chứng khoán theo nhóm, ví dụ VN30, VN100, vv
all_future_indicesTất cả mã chỉ số hợp đồng tương lai
all_government_bondsTất cả mã trái phiếu chính phủ
all_covered_warrantTất cả mã chứng quyền
all_bondsTất cả mã trái phiếu doanh nghiệp

Phương Thức Của Lớp Company

Khai thác thông tin chi tiết về từng doanh nghiệp.

Phương thứcVCIMASMô tả
overviewTổng quan doanh nghiệp
shareholdersCổ đông lớn
officersBan lãnh đạo
subsidiariesCông ty con
affiliateCông ty liên kết
newsTin tức doanh nghiệp
eventsSự kiện doanh nghiệp
reportsBáo cáo phân tích
trading_statsThống kê giao dịch
ratio_summaryTóm tắt chỉ số tài chính

Phương Thức Của Lớp Finance

Tập trung vào dữ liệu báo cáo tài chính đã chuẩn hóa & chỉ số phân tích.

Phương thứcVCIMASMô tả
balance_sheetBảng cân đối kế toán
income_statementBáo cáo kết quả kinh doanh
cashflowBáo cáo lưu chuyển tiền tệ
ratioChỉ số tài chính
annual_planKế hoạch năm

Phương Thức Của Lớp Quote

Theo dõi diễn biến giá theo thời gian.

Phương thứcVCIMASVNDMô tả
historyDữ liệu giá lịch sử
intradayDữ liệu giá trong ngày
price_depthThống kê bước giá & khối lượng

Phương Thức Của Lớp Trading

Khai thác dữ liệu giao dịch, khối lượng, đặt lệnh.

Phương thứcVCICafeFMô tả
price_boardThông tin bảng giá
trading_statsThống kê lịch sử giao dịch
side_statsDữ liệu cung cầu
price_historyLịch sử giá
foreign_tradeLịch sử giao dịch khối ngoại
prop_tradeLịch sử giao dịch tự doanh
order_statsThống kê đặt lệnh
insider_dealGiao dịch nội bộ và cổ đông lớn

Phương Thức Của Lớp Market

Thông tin định giá thị trường theo thời gian

Phương thứcVNDMô tả
peChỉ số định giá thị trường P/E
pbChỉ số định giá thị trường P/B
evaluationLịch sử định giá thị trường

Phương Thức Của Lớp Insights

Thống kê thị trường theo danh sách top cổ phiếu

Phương thứcVNDMô tả
gainerTop cổ phiếu tăng giá
loserTop cổ phiếu giảm giá
valueTop cổ phiếu theo giá trị giao dịch
volumeTop cổ phiếu theo KLGD
dealTop cổ phiếu theo giao dịch thỏa thuận
foreign_buyTop cổ phiếu NĐTNN mua ròng
foreign_sellTop cổ phiếu NĐTNN bán ròng

Phương Thức Của Lớp Macro

Dữ liệu kinh tế vĩ mô

Phương thứcMBKMô tả
gdpLấy chuỗi thời gian GDP theo quý/năm
cpiLấy chỉ số giá tiêu dùng (CPI) theo tháng/năm
industry_prodLấy chỉ số sản xuất công nghiệp theo tháng/năm
import_exportLấy số liệu xuất – nhập khẩu hàng hóa theo tháng/năm
retailLấy doanh thu bán lẻ tiêu dùng theo tháng/năm
fdiLấy vốn đầu tư trực tiếp nước ngoài (FDI) theo tháng/năm
money_supplyLấy số liệu cung tiền theo tháng/năm
exchange_rateLấy tỷ giá ngoại tệ (ví dụ USD/VND) theo ngày/năm
population_laborLấy thống kê dân số và lao động theo tháng/năm

Phương Thức Của Lớp Commodity

Dữ liệu thị trường hàng hóa

Phương thứcSPLMô tả
gold_vnLịch sử giá vàng giao dịch tại Việt Nam
gold_globalLịch sử giá vàng trên thị trường quốc tế
gas_vnLịch sử giá xăng và dầu diesel tại Việt Nam
oil_crudeLịch sử giá dầu thô trên thị trường thế giới
gas_naturalLịch sử giá khí thiên nhiên
cokeLịch sử giá than cốc phục vụ luyện kim
steel_d10Lịch sử giá thép thanh vằn D10 tại Việt Nam
iron_oreLịch sử giá quặng sắt trên thị trường quốc tế
steel_hrcLịch sử giá thép cuộn cán nóng (Hot-Rolled Coil, HRC)
fertilizer_ureLịch sử giá phân bón Urê
soybeanLịch sử giá đậu nành trên thị trường quốc tế
cornLịch sử giá ngô (bắp) trên thị trường quốc tế
sugarLịch sử giá đường trên thị trường quốc tế
pork_north_vnLịch sử giá lợn (heo) hơi tại vùng miền Bắc Việt Nam
pork_chinaLịch sử giá lợn (heo) hơi tại thị trường Trung Quốc

Thảo luận

Đang tải bình luận...