Dữ Liệu Vĩ Mô & Hàng Hóa (Macro Data)
Cập nhật lần cuối:
Thảo luậnMục lục
Lưu ý Quan Trọng
- 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 cung cấp dữ liệu kinh tế vĩ mô, tiền tệ, hàng hóa phục vụ cho:
- Phân tích tác động yếu tố kinh tế đến thị trường
- Trading danh sách hàng hóa (gold, oil, steel, etc.)
- 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
Python
Macro()
├── .economy() # Dữ liệu kinh tế Việt Nam
├── .currency() # Tỷ giá, lãi suất
├── .commodity() # Giá hàng hóa
└── .global # 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 |
industry_prod() | start, end, period | Sản xuất công nghiệp | DataFrame |
import_export() | start, end, period | Xuất nhập khẩu | DataFrame |
retail() | start, end, period | Bán lẻ | 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 |
population_labor() | start, end, period | Dân số & lao động | 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ụ
Python
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_ind = mac.economy().industry_prod(period="month", length=12)
print(df_ind.head(1))
df_trade = mac.economy().import_export(period="month")
df_retail = mac.economy().retail(period="month")
df_fdi = mac.economy().fdi(period="month")
print(df_fdi.head(1))
df_money = mac.economy().money_supply(period="month")
df_labor = mac.economy().population_labor(period="year")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 |
interest_rate() | start, end, period, format | Lãi suất | 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"format: "pivot" (mặc định) hoặc "long"length: Số kỳ gần nhất
Ví Dụ
Python
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())
df_ir = mac.currency().interest_rate(
period="day",
length=365 # 1 năm gần nhất
)
print(df_ir[['time', 'lending_rate', 'deposit_rate']])
df_ir_long = mac.currency().interest_rate(period="month", format="long")
print(df_ir_long[['date', 'rate_type', 'rate_value']].head(10))3. Hàng hóa (Commodity)
Giá hàng hóa địa phương và quốc tế: vàng, dầu, thép, nông sản, v.v.
Source: ASEAN (Quốc tế), SPL (Nội địa)
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á xăng dầu | 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 |
fertilizer_ure() | start, end | Giá phân URE | DataFrame |
soybean() | start, end | Giá đậu tương | DataFrame |
corn() | start, end | Giá ngô | DataFrame |
sugar() | start, end | Giá đường | DataFrame |
pork() | market, start, end | Giá thịt lợn | DataFrame |
Parameters (cho gold, gas, steel, pork):
market: "VN" (Việt Nam) hoặc "GLOBAL" (quốc tế), mặc định = "VN"start,end: Khoảng thời gian lịch sử
Ví Dụ
Python
from vnstock_data import Macro
import pandas as pd
mac = Macro()
df_gold_vn = mac.commodity().gold(market="VN")
print(df_gold_vn[['time', 'price']].tail())
df_gold_global = mac.commodity().gold(market="GLOBAL")
print(df_gold_global.head(1)) # OHLCV DataFrame
df_gas_vn = mac.commodity().gas(market="VN")
print(df_gas_vn.head(1))
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_vn = mac.commodity().steel(market="VN")
print(df_steel_vn.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']])
df_pork_vn = mac.commodity().pork(market="VN")
print(df_pork_vn[['time', 'price']]) # VNĐ/kg
df_pork_china = mac.commodity().pork(market="CHINA")
print(df_pork_china[['time', 'price']])4. Kinh tế toàn cầu (Global)
Cung cấp 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
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ụ
Python
from vnstock_data import Macro
mac = Macro()
df_bond = mac.global.bond_yield(market="VN", tenor="10Y")
df_fed = mac.global.fed_rate()
df_dxy = mac.global.index(symbol="DXY")⚠️ Lưu Ý Quan Trọng
1. Tương Thích Ngược
DEPRECATED (sẽ xóa sau 31/8/2026):
Python
m = Macro()
df = m.interest_rate(length=90) # ⚠️ WarningRECOMMENDED (Dùng từ bây giờ):
Python
df = Macro().currency().interest_rate(length=90)Tất cả legacy methods sẽ hiển thị deprecation warning bằng tiếng Việt + Anh:
[DEPRECATED] Macro.interest_rate() sẽ bị xóa sau ngày 31/8/2026.
Vui lòng sử dụng Macro().currency().interest_rate() thay thế. |
Macro.interest_rate() is deprecated and will be removed after 31/8/2026.
Please use Macro().currency().interest_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, realtime hoặc T+1
3. Đơn Vị Tiền Tệ
- Tỷ giá: Nghìn VNĐ (ví dụ: 24.5 = 24,500 VNĐ)
- Vàng: VNĐ/lượng
- 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)
Thảo luận