货物进口 API

获取一个国家某个期间的货物进口总额。

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

端点与请求

REST 端点

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

请求示例

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

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

REST 发送 product 和 classification 作为独立的查询参数。MCP 将它们嵌套在一个 product 对象：

MCP 贸易筛选参数

{
  "country": "USA",
  "period": "2026-06",
  "partner": "CAN",
  "product": {
    "classification": "HS2022",
    "code": "27"
  }
}

参数

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

名称	必填	类型	含义
`country`	是	路径·ISO alpha-3	一个受支持的大写国家代码；请参阅此操作的覆盖列表。
`period`	否	查询·YYYY 或 YYYY-MM	省略此参数可获取已采纳的最新完整发布数据，也可传入一个具体期间。
`partner`	否	查询·ISO alpha-3	接口约定允许使用此参数，但当前测试版尚未发布按贸易伙伴筛选的总额。
`product`	否	查询·2、4 或 6 位数字	HS 商品代码。请与 classification 一并提供。
`classification`	否	查询·HSYYYY	Harmonized System 的版本。请与 product 一并提供。

响应

响应示例

{
  "country": "USA",
  "period": "2026-06",
  "flow": "import",
  "value": "275000000000",
  "currency": "USD",
  "coverage": "merchandise",
  "partner": null,
  "product": null,
  "released_on": "2026-08-04"
}

字段	类型	必填	含义
`country`	字符串	是	所请求的大写 ISO 三字母国家代码。
`period`	字符串	是	返回的官方观测期间。
`flow`	"export" 或 "import"	是	由路由确定的货物贸易方向。
`value`	十进制字符串	是	所选方向对应的货币金额。
`currency`	ISO 4217 字符串	是	货币金额所使用的货币。
`coverage`	"merchandise"	是	确认不包含服务贸易。
`partner`	ISO alpha-3 字符串或 null	否	若请求包含贸易伙伴筛选条件，则在此返回。对于公开的未筛选总额，此字段可为 null 或省略。
`product`	对象或 null	否	若请求包含 HS 分类和商品代码，则在此返回。对于公开的未筛选总额，此字段可为 null 或省略。
`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

未经筛选的全国货物进口总额数据覆盖的国家见下方列表。接口约定允许传入贸易伙伴和商品筛选条件，但在筛选后总额数据发布前，此类请求会返回 404。

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

返回所有经济数据操作。