bcra-macro

BCRA Macro — 货币统计 API v4.0

BCRA 官方 API，用于查询全国宏观经济变量（非省级变量）。
Base URL： https://api.bcra.gob.ar
总目录： 1220 个序列 → ./references/VARIABLES.md 中的 638 个全国序列。

端点

#	Endpoint	用途
1	GET /estadisticas/v4.0/Monetarias	变量目录（分页）
2	GET /estadisticas/v4.0/Monetarias/{IdVariable}	变量历史序列（分页）
3	GET /estadisticas/v4.0/Metodologia	方法论索引（分页）
4	GET /estadisticas/v4.0/Metodologia/{IdVariable}	变量的方法论说明

身份验证： 无需。CORS： 开放。编码： 部分文本使用 ISO-8859-1。

---

1. 变量目录

GET /estadisticas/v4.0/Monetarias

返回包含元数据的完整列表（idVariable、descripcion、categoria、tipoSerie、periodicidad、unidadExpresion、moneda、primerFechaInformada、ultFechaInformado、ultValorInformado）。

可用筛选条件（查询参数）

参数	类型	描述
IdVariable	int	按精确 ID 筛选
Categoria	string	部分匹配搜索，无重音符号（"depositos"、"prestamos"）
Periodicidad	string	D 每日，M 每月，T 每季度
Moneda	string	PES、DOL、ML、ME、MEyML
TipoSerie	string	Stock、Flujo、Tasa 等
UnidadExpresion	string	自由文本
Limit	int	默认值为 1000，最大 3000
Offset	int	分页（增加偏移量）

最简示例

import requests, pandas as pd
r = requests.get("https://api.bcra.gob.ar/estadisticas/v4.0/Monetarias", params={"Limit": 3000})
df = pd.DataFrame(r.json()["results"])

---

2. 变量历史序列

GET /estadisticas/v4.0/Monetarias/{IdVariable}

返回 {idVariable, detalle: [{fecha, valor}]}。

参数	类型	必填	描述
IdVariable	int (path)	是	变量的 ID
Desde	string	否	YYYY-MM-DD
Hasta	string	否	YYYY-MM-DD
Limit	int	否	默认值为 1000，最大 3000
Offset	int	否	分页

r = requests.get("https://api.bcra.gob.ar/estadisticas/v4.0/Monetarias/1",
                 params={"Desde": "2020-01-01", "Hasta": "2025-12-31"})
df = pd.DataFrame(r.json()["results"][0]["detalle"])
df["fecha"] = pd.to_datetime(df["fecha"])
df = df.set_index("fecha").sort_index()

---

3. 方法论

GET /estadisticas/v4.0/Metodologia           # índice paginado
GET /estadisticas/v4.0/Metodologia/{idVar}   # ficha completa

r = requests.get("https://api.bcra.gob.ar/estadisticas/v4.0/Metodologia/1")
print(r.json()["results"][0]["detalle"])

---

4. 分页：如何突破 3000 条记录的限制

API 每次调用最多返回 3000 行，而最长的每日序列（国际储备，ID 1）自 1996 年以来有 ~9000 条观测值。有两种策略。

策略 A — 使用 Offset 分页（最简单）

循环执行，每次将 Offset += Limit，直到响应为空。

import requests, pandas as pd

def get_serie(id_variable, limit=3000):
    url = f"https://api.bcra.gob.ar/estadisticas/v4.0/Monetarias/{id_variable}"
    offset, partes = 0, []
    while True:
        r = requests.get(url, params={"Limit": limit, "Offset": offset}).json()
        det = r["results"][0]["detalle"]
        if not det:
            break
        partes.append(pd.DataFrame(det))
        offset += limit
    df = pd.concat(partes).drop_duplicates("fecha").sort_values("fecha")
    df["fecha"] = pd.to_datetime(df["fecha"])
    return df.set_index("fecha")

reservas = get_serie(1)  # ~9000 observaciones desde 1996

策略 B — 按日期范围分块（处理较长序列时更快）

将总日期范围拆分为多个时间窗口（例如按年），并分别使用 Desde/Hasta 请求。若序列有超过 50.000 条观测值，或需要同时获取非常早期的数据，建议采用此方法。

import requests, pandas as pd
from datetime import date

def get_serie_por_chunks(id_variable, desde, hasta, ventana_dias=365):
    url = f"https://api.bcra.gob.ar/estadisticas/v4.0/Monetarias/{id_variable}"
    partes, d = [], pd.to_datetime(desde)
    fin = pd.to_datetime(hasta)
    while d <= fin:
        h = min(d + pd.Timedelta(days=ventana_dias - 1), fin)
        r = requests.get(url, params={"Desde": d.strftime("%Y-%m-%d"),
                                       "Hasta": h.strftime("%Y-%m-%d"),
                                       "Limit": 3000}).json()
        partes.append(pd.DataFrame(r["results"][0]["detalle"]))
        d = h + pd.Timedelta(days=1)
    df = pd.concat(partes).drop_duplicates("fecha").sort_values("fecha")
    df["fecha"] = pd.to_datetime(df["fecha"])
    return df.set_index("fecha")

base = get_serie_por_chunks(15, "1996-01-01", date.today().isoformat())

策略 C — 分页获取目录（重新列出所有变量）

def catalogo_completo(limit=3000):
    url = "https://api.bcra.gob.ar/estadisticas/v4.0/Monetarias"
    offset, todo = 0, []
    while True:
        r = requests.get(url, params={"Limit": limit, "Offset": offset}).json()
        batch = r["results"]
        todo += batch
        if len(batch) < limit:
            break
        offset += limit
    return pd.DataFrame(todo)

黄金法则

• 响应不包含 total → 始终检查 len(batch) < limit 或 detalle == []。
• 一次进行大批量调用（Limit=3000）比多次小批量调用更高效。
• API 未公开实施速率限制，但请注意礼貌：批量循环调用时，在请求之间添加 time.sleep(0.2)。

---

全国变量（最常用 ID）

完整列表见 VARIABLES.md（638 个全国序列）。以下为查询次数最多的 30 个：

ID	描述	Per.
1	国际储备（百万 USD）	D
4	零售汇率（$/USD）	D
5	参考批发汇率（$/USD）	D
7	私营银行 BADLAR 利率（% TNA）	D
8	私营银行 TM20 利率（% TNA）	D
11	BAIBAR 利率（% TNA）	D
12	30 天存款利率（% TNA）	D
13	活期账户透支利率（% TNA）	D
14	个人贷款利率（% TNA）	D
15	货币基础（百万 $）	D
16	货币流通量（百万 $）	D
17	公众持有的纸币和硬币（百万 $）	D
18	金融机构存款（百万 $）	D
19	私营部门贷款（百万 $）	D
26	货币政策利率（% TNA）	D
27	IPC 月变化率（%）	M
28	IPC 同比变化率（%）	M
29	REM - 未来 12 个月通胀率中位数（%）	M
30	CER（指数，基期 2.2.02=1）	D
31	UVA（$）	D
32	UVI（$）	D
40	ICL - 租赁合同指数（$）	D
1187	汇率区间 - 下限（$/USD）	D
1188	汇率区间 - 上限（$/USD）	D
1189	比索定期存款利率（% TNA）	D
1197	TIM 逾期利息利率（% TNA）	D
1232	M1（百万 $）	D
1233	M2（百万 $）	D
1234	M3（百万 $）	D

提示： API 重构时 ID 可能会变更。要确认变量当前的 ID，请使用目录端点。

目录中的类别

类别	全国数量	描述
主要变量	35	核心宏观指标（利率、汇率、储备、货币基础、CER、UVA、IPC）
每日货币报告	33	IMD 每日序列（境外项目、M1/M2/M3、BCRA 信贷）
Series.xlsm	154	货币基础和储备变动系数
存款利率	10	按币种和期限细分的存款利率
按持有人类型和用途划分的贷款	74	按用途划分的贷款（抵押贷款、汽车贷款、个人贷款）
按持有人类型划分的贷款	120	按币种划分的全国公共部门／私营部门贷款
按持有人类型划分的存款	212	按币种和期限划分的全国公共部门／私营部门存款

已排除（582 个省级／市级序列）： ID 322+ 按省份细分（布宜诺斯艾利斯、科尔多瓦、圣菲等）；此外还排除了未汇总为全国数据、但提及“省级政府”或“市级政府”的项目。

货币代码

代码	含义
ML	本币（阿根廷比索）
ME	外币（美元）
MEyML	本币 + 外币汇总
USD	美元（未转换）

序列类型

月末余额 · 余额 · 利率 · 每日流量 · 汇率 · 变化率 · 比率 · 指数 · 计价单位 · 利差 · 金额

---

技术注意事项

• 无需身份验证 — 无需 key 或 token。
• **分页上限：**每次调用 3000 条记录。
• **编码：**响应可能包含扩展字符（ISO-8859-1）——使用 response.encoding 或 pd.read_json(..., encoding="utf-8")。
• **日期格式：**ISO 8601（YYYY-MM-DD）。
• **SLA：**尽力而为，不作正式保证。

实用链接

• 官方文档
• BCRA API 目录
• 每日货币数据
• 方法论
• OpenAPI 规范
• 交互式文档