货物贸易 API

获取某个期间的出口额、进口额以及准确的货物贸易差额。

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

端点与请求

REST 端点

GET /v1/economics/{country}/trade

请求示例

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

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

参数

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

名称	必填	类型	含义
`country`	是	路径·ISO alpha-3	一个受支持的大写国家代码；请参阅此操作的覆盖列表。
`period`	否	查询·YYYY 或 YYYY-MM	省略此参数可获取已采纳的最新完整发布数据，也可传入一个具体期间。

响应

响应示例

{
  "country": "USA",
  "period": "2026-06",
  "exports": "189000000000",
  "imports": "275000000000",
  "balance": "-86000000000",
  "currency": "USD",
  "coverage": "merchandise",
  "released_on": "2026-08-04"
}

字段	类型	必填	含义
`country`	字符串	是	所请求的大写 ISO 三字母国家代码。
`period`	字符串	是	返回的官方观测期间。
`exports`	非负十进制字符串	是	货物出口总额。
`imports`	非负十进制字符串	是	货物进口总额。
`balance`	十进制字符串	是	精确的出口额减进口额；结果可能为负。
`currency`	ISO 4217 字符串	是	三个货币值所使用的货币。
`coverage`	"merchandise"	是	确认不包含服务贸易。
`released_on`	日期	是	官方发布日期，而不是 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 无法安全提供已接受的发布版本。

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

数据时效性

省略 period 返回 Narwhal 最新存储的已接受发布版本。API 调用读取 Narwhal 数据库，不会实时调用官方发布机构。

released_on 是官方发布日期。

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

当前公开测试覆盖范围

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。

返回所有经济数据操作。