商品进口 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	支持的一个大写国家代码：AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP 和 USA。
`period`	否	查询·YYYY 或 YYYY-MM	省略此参数可获取最新已接受的完整发布，或传入一个精确期间。
`partner`	否	查询·ISO alpha-3	根据合约已接受，但当前测试版不会发布筛选后的合作伙伴总数。
`product`	否	查询·2、4 或 6 位数字	HS 商品代码。请将其与分类一并提供。
`classification`	否	查询·HSYYYY	《协调制度》的版本。请与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 是官方发布日期。

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

当前公开测试覆盖范围

AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP和USA的未筛选全国商品进口总额已公开。契约接受伙伴和产品筛选条件，但在筛选总额发布前会返回404。

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

返回所有经济数据操作.