Kinh tế vĩ mô
Mục lục
Mọi hàm trên trang này chạy với khoá API từ cấp tài trợ Bronze trở lên. Khoá cấp Cộng đồng hoặc chạy không khoá nhận EntitlementError (mã VNSTOCK_TIER_ROUTE hoặc VNSTOCK_TIER_SOURCE), và thư viện không gửi truy vấn nào đi.
Lớp Macro() giúp bạn tự truy xuất số liệu kinh tế vĩ mô của Việt Nam, tỷ giá, lãi suất và vài
chuỗi vĩ mô thế giới. Hàm chia thành ba nhóm:
Macro().economy(): GDP, CPI, xuất nhập khẩu, FDI, cung tiền, tín dụng, vốn đầu tư, ngân sách.Macro().currency(): tỷ giá, nghiệp vụ thị trường mở, lãi suất điều hành, tiền gửi, liên ngân hàng.Macro().global_macro(tên khácMacro().world): lợi suất trái phiếu, lãi suất Fed, DXY, DJI.
Lưu ý cách gọi: economy() và currency() là hàm (có ngoặc), còn global_macro là thuộc
tính (không ngoặc).
Mọi hàm lấy từ nguồn asean và không có tham số source. Đọc nguồn của kết quả ở
df.attrs["source"].
Tóm tắt
| Hàm | Làm gì | Cấp |
|---|---|---|
economy().gdp() | Tăng trưởng GDP và phần đóng góp từng khu vực | Tài trợ |
economy().cpi() | CPI tổng và CPI lõi | Tài trợ |
economy().import_export() | Kim ngạch xuất khẩu, nhập khẩu, cán cân | Tài trợ |
economy().fdi() | FDI đăng ký, giải ngân | Tài trợ |
economy().money_supply() | Cung tiền | Tài trợ |
economy().credit() | Tăng trưởng tín dụng | Tài trợ |
economy().total_investment() | Vốn đầu tư toàn xã hội theo khu vực | Tài trợ |
economy().state_budget() | Thu, chi, cân đối ngân sách | Tài trợ |
currency().exchange_rate() | Tỷ giá USD/VND | Tài trợ |
currency().omo() | Nghiệp vụ thị trường mở | Tài trợ |
currency().policy_rate() | Lãi suất tái cấp vốn, chiết khấu | Tài trợ |
currency().deposit_rate() | Lãi suất tiền gửi theo ngân hàng, kỳ hạn | Tài trợ |
currency().interbank_rate() | Lãi suất liên ngân hàng một kỳ hạn | Tài trợ |
global_macro.bond_yield() | Lợi suất trái phiếu chính phủ VN, Mỹ | Tài trợ |
global_macro.fed_rate() | Lãi suất quỹ liên bang Mỹ | Tài trợ |
global_macro.index() | Chỉ số DXY hoặc DJI | Tài trợ |
1. Khởi tạo
from vnstock import Macro
macro = Macro()
eco = macro.economy()
cur = macro.currency()
glb = macro.global_macro2. Tham số thời gian chung
Các hàm của economy() và currency() nhận cùng ba tham số khoảng thời gian:
| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
start | str | None | Đầu kỳ: "YYYY", "YYYY-MM" hoặc "YYYY-MM-DD". Để trống thì lấy ba năm trước end |
end | str | None | Cuối kỳ, cùng dạng. Để trống thì lấy hôm nay |
length | int | None | Chỉ giữ chừng này dòng gần nhất |
length là số dòng. Bản 3.x nhận cả chuỗi như "1Y", "3M"; thế hệ 5 thì không, truyền
"1Y" nhận ValueError. Muốn lấy theo khoảng thời gian, dùng start và end.
start sau end thì nhận InputError mã VNSTOCK_INPUT_WINDOW.
Tham số period (kỳ số liệu) của nhóm economy() nhận "month", "quarter" hoặc "year".
Mỗi hàm có mặc định riêng, ghi trong bảng của hàm đó. Không phải chỉ tiêu nào cũng có đủ ba kỳ: hỏi
gdp(period="month") nhận ProviderError mã VNSTOCK_SOURCE_NOT_FOUND.
Mọi bảng có cột time kiểu ngày, múi giờ Asia/Ho_Chi_Minh, là ngày cuối kỳ (ví dụ quý 3 là
30/09). Nhiều bảng có thêm cột vnindex: điểm VN-Index tại cùng mốc, để bạn đặt hai chuỗi cạnh
nhau.
3. Kinh tế — Macro().economy()
3.1. GDP — gdp()
eco.gdp(start=None, end=None, period="quarter", length=None)period: "quarter" (mặc định) hoặc "year".
df = eco.gdp(start="2025", length=3) # 3 quý gần nhất
df = eco.gdp(start="2023", period="year") # theo năm| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
gdp | số | Tăng trưởng GDP so với cùng kỳ, % |
agriculture, industry, services, tax | số | Phần đóng góp của nông nghiệp, công nghiệp, dịch vụ, thuế vào mức tăng, điểm %. Bốn cột cộng lại bằng gdp |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026):
time agriculture industry services tax gdp vnindex
0 2026-03-31 00:00:00+07:00 0.91654 2.90554 3.38016 0.62400 7.82625 1674.49
1 2026-06-30 00:00:00+07:00 0.97476 3.33868 3.49025 0.58869 8.39239 1860.01
2 2026-09-30 00:00:00+07:00 1.19158 4.09488 4.01025 0.65128 9.94799 1768.62
3.2. CPI — cpi()
eco.cpi(start=None, end=None, period="month", length=None)period: "month" (mặc định), "quarter" hoặc "year".
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
cpi_total | số | CPI tổng, % so với cùng kỳ |
cpi_core | số | CPI lõi, % so với cùng kỳ |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, cpi(start="2026-01", length=3)):
time cpi_total cpi_core vnindex
0 2026-07-31 00:00:00+07:00 4.45 4.63 1735.78
1 2026-08-31 00:00:00+07:00 4.89 4.55 1832.12
2 2026-09-30 00:00:00+07:00 5.08 4.45 1768.62
3.3. Xuất nhập khẩu — import_export()
eco.import_export(start=None, end=None, period="month", length=None)period: "month" (mặc định), "quarter" hoặc "year".
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
export_value | số | Kim ngạch xuất khẩu, triệu USD |
import_value | số | Kim ngạch nhập khẩu, triệu USD |
balance_value | số | Cán cân thương mại (xuất trừ nhập), triệu USD |
export_growth | số | Tăng trưởng xuất khẩu, % |
import_growth | số | Tăng trưởng nhập khẩu, % |
vnindex | số | Lần chạy 10/10/2026, cột này bằng 0 ở mọi dòng của bảng này |
Dữ liệu mẫu (chạy ngày 10/10/2026, import_export(start="2026-01", length=3)):
time export_value import_value balance_value export_growth import_growth
0 2026-07-31 00:00:00+07:00 53081.329334 56668.257918 -3586.928584 4.52 6.06
1 2026-08-31 00:00:00+07:00 54794.764261 54907.979099 -113.214838 3.23 -3.11
2 2026-09-30 00:00:00+07:00 59477.404354 58206.560939 1270.843415 8.55 6.01
3.4. FDI — fdi()
eco.fdi(start=None, end=None, period="month", length=None)period: "month" (mặc định), "quarter" hoặc "year".
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
register_value | số | Vốn FDI đăng ký, triệu USD |
realized_value | số | Vốn FDI giải ngân, triệu USD |
realized_percent | số | Giải ngân trên đăng ký, % |
Bảng này không có cột vnindex.
Dữ liệu mẫu (chạy ngày 10/10/2026, fdi(length=3)):
time register_value realized_value realized_percent
0 2025-01-31 00:00:00+07:00 4334.79 1510.0 34.83444
1 2025-02-28 00:00:00+07:00 2570.13 1440.0 56.02829
2 2025-03-31 00:00:00+07:00 4073.71 2012.0 49.38987
Lần chạy này, kỳ mới nhất nhận được là tháng 3/2025, nên fdi(start="2026-01") trả bảng rỗng.
3.5. Cung tiền — money_supply()
eco.money_supply(breakdown="total", start=None, end=None, period="quarter", length=None)| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
breakdown | str | "total" | Chỉ nhận "total". "bank" chưa hỗ trợ, nhận UnsupportedError mã VNSTOCK_ROUTE_NOT_MIGRATED |
period | str | "quarter" | "quarter", "month" hoặc "year" |
Hàm này nằm ở economy(), không ở currency().
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
total | số | Tổng phương tiện thanh toán, tỷ đồng |
institutional | số | Phần của tổ chức, tỷ đồng |
private | số | Phần của dân cư, tỷ đồng |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, money_supply(length=3)):
time total institutional private vnindex
0 2024-12-31 00:00:00+07:00 17914566.0 7667207.69 7065062.55 1266.78
1 2025-03-31 00:00:00+07:00 18450042.0 7520233.24 7469971.36 1306.86
2 2025-06-30 00:00:00+07:00 19584434.0 8104341.37 7694546.37 1376.07
3.6. Tín dụng — credit()
eco.credit(breakdown="total", start=None, end=None, period="quarter", length=None)breakdown chỉ nhận "total"; giá trị khác nhận UnsupportedError. period: "quarter"
(mặc định), "month" hoặc "year".
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
credit_growth | số | Tăng trưởng tín dụng toàn nền kinh tế, % |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, credit(length=3)):
time credit_growth vnindex
0 2024-12-31 00:00:00+07:00 15.08762 1266.78
1 2025-03-31 00:00:00+07:00 17.91271 1306.86
2 2025-06-30 00:00:00+07:00 19.21941 1376.07
3.7. Vốn đầu tư toàn xã hội — total_investment()
eco.total_investment(start=None, end=None, period="quarter", length=None)period: "quarter" (mặc định), "month" hoặc "year".
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
public | số | Khu vực nhà nước, nghìn tỷ đồng |
private | số | Khu vực ngoài nhà nước, nghìn tỷ đồng |
fdi | số | Khu vực vốn đầu tư nước ngoài, nghìn tỷ đồng |
other | số | Khác, nghìn tỷ đồng |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, total_investment(start="2025", length=3)):
time public private fdi other vnindex
0 2026-03-31 00:00:00+07:00 184.680 402.500 135.050 22.480 1674.49
1 2026-06-30 00:00:00+07:00 271.980 566.911 191.021 29.604 1860.01
2 2026-09-30 00:00:00+07:00 385.836 671.335 203.285 30.785 1768.62
3.8. Ngân sách nhà nước — state_budget()
eco.state_budget(start=None, end=None, period="quarter", length=None)period: "quarter" (mặc định), "month" hoặc "year".
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Cuối kỳ |
budget_in | số | Thu ngân sách, tỷ đồng |
budget_out | số | Chi ngân sách, tỷ đồng |
budget_net | số | Cân đối thu chi, tỷ đồng |
Bảng này không có cột vnindex.
Dữ liệu mẫu (chạy ngày 10/10/2026, state_budget(length=2)):
time budget_in budget_out budget_net
0 2023-12-31 00:00:00+07:00 1620758.0 2035930.0 415172.0
1 2024-03-31 00:00:00+07:00 539540.0 393495.0 -146045.0
Lần chạy này, kỳ mới nhất nhận được là quý 1/2024. Dấu của budget_net chưa thống nhất giữa các
kỳ: ở kỳ quý, cột này bằng chi trừ thu; ở kỳ năm, bằng thu trừ chi. Nếu cần một quy ước dấu cố định,
tự tính budget_in - budget_out.
4. Tỷ giá và lãi suất — Macro().currency()
4.1. Tỷ giá — exchange_rate()
cur.exchange_rate(start=None, end=None, period="day", length=None)Tham số period có trong chữ ký nhưng hiện không đổi tần suất: kết quả luôn là một dòng mỗi ngày.
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Ngày |
center_rate | số | Tỷ giá trung tâm, đồng/USD. Lần chạy 10/10/2026, các dòng gần nhất để trống |
vcb_rate | số | Tỷ giá tại Vietcombank, đồng/USD |
market_rate | số | Tỷ giá thị trường, đồng/USD |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, exchange_rate(start="2026-09-25", length=3)):
time center_rate vcb_rate market_rate vnindex
0 2026-10-07 00:00:00+07:00 NaN 26170.0 26140.0 1753.39
1 2026-10-08 00:00:00+07:00 NaN 26160.0 26140.0 1738.97
2 2026-10-09 00:00:00+07:00 NaN 26020.0 26180.0 1735.09
Tỷ giá mua bán nhiều ngoại tệ tại ngân hàng thì dùng Retail().exchange_rate() (trang
Retail).
4.2. Nghiệp vụ thị trường mở — omo()
cur.omo(start=None, end=None, length=None)| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Ngày |
inflow_amount | số | Lượng bơm ra, tỷ đồng |
outflow_amount | số | Lượng hút về, tỷ đồng |
netflow_amount | số | Bơm ròng (bơm trừ hút), tỷ đồng |
cumulative_flow_amount | số | Lượng còn lưu hành, tỷ đồng |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, omo(start="2026-09-25", length=3), nhận 2 dòng):
time vnindex inflow_amount outflow_amount netflow_amount cumulative_flow_amount
0 2026-10-01 00:00:00+07:00 1749.30 577.84 1000.00 -422.16 217459.23
1 2026-10-02 00:00:00+07:00 1737.71 0.00 2147.92 -2147.92 215311.31
4.3. Lãi suất điều hành — policy_rate()
cur.policy_rate(start=None, end=None, length=None)Một dòng mỗi ngày.
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Ngày |
refinance | số | Lãi suất tái cấp vốn, %/năm |
discount | số | Lãi suất tái chiết khấu, %/năm |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, policy_rate(start="2026-01-01", length=3)):
time refinance discount vnindex
0 2026-10-07 00:00:00+07:00 4.5 3.0 1753.39
1 2026-10-08 00:00:00+07:00 4.5 3.0 1738.97
2 2026-10-09 00:00:00+07:00 4.5 3.0 1735.09
4.4. Lãi suất tiền gửi — deposit_rate()
cur.deposit_rate(mode="term", period="all", start=None, end=None, length=None)| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
mode | str | "term" | Chỉ nhận "term": bảng hiện hành, mỗi ngân hàng một dòng. "historical" chưa hỗ trợ, nhận UnsupportedError mã VNSTOCK_ROUTE_NOT_MIGRATED |
period | str | "all" | Giữ cho mã cũ, hiện không dùng |
length | int | None | Số dòng tối đa |
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
bank_code | chuỗi | Mã ngân hàng |
bank_name, bank_name_en | chuỗi | Tên ngân hàng, tiếng Việt và tiếng Anh |
time | ngày | Ngày cập nhật |
interest_1m, interest_3m, interest_6m, interest_13m, interest_36m | số | Lãi suất kỳ hạn 1, 3, 6, 13, 36 tháng, %/năm |
Dữ liệu mẫu (chạy ngày 10/10/2026, deposit_rate(length=3)):
bank_code bank_name time interest_1m interest_3m interest_6m interest_13m
0 VCB Vietcombank 2026-10-02 00:00:00+07:00 2.10 2.40 3.5 5.9
1 VIB Ngân hàng Quốc tế 2026-10-02 00:00:00+07:00 4.25 4.35 5.5 6.5
2 VPB VPBank 2026-10-02 00:00:00+07:00 4.45 4.65 6.8 6.9
4.5. Lãi suất liên ngân hàng — interbank_rate()
cur.interbank_rate(period="ON", start=None, end=None, length=None)Ở hàm này period là kỳ hạn, không phải tần suất, và đứng đầu danh sách tham số.
| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
period | str | "ON" | Kỳ hạn: "ON" (qua đêm), "1W", "1M", "3M". Mỗi lần gọi một kỳ hạn |
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Ngày |
interest | số | Lãi suất của kỳ hạn đã chọn, %/năm |
vnindex | số | Điểm VN-Index |
Dữ liệu mẫu (chạy ngày 10/10/2026, interbank_rate(start="2026-09-25", length=3), kỳ hạn qua đêm):
time interest vnindex
0 2026-09-29 00:00:00+07:00 0.56 1777.73
1 2026-09-30 00:00:00+07:00 6.95 1768.62
2 2026-10-01 00:00:00+07:00 4.29 1749.30
5. Vĩ mô thế giới — Macro().global_macro
Macro().world là tên khác, cho cùng kết quả. Ba hàm nhận chung các tham số sau:
| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
start | str | None | Ngày bắt đầu, "YYYY-MM-DD" |
end | str | None | Ngày kết thúc, "YYYY-MM-DD". Để trống thì lấy hôm nay |
length | int | None | Chỉ giữ chừng này dòng gần nhất |
resolution | str | "1D" | Khung nến: "1D", "1W" hoặc "1M". Giá trị khác nhận InputError mã VNSTOCK_INPUT_INTERVAL |
Cả ba trả bảng nến cùng cột:
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | ngày | Ngày của nến |
open, high, low, close | số | Giá trị mở, cao, thấp, đóng. Với lợi suất và lãi suất: %/năm; với chỉ số: điểm |
volume | số | Khối lượng. Bằng 0 với các chuỗi không có khối lượng |
5.1. Lợi suất trái phiếu chính phủ — bond_yield()
glb.bond_yield(market="VN", tenor="10Y", start=None, end=None, length=None, resolution="1D")| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
market | str | "VN" | "VN" hoặc "US". Giá trị khác nhận InputError mã VNSTOCK_INPUT_MARKET |
tenor | str | "10Y" | VN: 1Y, 2Y, 3Y, 5Y, 10Y. US: 1Y, 2Y, 5Y, 10Y, 30Y |
Kỳ hạn không có trong danh sách hiện trả bảng rỗng, không báo lỗi. Lần chạy 10/10/2026, US 30Y
cũng trả bảng rỗng; US 10Y, VN 2Y, VN 10Y có dữ liệu.
Dữ liệu mẫu (chạy ngày 10/10/2026, bond_yield(start="2026-09-25", length=3), VN 10 năm):
time open high low close volume
0 2026-10-07 00:00:00+07:00 4.58 4.58 4.58 4.58 0.0
1 2026-10-08 00:00:00+07:00 4.56 4.56 4.56 4.56 0.0
2 2026-10-09 00:00:00+07:00 4.56 4.58 4.56 4.58 0.0
5.2. Lãi suất Fed — fed_rate()
glb.fed_rate(start=None, end=None, length=None, resolution="1D")Chuỗi này thưa: lần chạy 10/10/2026 cho một dòng mỗi tháng dù resolution="1D".
Dữ liệu mẫu (chạy ngày 10/10/2026, world.fed_rate(length=2)):
time open high low close volume
0 2026-08-01 00:00:00+07:00 3.63 3.63 3.63 3.63 0.0
1 2026-09-01 00:00:00+07:00 3.75 3.75 3.75 3.75 0.0
5.3. Chỉ số DXY, DJI — index()
glb.index(symbol="DXY", start=None, end=None, length=None, resolution="1D")symbol nhận "DXY" (chỉ số đô la Mỹ, mặc định) hoặc "DJI" (Dow Jones). Mã khác nhận
InputError mã VNSTOCK_INPUT_SYMBOL. Chỉ số chứng khoán thế giới khác (ví dụ USA30, JPN225)
nằm ở Market().index(symbol, scope="global"), trang
Tài sản quốc tế.
Dữ liệu mẫu (chạy ngày 10/10/2026, index("DXY", start="2026-09-25", length=3)):
time open high low close volume
0 2026-10-07 00:00:00+07:00 101.89 102.50 101.89 102.24 0.0
1 2026-10-08 00:00:00+07:00 102.23 102.47 102.03 102.14 0.0
2 2026-10-09 00:00:00+07:00 102.13 102.34 101.92 102.23 0.0
6. Đã ngừng
Các hàm dưới đây vẫn giữ tên để mã cũ không gặp AttributeError, nhưng gọi là nhận
UnsupportedError mã VNSTOCK_FEATURE_REMOVED và không có dữ liệu trả về.
Chỉ tiêu đã gỡ, không có hàm thay:
| Hàm | Ngừng từ |
|---|---|
Macro().economy().industry_prod() | 5.0.0a3 |
Macro().economy().retail() | 5.0.0a3 |
Macro().economy().population_labor() | 5.0.0a3 |
Macro().currency().interest_rate() | 5.0.0a3. Dùng interbank_rate(), policy_rate(), deposit_rate() cho từng loại lãi suất |
Macro().commodity() | 5.0.0a2. Giá hàng hoá quốc tế ở Market().commodity(symbol), trang Tài sản quốc tế |
Hàm phẳng kiểu cũ trên Macro(). Bản 3.x cho gọi thẳng Macro().gdp(), Macro().exchange_rate()…
kèm cảnh báo hết hạn ngày 31/08/2026. Từ 5.0.0a6 các hàm này báo lỗi, và thông báo lỗi nêu hàm thay:
| Hàm cũ | Dùng thay |
|---|---|
Macro().gdp() | Macro().economy().gdp() |
Macro().cpi() | Macro().economy().cpi() |
Macro().import_export() | Macro().economy().import_export() |
Macro().fdi() | Macro().economy().fdi() |
Macro().money_supply() | Macro().economy().money_supply() |
Macro().exchange_rate() | Macro().currency().exchange_rate() |
Macro().industry_prod() | Không có (ngừng từ 5.0.0a3) |
Macro().retail() | Không có (ngừng từ 5.0.0a3) |
Macro().population_labor() | Không có (ngừng từ 5.0.0a3) |
Macro().interest_rate() | Không có hàm gộp; dùng các hàm lãi suất của currency() |
Ví dụ thông báo khi gọi hàm cũ:
UnsupportedError: `Macro().gdp()` đã ngừng hỗ trợ từ vnstock 5.0.0a6 và không còn trả dữ liệu. Dùng Macro().economy().gdp().
Bảng trả về của thế hệ 5 cũng khác hàm phẳng cũ: mỗi kỳ một dòng, mỗi chỉ tiêu một cột (ví dụ
agriculture, industry, gdp), thay cho bảng dọc có group_name, name, value, unit.
Hàm gdp() mới không còn tham số keep_label.
Bắt lỗi theo mã, xem Xử lý lỗi:
from vnstock import Macro
from vnstock.core.exceptions import UnsupportedError
try:
df = Macro().economy().gdp(length=4)
except UnsupportedError as e:
print(e.code)