Lớp Fundamental: hàm truy xuất dữ liệu báo cáo tài chính
Mục lục
Bản mặc định hiện là vnstock v5.0.0, gộp bản Cộng đồng và bản Mở rộng vào một thư viện. Trang này giữ lại cho máy còn cài vnstock v4.x: mã viết theo trang này vẫn chạy với bản đó. Đã cài bản mới thì đọc trang tương ứng của v5.0.0.
Máy đang cài bản nào: chạy python -c "import vnstock; print(vnstock.__version__)", ra số bắt đầu bằng 5. là thế hệ 5.
Kể từ phiên bản 4.0, Vnstock sử dụng kiến trúc Unified UI nhằm mang lại giao diện lập trình nhất quán và dễ sử dụng nhất. Dưới đây là tài liệu chính thức cho phiên bản mới.
Thư viện vnstock_data thuộc bản Mở rộng dành cho người tài trợ có thêm tính năng tự động quy chuẩn hoá báo cáo tài chính, thuận tiện khi làm việc với AI. Xem tài liệu Dữ Liệu Cơ Bản (Fundamental Data).
Nhóm Fundamental cung cấp bộ công cụ để truy xuất dữ liệu tài chính doanh nghiệp đã được chuẩn hóa, giúp bạn thực hiện phân tích cơ bản một cách nhanh chóng.
Khuyên dùng: Nên ưu tiên sử dụng Agent Guide để nạp môi trường cho AI Agent trên máy tính cục bộ. Tránh viết code thủ công hoặc dùng AI phiên bản web/Google Colab vì AI không có thông tin mới nhất về thư viện nên dễ viết sai cú pháp.
1. Khởi tạo
from vnstock import Fundamental
# Khởi tạo đối tượng Fundamental
fun = Fundamental()2. Các lớp và phương thức chi tiết
A. Lớp equity (Cổ phiếu)
Truy xuất báo cáo tài chính và chỉ số định giá của các doanh nghiệp niêm yết.
| Phương thức | Tham số | Mô tả |
|---|---|---|
income_statement() | period='year', orient='report', **kwargs | Kết quả kinh doanh. |
balance_sheet() | period='year', orient='report', **kwargs | Bảng cân đối kế toán. |
cash_flow() | period='year', orient='report', **kwargs | Lưu chuyển tiền tệ. |
ratio() | orient='report', **kwargs | Các chỉ số tài chính (P/E, P/B, ROE...). |
3. Tham số nâng cao
Tham số period (Kỳ báo cáo)
'year': Báo cáo theo năm (Mặc định).'quarter': Báo cáo theo quý.
Tham số orient (Định dạng kết quả)
Đây là tính năng độc đáo giúp bạn thay đổi cấu trúc DataFrame trả về để phù hợp với mục đích sử dụng:
'report'(Mặc định):- Hàng (Rows): Các chỉ tiêu tài chính (Doanh thu, Lợi nhuận...).
- Cột (Columns): Các kỳ báo cáo (2023, 2022...).
- Phù hợp để đọc và so sánh trực quan.
'time_series':- Hàng (Rows): Các kỳ báo cáo.
- Cột (Columns): Các chỉ tiêu tài chính.
- Phù hợp để vẽ biểu đồ hoặc chạy mô hình machine learning.
# Lấy báo cáo dưới dạng chuỗi thời gian để vẽ biểu đồ cho cổ phiếu VCB
fun.equity("VCB").income_statement(period='quarter')4. Cấu trúc dữ liệu
Kết quả trả về của các báo cáo (orient='report')
item: Tên chỉ tiêu tiếng Việt.item_en: Tên chỉ tiêu tiếng Anh (nếu có).unit: Đơn vị tính.- Các cột năm/quý (ví dụ:
2023,2022...): Giá trị tương ứng.
Các chỉ số tài chính (ratio)
Bao gồm hơn 50 chỉ số quan trọng, ví dụ:
ticker: Mã cổ phiếu.quarter/year: Kỳ báo cáo.priceToEarning: P/E.priceToBook: P/B.roe: Tỷ suất lợi nhuận trên vốn chủ sở hữu.roa: Tỷ suất lợi nhuận trên tổng tài sản.
Hệ thống tự động làm sạch dữ liệu như loại bỏ các hậu tố tên cột dư thừa (ví dụ: "-Năm") để DataFrame trả về gọn gàng và sẵn sàng cho tính toán phân tích.
Bản Cộng đồng có đủ các hàm cho nhu cầu phân tích cơ bản. Nếu bạn cần truy xuất báo cáo tài chính nhiều hơn 8 kỳ mặc định, hãy tham khảo các tính năng mở rộng của Bản Mở rộng.