Lấy dữ liệu vĩ mô Việt Nam bằng Python

Giá cổ phiếu không tự giải thích được chính nó. client.macro đưa CPI, tỷ giá, lãi suất, thanh khoản hệ thống và cán cân thương mại về cùng một DataFrame với dữ liệu thị trường, để bạn không phải đi lấy chỗ khác rồi tự ghép.

Nguồn là Tổng cục Thống kê và Ngân hàng Nhà nước; 3.348 chuỗi chỉ tiêu, cập nhật hằng ngày.

import finlens

client = finlens.client()

ds = client.macro.indicators(topic="cpi", freq="monthly")
df = client.macro.series(ds["code"].tolist()[:5])

Đơn vị nằm ở từng dòng

Mọi namespace khác của finlens khai đơn vị ở df.attrs["finlens"]["units"], và điều đó đúng vì một lời gọi không bao giờ trộn đơn vị: cổ phiếu và phái sinh nằm ở hai namespace khác nhau nên một bảng không thể vừa mang nghìn VND vừa mang điểm chỉ số.

Vĩ mô không có ranh giới nào như thế. Hỏi hai chỉ tiêu bất kỳ là một câu hỏi hoàn toàn bình thường:

df = client.macro.series(["gia_vang_giao_ngay_daily", "ty_gia_trung_tam_daily"])

df.groupby("code")["unit"].first()
# gia_vang_giao_ngay_daily    USD/Ounce
# ty_gia_trung_tam_daily      VND

Nên unit là một cột, và bạn đọc nó theo từng dòng. Tách bao nhiêu namespace cũng không đưa một bảng vĩ mô về một đơn vị duy nhất.

indicators() — tra mã trước khi hỏi số

client.macro.indicators(
    *,
    topic=None,
    freq=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Giá trị hợp lệ của topic chính là cột topic của kết quả — gọi không kèm bộ lọc một lần để xem có những chủ đề nào.

Cột trả về

Phân bố theo tần suất, đo ngày 06/08/2026:

last_date trả lời "chuỗi này phủ tới đâu", không phải "số mới nhất đã về chưa": danh mục được cache 12 giờ. Cần câu trả lời kia thì hỏi thẳng series().

series() — số liệu

client.macro.series(
    codes,
    *,
    start=None,
    end=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

codes là tham số vị trí duy nhất của cả namespace này, vì nó là danh sách khoá thật sự — ba phương thức còn lại chỉ mang bộ lọc nên đều keyword-only.

Bỏ trống start và end thì trả toàn bộ dải có dữ liệu. Không có mặc định nào bị bịa ra ở đây — khác dữ liệu giá, nơi mặc định là một năm gần nhất — vì một chuỗi vĩ mô có thể bắt đầu từ 2001 và cắt nó về một năm là bỏ mất phần lớn thứ người ta đến để lấy.

Cột trả về

Frame ở dạng long và sắp tăng dần theo (code, date). Thêm một chỉ tiêu là thêm dòng chứ không đổi schema.

date là cuối kỳ, period mới nói kỳ nào

Thư viện có ba loại cột thời gian, và đây là loại thứ ba:

2026-07-31 một mình không nói được đây là số của tháng 7 hay một quan sát ngày rơi đúng vào 31/7 — nên cột period đi kèm và mang nhãn đọc được.

Luôn dùng date để nối chuỗi, đừng phân tích period.

is_cumulative — cột dễ đọc sai nhất

2.135 trên 3.348 chuỗi mang giá trị luỹ kế từ đầu năm. Cùng một chỉ tiêu thường có cả hai dạng, và mã là thứ phân biệt:

df = client.macro.series([
    "tong_xuat_khau_gia_tri_luy_ke_m_monthly",   # cộng dồn từ đầu năm
    "tong_xuat_khau_gia_tri_thang_m_monthly",    # số của riêng tháng
])

df.groupby("code")["is_cumulative"].first()

Hai mã trên cùng đơn vị (Triệu USD), cùng tần suất, cùng 115 kỳ — và khác nhau đúng ở một cột.

Vẽ thẳng chuỗi luỹ kế lên biểu đồ thì đường sẽ leo suốt năm rồi rơi về gần 0 vào tháng 1. Đó là định nghĩa của nó, không phải một cú sụp.

Muốn số của riêng một kỳ thì lấy hiệu hai kỳ liên tiếp — nhưng chỉ với chuỗi mang đơn vị tuyệt đối. Với chuỗi % dạng "luỹ kế so với cùng kỳ năm trước" thì phép hiệu ấy vô nghĩa.

Tần suất là danh tính, không phải cách xem

70 chỉ tiêu thuộc nhóm Cán cân thanh toán tồn tại ở cả quý lẫn năm. Chúng là hai mã khác nhau mang hai bộ số khác nhau — chuỗi năm không phải chuỗi quý cộng lại. Đó là lý do mọi mã đều kết thúc bằng tần suất của nó.

omo() — nghiệp vụ thị trường mở

client.macro.omo(
    *,
    kind=None,
    start=None,
    end=None,
    freq="daily",
    refresh=False,
    on_error="warn",
) -> DataFrame

Khác freq của indicators(): ở đây nguồn phát sẵn cả ba mức và chúng nói về cùng một nghiệp vụ, nên đây thật sự là một cách xem.

Sáu nhóm, hai vũ trụ đo

tien = client.macro.omo(kind="reverse_repo,bill")
set(tien["unit"])   # {'VND'}

Cột trả về

direction là bản máy đọc được của cột name — "KL phát hành Reverse Repo" so với "KL đáo hạn Reverse Repo". Nó null ở các nhóm lãi suất và doanh số vì ở đó câu hỏi "chiều nào" không có nội dung.

Ba chân của tín phiếu — phát hành, lưu hành, đáo hạn — kết thúc ở ba ngày khác nhau. Kết quả kèm một cảnh báo nói ngày cuối cùng thực sự có số liệu, suy từ chính bảng bạn vừa nhận.

trade() — xuất nhập khẩu

client.macro.trade(
    *,
    flow="export",
    by="total",
    start=None,
    end=None,
    freq="monthly",
    refresh=False,
    on_error="warn",
) -> DataFrame

Cột trả về

freq="yearly" ở nguồn là luỹ kế từ đầu năm, không phải số của cả năm — máy chủ lọc về đúng kỳ cuối cùng của mỗi năm và kèm một cảnh báo nói rõ điều đó.

Cache

series() giữ 30 phút kể cả khi bạn chỉ hỏi chuỗi tháng, và đó là lựa chọn có chủ đích: thời gian sống được quyết định trước khi request rời khỏi máy bạn, nên thứ duy nhất đọc được là danh sách mã — mà suy tần suất từ tên mã sẽ buộc cache vào một quy ước đặt tên sửa tay được. Ngoài ra một lời gọi được phép trộn tần suất, nên thời gian sống của cả bảng phải là của chuỗi tươi nhất trong đó.

Dùng refresh=True khi bạn biết một kỳ mới vừa được công bố.

Hạn mức

Dữ liệu vĩ mô không bị kẹp theo độ sâu lịch sử của gói dịch vụ — đây là thông tin công khai của cơ quan thống kê. Hạn mức số chỉ tiêu mỗi request và hạn mức request theo ngày vẫn áp bình thường; nhiều mã được chia thành nhiều request và ghép lại trong suốt, giống mọi lời gọi nhiều mã khác.

Một mã không tồn tại không làm hỏng cả lời gọi: nó vào phần lỗi theo từng mã và các mã còn lại vẫn trả về, theo đúng on_error. Xem Xử lý lỗi.