世界银行数据 API

API由 Narwhal API 提供

Narwhal API 使用包含国家代码的 ID 读取年度世界发展指标，例如 wdi:ny.gdp.mktp.cd/idn 表示以现价美元计的印度尼西亚 GDP。先搜索指标，再使用同一个 API 密钥读取其定义、观测值或最新值。

按国家读取年度指标

使用 wdi:<indicator>/<iso3> 读取某国的 WDI 指标，须遵守下述许可限制。两部分均使用小写字母。国家部分为 ISO 3166-1 alpha-3 代码，例如印度尼西亚使用 idn。

WDI 序列为年度数据。响应保留指标的单位标签，观测值为十进制字符串。缺失年份会被省略，不会填补。序列不提供修订历史或历史版本。

搜索指标

使用 q 搜索目录，并以 source=wdi 限定结果来源。所有套餐均可使用搜索，搜索不会向来源发起请求。查询长度为 2 至 100 个字符；limit 允许 1 至 100 条结果，默认为 25。

搜索 WDI 指标
curl "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"
搜索响应
{
  "results": [
    {
      "id_template": "wdi:bg.gsr.nfsv.gd.zs/{country}",
      "source": "wdi",
      "title": "Trade in services (% of GDP)",
      "frequency": "annual",
      "unit_label": "Trade in services (% of GDP)"
    },
    {
      "id_template": "wdi:bm.klt.dinv.wd.gd.zs/{country}",
      "source": "wdi",
      "title": "Foreign direct investment, net outflows (% of GDP)",
      "frequency": "annual",
      "unit_label": "Foreign direct investment, net outflows (% of GDP)"
    }
  ],
  "next_cursor": "eyJhIjoid2RpOmJtLmtsdC5kaW52LndkLmdkLnpzIiwicSI6IjBhOTNhNWZiMmE1NzkzY2EifQ"
}

将结果中 id_template 的 {country} 替换为所需的国家代码。对应的 MCP 工具为 economics_search_catalogue。

读取序列

在 id 查询参数中传入完整 ID，包括其中的斜杠。先读取定义，检查标题、频率和单位标签。印度尼西亚 GDP 的来源单位标签为 GDP (current US$)。

读取印度尼西亚 GDP 元数据
curl "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"
部分定义字段
{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "title": "GDP (current US$), Indonesia",
  "country": "IDN",
  "frequency": "annual",
  "unit": "extended",
  "unit_label": "GDP (current US$)",
  "seasonal_adjustment": "not_stated",
  "first_period": "1967",
  "last_period": "2025"
}

单独读取观测值。年度 start 和 end 边界使用 YYYY，并包含起止年份。观测值每页最多支持 1,000 条记录。在 MCP 中，使用 economics_read_catalogue_series 读取定义，使用 economics_read_catalogue_observations 读取数值。

读取 GDP 观测值
curl "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"
Pro 请求的部分观测值响应字段
{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "observations": [
    {"period": "1967", "value": "5667756627.92093"},
    {"period": "1968", "value": "7076465299.81141"},
    {"period": "1969", "value": "8337423312.88344"}
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

批量读取多个国家的数据

在 ids 参数中传入 1 至 50 个不同的序列 ID，以逗号分隔，即可读取其最新观测值。保持指标部分不变，仅修改国家代码，即可请求不同国家的同一指标。

读取印度尼西亚和日本的最新 GDP
curl "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,wdi:ny.gdp.mktp.cd/jpn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

每返回一个序列计一次调用，批量请求一次性计费。比较数值时，请检查每条观测记录的 period。对应的 MCP 工具为 economics_read_catalogue_latest_batch。

查看各套餐限额

未缓存数据的获取额度按账户、按 UTC 日计算。仅当缓存中没有该序列时才需要获取；每日额度用尽后，仍可读取已缓存的序列。

限制免费BasicPro
每日未缓存数据获取次数101001,000
历史数据范围最近 12 个月最近 5 年完整历史数据
年度观测最低保留数量最新 5 条最新 5 条最新 5 条

年度数据的可访问范围为套餐历史范围或最新 5 条观测记录，取覆盖更多记录的一项。请求范围完全早于允许的历史数据范围时，返回 403 plan_upgrade_required。

额度用尽后，如果请求需要获取数据，则返回 429 fetch_limit_reached，并通过 Retry-After 指示等待至 00:00 UTC。账户达到上限但有保留副本时，会免费返回该副本。

保留许可和来源署名

目录索引了采用 CC BY 4.0 许可的 1,489 个世界银行 WDI 指标。另有九个采用其他许可的指标，按 ID 请求时会被拒绝，不予提供。

每个序列响应均包含 attribution 和 licence_url。使用数据时，请一并保留世界银行的来源署名和 CC BY 4.0 许可。响应还包含 fetched_at，便于在记录观测期间的同时，记录 Narwhal 获取该序列的时间。

如何按国家代码获取世界银行指标？

搜索指标，获取其 id_template，再将 {country} 替换为小写的 ISO 3166-1 alpha-3 代码。例如，印度尼西亚的 GDP 序列为 wdi:ny.gdp.mktp.cd/idn。

读取定义或观测值时，将完整 ID 作为 id 参数传入。存储或比较序列时，请保留指标所附的国家代码。

世界银行数据的时效性如何？

WDI 观测值为年度数据，Narwhal 对序列的缓存时长为 24 小时至 7 天。缓存未命中时，Narwhal 会在套餐每日额度内从来源获取数据。

请分别检查观测记录的 period 和 fetched_at：前者标明数据对应的年份，后者记录获取时间。如果无法访问来源，可返回保留的副本，并标记 stale: true。

发布于。

后续步骤