Lớp Macro: hàm truy xuất dữ liệu vĩ mô và hàng hoá
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_data v3.2.9: 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.
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 như ChatGPT/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.
- Cấu trúc dữ liệu (Schema): Để xem chính xác tên cột, kiểu dữ liệu (
Dtype) và ý nghĩa của các bảng dữ liệu trả về, vui lòng tham khảo chi tiết tại đây. KHÔNG nên suy đoán tên cột khi viết mã xử lý. - Cách Sử Dụng Nâng Cao: Hướng dẫn này tập trung vào kiến trúc Unified UI mặc định. Nếu bạn muốn can thiệp sâu vào nguồn dữ liệu, vui lòng tham khảo Tính Năng Nâng Cao.
📌 Tổng Quan
Macro Layer giúp bạn truy xuất dữ liệu kinh tế vĩ mô, tiền tệ, hàng hóa từ nguồn bên thứ ba, phục vụ cho:
- Phân tích tác động yếu tố kinh tế đến thị trường
- Theo dõi giá hàng hóa thế giới (vàng, dầu, thép, v.v.)
- Quản lý rủi ro tiền tệ, lãi suất
- Dự báo xu hướng kinh tế
🏗️ Cấu Trúc Domain
Macro()
├── .economy() # Dữ liệu kinh tế Việt Nam
├── .currency() # Tỷ giá, lãi suất
├── .commodity() # Giá hàng hóa thế giới
└── .global_macro # Chỉ số toàn cầu (bond, fed rate)1. Kinh tế Việt Nam (Economy)
Dữ liệu kinh tế Việt Nam theo quý/năm: GDP, CPI, FDI, xuất nhập khẩu, v.v.
Source: ASEAN
Nhóm lệnh: macro.economy
Phương Thức
| Method | Tham Số | Mô Tả | Return |
|---|---|---|---|
gdp() | start, end, period | Tăng trưởng GDP | DataFrame |
cpi() | start, end, period | Chỉ số giá tiêu dùng | DataFrame |
import_export() | start, end, period | Xuất nhập khẩu | DataFrame |
fdi() | start, end, period | Đầu tư trực tiếp nước ngoài | DataFrame |
money_supply() | start, end, period, breakdown | Cung tiền | DataFrame |
credit() | start, end, period, breakdown | Tín dụng | DataFrame |
total_investment() | start, end, period | Tổng vốn đầu tư | DataFrame |
state_budget() | start, end, period | Ngân sách nhà nước | DataFrame |
Parameters:
start: Mốc bắt đầu (ví dụ: "2020-01" hoặc "2020")end: Mốc kết thúc (ví dụ: "2026-03")period: "quarter" (mặc định) hoặc "month" hoặc "year"length: Số kỳ gần nhất (ví dụ: length=12 lấy 12 tháng gần nhất)
Ví Dụ
from vnstock_data import Macro
mac = Macro()
df_gdp_q = mac.economy().gdp(
start="2020-01",
end="2026-03",
period="quarter"
)
print(df_gdp_q.head(1))
df_cpi = mac.economy().cpi(period="month", length=24) # 24 tháng gần nhất
print(df_cpi.head(1))
df_trade = mac.economy().import_export(period="month")
df_fdi = mac.economy().fdi(period="month")
print(df_fdi.head(1))
df_money = mac.economy().money_supply(period="month")2. Tiền tệ & Lãi suất (Currency)
Tỷ giá hối đoái, lãi suất tiền tệ, chính sách tiền tệ.
Source: ASEAN
Nhóm lệnh: macro.currency
Phương Thức
| Method | Tham Số | Mô Tả | Return |
|---|---|---|---|
exchange_rate() | start, end, period | Tỷ giá hối đoái | DataFrame |
interbank_rate() | start, end, period | Lãi suất liên ngân hàng | DataFrame |
policy_rate() | start, end | Lãi suất điều hành | DataFrame |
omo() | start, end | Nghiệp vụ thị trường mở | DataFrame |
deposit_rate() | mode, period, start, end | Lãi suất huy động | DataFrame |
Parameters:
period: "day" (mặc định), "month", "quarter"length: Số kỳ gần nhất
Ví Dụ
from vnstock_data import Macro
mac = Macro()
df_exr = mac.currency().exchange_rate(
start="2026-02-06",
end="2026-03-06",
period="day"
)
print(df_exr[['time', 'USD', 'EUR', 'JPY']])
df_exr_m = mac.currency().exchange_rate(period="month", length=12)
print(df_exr_m[['time', 'USD', 'EUR']].tail())3. Hàng hóa (Commodity)
Giá hàng hóa quốc tế: vàng, dầu, khí thiên nhiên, thép, nông sản, v.v.
Source: ASEAN
Nhóm lệnh: macro.commodity
Phương Thức
| Method | Tham Số | Mô Tả | Return |
|---|---|---|---|
gold() | market, start, end | Giá vàng | DataFrame |
gas() | market, start, end | Giá khí thiên nhiên | DataFrame |
oil_crude() | start, end | Giá dầu thô | DataFrame |
coke() | start, end | Giá coke (than cốc) | DataFrame |
steel() | market, start, end | Giá thép | DataFrame |
iron_ore() | start, end | Giá quặng sắt | DataFrame |
soybean() | start, end | Giá đậu tương | DataFrame |
corn() | start, end | Giá ngô | DataFrame |
sugar() | start, end | Giá đường | DataFrame |
Parameters (cho gold, gas, steel):
market: "GLOBAL" (quốc tế)start,end: Khoảng thời gian lịch sử
Ví Dụ
from vnstock_data import Macro
import pandas as pd
mac = Macro()
df_gold_global = mac.commodity().gold(market="GLOBAL")
print(df_gold_global.head(1)) # OHLCV DataFrame
df_gas_global = mac.commodity().gas(market="GLOBAL")
print(df_gas_global.head(1)) # USD/MMBtu (OHLCV)
df_oil = mac.commodity().oil_crude()
print(df_oil.head(1))
df_coke = mac.commodity().coke()
print(df_coke.head(1))
df_steel_global = mac.commodity().steel(market="GLOBAL")
print(df_steel_global.head(1)) # USD/tấn (OHLCV)
df_ore = mac.commodity().iron_ore()
print(df_ore.head(1)) # USD/tấn (OHLCV)
df_soy = mac.commodity().soybean()
print(df_soy.head(1)) # USD/bushel (OHLCV)
df_corn = mac.commodity().corn()
print(df_corn.head(1))
df_sugar = mac.commodity().sugar()
print(df_sugar[['time', 'price']])4. Kinh tế toàn cầu (Global)
Truy xuất các chỉ số vĩ mô toàn cầu như lợi suất trái phiếu chính phủ, lãi suất Fed, và các chỉ số vĩ mô thế giới (ví dụ DXY).
Source: ASEAN
Nhóm lệnh: macro.global_macro
Phương Thức
| Method | Tham Số | Mô Tả | Return |
|---|---|---|---|
bond_yield() | market, tenor | Lợi suất trái phiếu chính phủ | DataFrame |
fed_rate() | start, end | Lãi suất Fed (US Federal Reserve Fund Rate) | DataFrame |
index() | symbol | Các chỉ số vĩ mô toàn cầu (ví dụ DXY) | DataFrame |
Parameters:
market: Ví dụ "VN"tenor: Kỳ hạn, ví dụ "10Y", "5Y"symbol: Ticker của chỉ số vĩ mô (mặc định 'DXY')
Ví Dụ
from vnstock_data import Macro
mac = Macro()
df_bond = mac.global_macro.bond_yield(market="VN", tenor="10Y")
df_fed = mac.global_macro.fed_rate()
df_dxy = mac.global_macro.index(symbol="DXY")⚠️ Lưu Ý Quan Trọng
1. Tương Thích Ngược
DEPRECATED (sẽ xóa sau 31/8/2026):
m = Macro()
df = m.exchange_rate(length=90) # ⚠️ WarningRECOMMENDED (Dùng từ bây giờ):
df = Macro().currency().exchange_rate(length=90)Tất cả legacy methods sẽ hiển thị deprecation warning bằng tiếng Việt + Anh:
[DEPRECATED] Macro.exchange_rate() sẽ bị xóa sau ngày 31/8/2026.
Vui lòng sử dụng Macro().currency().exchange_rate() thay thế. |
Macro.exchange_rate() is deprecated and will be removed after 31/8/2026.
Please use Macro().currency().exchange_rate() instead.
2. Độ Trễ Dữ Liệu
- GDP, CPI: Công bố quý/tháng, có độ trễ 1-2 tuần
- Tỷ giá: Cập nhật hằng ngày, có thể bị delay 1-2 giờ
- Giá hàng hóa: Cập nhật hằng ngày, trong phiên hoặc T+1, theo độ trễ của nguồn
3. Đơn Vị Tiền Tệ
- Tỷ giá: Nghìn VNĐ (ví dụ: 24.5 = 24,500 VNĐ)
- Dầu/Quặng: USD/barrel hoặc USD/tấn
- Nông sản: USD/bushel hoặc USD/tấn
4. Chỉ Số & Phần Trăm
- GDP Growth, CPI: Phần trăm YoY hoặc QoQ
- Lãi suất: Phần trăm năm (%/năm)
- Tỷ lệ: 0-100 (không phải 0-1)