消费者价格指数历史 API

获取一个国家当前已接受的居民消费价格指数时间序列。

economics_get_cpi_history 可通过 REST 和 economics_get_cpi_history MCP 工具。两者返回相同的数据结构，并消耗相同的月度配额。

端点与请求

REST 端点

GET /v1/economics/{country}/cpi/observations

请求示例

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/cpi/observations?start=2026-07&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用工具 economics_get_cpi_history 使用下面对应的参数。

参数

此操作接受的期间格式是 YYYY-MM.

名称	必填	类型	含义
`country`	是	路径·ISO alpha-3	支持的一个大写国家代码：AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP 和 USA。
`start`	否	查询·YYYY-MM	包含的首个观测期。
`end`	否	查询·YYYY-MM	包含的最后观测期。
`limit`	否	查询·整数，1–1000	最多返回的观测值数量。默认为 100。
`cursor`	否	查询·不透明字符串	上一页返回的next_cursor。

响应

响应示例

{
  "observations": [
    {
      "country": "USA",
      "measure": "cpi",
      "value": "333.918",
      "unit": "INDEX",
      "transformation": "",
      "period": "2026-07"
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T16:00:00Z"
}

字段	类型	必填	含义
`observations`	数组	是	按从最早到最近的顺序排列已接受的观测值。缺失的来源数值会被省略，绝不会填补。
`observations[].country`	字符串	是	所请求的大写 ISO 三字母国家代码。
`observations[].measure`	字符串	是	该观测值所代表的规范指标。
`observations[].period`	字符串	是	观测值所代表的官方月份或季度。
`observations[].value`	十进制数字符串	是	不经过二进制浮点转换的已接受来源值。
`observations[].unit`	字符串	是	该指标的来源单位或货币代码。
`observations[].transformation`	字符串	是	指标变换；若为水平值则为空字符串。
`next_cursor`	字符串或 null	否	将此值原样作为 cursor 传入，以读取下一页。
`as_of`	RFC 3339 时间戳	否	Narwhal接受当前存储序列快照的时间。

错误与配额

400 invalid_query — 国家、期间或筛选格式无效。
401 invalid_api_key — Bearer 密钥缺失或被拒绝。
404 series_not_found — 没有已批准的观测值符合请求。
429 rate_limit_exceeded — 已达到网络或账户短窗口限制；请在此时间后重试 Retry-After.
429 quota_exhausted — 账户已达到月度额度。
503 economics_unavailable — Narwhal 无法安全提供已接受的发布版本。

只有成功的数据响应才会消耗配额。参见所有错误、请求头和重试规则.

新鲜度

此路由返回Narwhal截至指定时间当前已接受的序列 as_of。这是按当前版本提供的历史数据，不是对过去每次发布版本的重建。

官方来源可能较为稀疏，且提供的历史深度各不相同。Narwhal 会省略缺失观测值，而不是进行插值或向前延续数值。

读取源检查、验证、已存储发布版本和失败检查的工作方式.

当前公开测试覆盖范围

AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP 和 USA 的官方历史数据已公开；最早可用期间因来源而异。

印度尼西亚、区域路由和 Commodities 尚未公开。FX 可通过单独的 FX API.

返回所有经济数据操作.