Giới thiệu vnstock
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.
Dành cho người mới dùng vnstock — bản Cộng đồng, công khai mã nguồn theo giấy phép riêng. Trang này nói rõ bản Cộng đồng làm được gì, dừng ở đâu, và nên đọc tiếp trang nào. Nếu bạn đang dùng bộ thư viện mở rộng, xem Giới thiệu vnstock_data.
vnstock là thư viện Python để truy vấn và chuẩn hoá dữ liệu thị trường tài chính
Việt Nam. Thư viện chạy trên máy hoặc máy chủ do bạn kiểm soát: nó gửi truy vấn từ
runtime của bạn tới nguồn bạn chọn, rồi trả về dữ liệu đã chuẩn hoá dưới dạng
DataFrame của pandas.
Kể từ phiên bản 4.0, thư viện dùng kiến trúc Unified UI: một giao diện lập trình duy nhất cho mọi nhóm dữ liệu và mọi nguồn cấp.
Đặc tính của bản Cộng đồng
| Tiêu chí | Bản Cộng đồng vnstock |
|---|---|
| Giấy phép | Công khai mã nguồn theo giấy phép riêng |
| Mức phí | Miễn phí cho cá nhân, học tập và nghiên cứu |
| Phân phối | PyPI và GitHub |
| Hạn mức | Một hạn mức chung cho mọi thư viện của tài khoản, chia theo giờ, ngày, tháng (giờ Việt Nam). Xem phần trăm còn lại ở trang tài khoản. Thư viện còn giữ nhịp gọi vừa phải để giữ tải hợp lý với nguồn |
| Dữ liệu trong phiên | Qua REST API, cập nhật theo độ trễ của nguồn |
| Lịch sử giá | Tối đa 8 năm khung ngày, 1 năm khung phút |
| Giao dịch trong ngày | Tối đa 30.000 bản ghi |
| Báo cáo tài chính | Tối đa 8 kỳ khi xác thực khoá API, 4 kỳ ở chế độ khách |
| Yêu cầu đồng thời | Bạn tự kiểm soát; nên giữ ở mức thấp và có khoảng nghỉ giữa các yêu cầu |
Bảng đối chiếu đầy đủ từng hàm giữa hai bản nằm ở So sánh Bản Cộng đồng và Bản Mở rộng.
Học tập, nghiên cứu, tra cứu nhanh và làm quen với lập trình dữ liệu tài chính. Nếu bạn cần các thư viện bổ sung, lớp dữ liệu chuẩn hoá rộng hơn, hoặc lịch sử dài hơn giới hạn ở bảng trên, hãy đọc phần so sánh trước khi quyết định.
Cài đặt
pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnaivnstock và gói đi kèm vnai được phân phối từ kho gói của Vnstock, nên lệnh cài
cần phần --extra-index-url. Thiếu phần này, pip sẽ báo
Could not find a version that satisfies the requirement. Các thư viện phụ thuộc
khác như pandas vẫn tải từ PyPI như bình thường. Trên Google Colab hay Jupyter,
thêm dấu ! ở đầu lệnh.
Khi thư viện báo có phiên bản mới, chạy lại đúng lệnh trên để cập nhật, rồi khởi động lại kernel hoặc phiên Colab.
Muốn chạy thử ngay trên trình duyệt mà không cài gì, xem Chạy thử trên Colab. Muốn dựng môi trường Python đàng hoàng trên máy, xem Cài Python cho người mới.
Bốn nhóm dữ liệu
Unified UI chia dữ liệu theo nghiệp vụ, mỗi nhóm một trang tài liệu riêng:
| Nhóm | Nội dung | Tài liệu |
|---|---|---|
| Reference | Thông tin tham chiếu về doanh nghiệp, cổ phiếu, chỉ số | Dữ liệu tham chiếu |
| Market | Giá lịch sử, khớp lệnh, bảng giá | Dữ liệu thị trường |
| Fundamental | Báo cáo tài chính và chỉ số định giá | Phân tích cơ bản |
| Retail | Thông tin thị trường bán lẻ (tỷ giá ngoại tệ...) | Thị trường bán lẻ |
Đọc tiếp
- Kiến trúc thư viện — ba lớp của Unified UI và ba cách gọi lệnh tương ứng.
- Biểu diễn dữ liệu — vẽ biểu đồ từ bảng dữ liệu vừa lấy về.
- Tự động nạp Agent Skills và tài liệu — để trợ lý AI viết mã Vnstock đúng ngay từ đầu.
- Lịch sử phiên bản — thay đổi qua từng bản phát hành.