货物贸易历史数据 API

获取一个国家当前已接受的货物贸易时间序列。

economics_get_trade_history 可通过 REST 和 economics_get_trade_history MCP 工具访问。两者返回相同的数据结构，并共用月度配额。

端点与请求

REST 端点

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

请求示例

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

MCP 使用工具 economics_get_trade_history ，并传入下方对应的参数。

参数

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

名称	必填	类型	含义
`country`	是	路径·ISO alpha-3	一个受支持的大写国家代码；请参阅此操作的覆盖列表。
`start`	否	查询·YYYY-MM	起始观测期（包含该期）。
`end`	否	查询·YYYY-MM	结束观测期（包含该期）。
`limit`	否	查询·整数，1–1000	最多返回的观测值数量。默认为 100。
`cursor`	否	查询·不透明字符串	上一页返回的next_cursor。

响应

响应示例

{
  "observations": [
    {
      "country": "USA",
      "measure": "trade_exports",
      "value": "189000000000",
      "unit": "USD",
      "transformation": "",
      "period": "2026-06"
    }
  ],
  "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 会省略缺失观测值，而不是进行插值或向前延续数值。

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

当前公开测试覆盖范围

35 国家

AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, SAU, SGP, SVN, SWE, USA

可用的官方历史数据遵循此操作的国家覆盖范围。首个可用时期因来源而异。

印度尼西亚和地区级经济数据路由不对外开放。日频外汇数据可通过以下 API 获取：外汇 API。

返回所有经济数据操作。