任意序列 API 参考

搜索世界银行和加拿大统计局的目录，并按 ID 读取序列，了解套餐限制、缓存和错误处理。

通过四项操作，可按 ID 访问世界银行和加拿大统计局的数据序列。你可以搜索目录、读取序列定义或观测值，也可以一次获取最多 50 个序列的最新值。

REST 和 MCP 共用数据结构、密钥和配额。按 ID 实时读取的世界银行和加拿大统计局序列没有修订历史。Pro 密钥可通过支持的各国历史数据路由和按 ID 查询序列的路由读取历史版本，详见 Economics API 参考文档中的“按 ID 查询序列历史”部分。

操作

操作	REST 路径	MCP 工具	返回内容
搜索目录	`GET /v1/economics/catalogue`	`economics_search_catalogue`	与查询匹配的序列和数据表。
读取序列	`GET /v1/economics/catalogue/series`	`economics_read_catalogue_series`	一个序列的定义。
读取观测值	`GET /v1/economics/catalogue/series/observations`	`economics_read_catalogue_observations`	一个序列的数值，按时间从早到晚排列。
最新数值	`GET /v1/economics/catalogue/latest`	`economics_read_catalogue_latest_batch`	1 至 50 个序列各自的最新值。

数据源键可能包含斜杠，因此请通过 id 查询参数传入序列 ID。

每个请求都需要 Bearer 密钥。身份验证

序列 ID

序列 ID 使用小写格式 <source>:<key>。

来源	格式	示例	频率
世界银行，世界发展指标	`wdi:<indicator>/<iso3>`	`wdi:ny.gdp.mktp.cd/idn`	年度
加拿大统计局	`statcan:v<vector>`	`statcan:v41690973`	月度、季度、年度

世界银行搜索结果包含 id_template，例如 wdi:ny.gdp.mktp.cd/{country}。请将 {country} 替换为小写的 ISO 3166-1 alpha-3 国家代码。索引仅收录依据 CC BY 4.0 发布的指标；其他指标返回 404 not_found。

加拿大统计局的搜索结果对应数据表。每条结果都包含 id_template，其值为 statcan:v{vector}，以及带有表号的标题，例如表 10-10-0106-01。请在加拿大统计局网站上该数据表的页面中找到序列的向量编号，并填入模板。目前没有可列出某张表所有向量的路由。

加拿大统计局中频率为每日、每周、多年、财政年度或财政季度的向量返回 404 not_found。

搜索目录

搜索使用 Narwhal 的索引，不请求数据源。所有套餐均可使用，每次搜索计为一次调用。

q：搜索文本，长度为 2 至 100 个字符。
source：wdi 或 statcan。
country：大写的 ISO alpha-3 代码。
frequency：daily、monthly、quarterly 或 annual。
limit：1 至 100；默认为 25。
cursor：上一页的 next_cursor。

每条结果都包含 source、title，以及 id 或 id_template 中的一个，且仅包含其中一个。如果相关信息已知，还会包含 frequency、unit_label、country、first_period 和 last_period。最后一页的 next_cursor 为 null。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  --header "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"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=consumer%20price&source=statcan&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Consumer Price Index (CPI) statistics, alternative measures, unadjusted and seasonally adjusted, Bank of Canada (Statistics Canada table 10-10-0106-01)",
      "frequency": "monthly",
      "country": "CAN",
      "first_period": "1979-11",
      "last_period": "2026-09"
    },
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Inter-city indexes of price differentials of consumer goods and services, annual (Statistics Canada table 18-10-0003-01)",
      "frequency": "annual",
      "country": "CAN",
      "first_period": "2000",
      "last_period": "2019"
    }
  ],
  "next_cursor": "eyJhIjoic3RhdGNhbjp0MTgxMDAwMDMiLCJxIjoiNGQxYjFkOWQwN2FlNTBhMiJ9"
}

读取序列

返回一个序列的定义，包括起始和结束期间。不包含观测值。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "first_period": "1967",
  "last_period": "2025"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "first_period": "1914-01",
  "last_period": "2026-09"
}

读取观测值

返回一个序列的数值及其定义，数值按时间从早到晚排列。

id：序列 ID。
start 和 end：包含边界的起止期间，使用序列的期间格式，即 YYYY、YYYY-MM 或 YYYY-Qn。两个边界必须使用相同格式。
limit：1 至 1000；默认为 100。
cursor：上一页的 next_cursor。

Narwhal 先应用 start 和 end，再应用套餐的历史数据范围限制。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "observations": [
    {
      "period": "1967",
      "value": "5667756627.92093"
    },
    {
      "period": "1968",
      "value": "7076465299.81141"
    },
    {
      "period": "1969",
      "value": "8337423312.88344"
    }
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=statcan:v41690973&start=2026-07&limit=3" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "observations": [
    {
      "period": "2026-07",
      "value": "169.9",
      "released_on": "2026-08-17"
    },
    {
      "period": "2026-08",
      "value": "169.8",
      "released_on": "2026-09-14"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19"
    }
  ],
  "next_cursor": null
}

数据源未发布数值的年份或月份会被省略，绝不补值。每条观测记录都包含 period 和以十进制字符串表示的 value；数据源提供 released_on 和 status 时，也会包含这两个字段。

一次请求获取最新值

通过以逗号分隔的 ids 列表发送 1 至 50 个互不重复的 ID。响应返回每个序列的最新观测值及其定义。missing 列表包含数据源无法识别或没有观测值的 ID。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "observations": [
    {
      "period": "2025",
      "value": "1445642584163.81",
      "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",
      "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
      "licence_url": "https://creativecommons.org/licenses/by/4.0/",
      "fetched_at": "2026-10-27T03:37:35Z"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19",
      "id": "statcan:v41690973",
      "title": "Canada;All-items",
      "frequency": "monthly",
      "unit": "extended",
      "unit_label": "2002=100",
      "seasonal_adjustment": "not_stated",
      "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
      "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
      "fetched_at": "2026-10-27T12:30:59Z"
    }
  ],
  "missing": []
}

批量请求一次性计入配额，每个返回的序列计为一次调用。

套餐限制

所有套餐均可使用这四项操作。每个套餐都设有未缓存数据的每日源站获取次数上限和历史数据范围。

限制	免费	Basic	Pro
每个 UTC 日的未缓存数据获取次数	10	100	1,000
历史数据范围	最近 12 个月	最近 5 年	完整历史数据

每个套餐都至少包含年度序列的最新 5 条观测值和季度序列的最新 4 条观测值，即使这些观测值超出了套餐的历史数据范围。Narwhal 会在历史数据范围与这些最新观测值之间，采用包含观测值更多的一项。

请求范围完全早于套餐历史数据范围时，返回 403 plan_upgrade_required。对于年度和季度序列，Narwhal 会先加载序列，再执行此检查，以便应用最低观测值数量规则。

数据实时提供，无延迟。

调用、缓存与过期数据

每次成功的搜索、序列定义、观测值或单序列最新值请求均计为一次调用。批量请求中，每个返回的序列计为一次调用。

返回过期数据的响应，以及 400、404 和 503 响应，均不计入配额。

Narwhal 从数据源读取序列后会将其缓存。已缓存的序列始终直接返回响应，不消耗源站获取次数；只有未缓存的序列才会消耗获取次数。世界银行序列的缓存时间为 24 小时至 7 天。加拿大统计局序列的缓存时间分别为：月度序列 6 小时、季度序列 12 小时、年度序列 24 小时。

账户用完每日获取次数后，需要再次从数据源获取数据的请求会返回 429 fetch_limit_reached。响应的 Retry-After 标头给出距离 00:00 UTC 的剩余时间。如果仍有该序列的旧副本可用，Narwhal 会返回该副本，并附上 stale: true，不计入配额。

如果数据源不可用，且没有缓存副本，Narwhal 会返回 503 upstream_busy，并附上 Retry-After。数据源的限流不会以 429 响应透传。

字段

序列响应包含以下字段。

字段	含义
`id`	序列 ID。
`title`	数据源提供的序列标题。
`country`	ISO alpha-3 代码，仅在数据源提供时包含。
`frequency`	`daily`、`monthly`、`quarterly` 或 `annual`。
`unit`	始终为 `extended`。
`unit_label`	单位，保留数据源的原文。世界银行序列使用指标名称，例如 `GDP (current US$)`。
`scale, currency`	仅在数据源明确说明时包含。Narwhal 绝不根据 `scale` 对数值进行换算。
`seasonal_adjustment`	`seasonally_adjusted`、`not_seasonally_adjusted`、`not_applicable` 或 `not_stated`。
`base_period`	指数基期，仅在数据源明确说明时包含。
`attribution, licence_url`	必须保留的数据来源署名，以及数据源许可证链接。
`fetched_at`	Narwhal 读取数据源的时间。
`stale`	仅当数据源无法访问，且 Narwhal 返回其最后保存的副本时，才为 `true`。
`first_period, last_period`	起始和结束期间，包含在序列定义中。

错误

状态与代码	含义
`400 invalid_series_id`	ID 的数据源格式无效。详细信息会指明：世界银行使用 `<indicator>/<iso3 country>`，加拿大统计局使用 `v<vector number>`。
`400 invalid_query`	参数无效。例如，批量请求包含超过 50 个 ID、ID 重复，或 `start` 和 `end` 使用不同的期间格式。
`403 plan_upgrade_required`	请求范围的结束时间早于套餐允许的历史数据起点。
`404 not_found`	数据源或索引无法识别该序列，或该序列的频率不受支持。Narwhal 会将此结果缓存 24 小时。
`404 not_covered`	ID 指定了不受支持的数据源。
`429 fetch_limit_reached`	账户已用完当前 UTC 日的获取配额。`Retry-After` 给出距离 00:00 UTC 的剩余时间。
`503 upstream_busy`	数据源不可用，且没有缓存副本。请等待 `Retry-After` 指定的时间后重试。

错误采用统一的问题响应结构，并包含 request_id。错误与配额

世界银行数据 API · 加拿大统计局数据 API

来源署名

每个响应都在 attribution 中注明机构名称，并在 licence_url 中提供其许可证链接。世界银行指标采用 CC BY 4.0，加拿大统计局数据采用加拿大开放政府许可证。Narwhal 对数值进行标准化处理；无论在哪里展示这些数值，都应保留来源署名。

经济数据 API 参考 · MCP