Stats Nz

@pipeworx/stats-nz

新西兰官方统计数据（Aotearoa Data Explorer）——按关键词搜索 Stats NZ 发布的 911 个数据集，并提取其观测数据，涵盖 2013、2018 和 2023 年人口普查、LEED 收入、企业人口统计、人口估算与预测、家庭支出、矫正及司法数据。

属于 Pipeworx——一个将 AI Agent 接入 1819+ 个实时数据源的 MCP 网关。这是一项独立的非官方集成，与上游提供方无关联、未经其认可，也非由其发布。

工具

• statsnz_datasets({ query, limit, offset }) — 无需密钥。按关键词搜索全部 911 个数据集；返回数据集 ID、完整标题、描述、机构和版本。
• statsnz_observations({ dataset, key, agency, version, startPeriod, endPeriod, lastNObservations, _apiKey }) — 返回带有维度标签的期间/数值对。范围过宽且未筛选的查询会自动缩小到总计，并在 narrowed 中标记（见“注意事项”）。
• statsnz_resources({ dataset, agency, version, includeCodes, maxCodesPerList, _apiKey }) — 按键顺序列出维度、时间维度、度量，以及将 1.2.Q 这类键转换为可读内容所需的代码列表。

身份验证

平台密钥 PLATFORM_STATSNZ_KEY（自 2026-09-18 起存储在加密密钥库中），也可通过 ?_apiKey= 使用自带密钥覆盖；密钥会作为 Ocp-Apim-Subscription-Key 请求头发送给上游。调用方无需自己的密钥。可在 https://portal.apis.stats.govt.nz/ 免费订阅——注册后订阅 Aotearoa Data Explorer API 产品。

statsnz_datasets 也完全支持无密钥调用。

数据源

• https://api.data.stats.govt.nz/rest/dataflow/all/all/latest — 数据集目录（无需密钥）。
• https://api.data.stats.govt.nz/rest/data/{agency},{dataset},{version}/{key} — 观测数据（需密钥）。
• https://api.data.stats.govt.nz/rest/datastructure/{agency}/{dataset}/{version}?references=all — 结构和代码列表（需密钥）。

注意事项

• 无论请求什么，目录现在都返回 SDMX-ML。 /rest/dataflow/all/all/latest 在 2026-09-18 之前返回 SDMX-JSON，现在对尝试过的所有 Accept 标头——structure+json;version=1.0、裸 application/json、 structure+json;version=2.0——均返回 application/vnd.sdmx.structure+xml; version=2.1，无论是否指定键。对此调用 res.json() 会抛出 Unexpected token '<', "<?xml vers"，结果被归类为 upstream_down，看起来像服务中断，而不是格式变更。该工具包会解析 XML。这是特定于此端点的：/rest/datastructure/… 仍会返回 structure+JSON，因此不要也转换那个端点。
• flowRef 中的逗号必须保留为字面字符——编码后会悄无声息地返回零结果。 数据路径为 /rest/data/{agency},{dataset},{version}/{key}。他们的 Azure APIM 不会对路径段进行百分号解码，未匹配的路由会落入一个处理程序：没有密钥时返回 401「missing subscription key」，有密钥时则返回空但有效的 200。2026-09-18 测得： /rest/data/STATSNZ,AGR_AGR_001,1.0/all?lastNObservations=1 → 200，含 80 条观测；同一 URL 将逗号替换为 %2C → 401。正是对该路径段使用 encodeURIComponent，导致 statsnz_observations 针对完全正常的数据集返回 count: 0。/rest/dataflow/%61ll/all/latest → 401，这说明问题出在他们的路由方式，而非仅此路径。
• statsnz_observations 返回零条结果总有原因，而无效 ID 会报错。 由于在此网关上，未知数据集、格式错误的路径和确实为空的查询无法通过状态码区分，该工具会在调用数据端点之前，先用不需要密钥的目录验证数据集 ID（每个隔离区缓存 30 分钟）。未知 ID 会抛出类似 404 的错误，并列出相近匹配项；若 ID 存在但没有返回结果，则会在 empty_reason 中说明具体情况——完全没有结构（路由成功但无法解读）、维度 key 筛掉了所有结果、时间段窗口内没有数据，或确实存在上游数据缺口。
• 宽泛普查表的未筛选查询太大，无法直接返回，因此该工具包会缩小范围并说明原因。 2026-10-16 时，CEN23_HAD_020 使用键 all 会产生约 208MB 的 SDMX-JSON（没有 Content-Length，也没有时间维度供 lastNObservations 缩小结果），超过该工具包 16MB 的流式处理上限；在 48 小时内 44 次外部 statsnz_observations 调用中，这种情况占了 24 次。未筛选查询触发上限时，该工具包会读取数据集结构，将地理维度（然后是剩余维度中范围最广的维度，当未固定的笛卡尔积超过 250k 个单元时）固定到 Stats NZ 标为「Total …」的 ROOT 代码——绝不会固定到「Total stated …」小计；随后重新查询并返回该切片，同时提供 requested_key: "all" 和一个 narrowed 对象，列出每个固定项以及如何请求细分结果。CEN23_HAD_020 会以键 .9999....（Total - New Zealand by regional council）返回，共 16,920 行。不会缩小调用方提供的 key；若其范围过宽，或数据集没有可用于固定的 Total 代码，则会以 user_error 失败，并在错误中列出维度和示例代码。
• 这里的 401 不表示「凭据错误」。 由于未匹配的路由也会返回 401，因此无法仅凭状态码区分格式错误的路径和缺少密钥。该工具包的 401 错误消息会明确说明这两种可能性。
• 观测结果是扁平的，而不是按序列键组织的。 dataSets[0].observations 是一个映射，格式为 "0:3" → [value, …]，并且不存在 dataSets[0].series。只读取 series（该工具包最初就是这样做的），会导致正常的 200 响应也返回零条观测。该工具包会同时映射这两种布局，以及数据集级维度。
• lastNObservations 会从观测键中移除被折叠的维度，而且它不一定是时间轴。 在 AGR_AGR_001 上使用 lastNObservations=1 时，键只有 2 部分，而声明的维度有 3 个——响应中根本没有年份，因此无法从行中判断年份。在 INC_INC_001 上，被折叠的维度是 MEASURE_INC_INC_001，这是一个度量轴，涉及 35,610 行。该工具包会返回 collapsed_dimensions 和一条说明，而不会返回看起来像是标签完整的行。
• startPeriod/endPeriod 仅对已声明的时间维度生效，而 Stats NZ 大多不声明时间维度。 statsnz_resources 对 AGR_AGR_001 报告 time_dimension: []，而数据消息中的 role 字段只会回显每个维度自身的 ID，因此没有可用的时间标记：对这个服务器来说，名为 YEAR_* 的维度并不是时间维度。因此，该工具包会检查 SDMX 标准 TIME_PERIOD ID；对于其他维度，则会告知调用方通过 key 参数固定该维度，并指出其段位置，提供一个可用的键示例，例如 ..<YEAR_AGR_AGR_001>。之前的说明无条件建议使用 startPeriod/endPeriod，但在度量轴上这种建议行不通（fleet #2244）。
• Accept: application/vnd.sdmx.data+json;version=1.0.0 会返回 406。 他们的服务器列出的可接受格式是 genericdata+xml 2.1 和 data+json 2.0。纯 application/json 会返回 SDMX-JSON 1.0，也是该工具包实际请求的格式。
• 主机名错误看起来像服务中断。 较早文档中记录的主机 api.stats.govt.nz 会在所有路径（包括根路径）上从其 Azure Application Gateway 返回 HTTP 502。当服务实际已经迁移时，502 看起来会像是「他们的服务挂了」。当前主机是 api.data.stats.govt.nz。不要把该工具包「修正」回旧主机名。
• 裸 SDMX 资源路径会返回 404。 /rest/dataflow 会返回 404 Resource not found；只有完整的 /rest/dataflow/{agency}/{resource}/{version} 形式才会正常响应。
• 911 个数据流中，只有 341 个带有 description；其余只有标题，因此关键词筛选依赖较长的正式标题（「Earnings for people in paid employment」，而不是「wages」）。
• 该目录不包含 CPI、GDP 和商品贸易数据。 2026-09-17 测得：911 个数据流中，没有一个提到「price」「consumer」或「trade」；其中 705 个是普查表。将该工具包描述为覆盖 CPI，会让所有通胀问题都被错误地路由到无法回答这些问题的数据源。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "stats-nz": {
      "url": "https://gateway.pipeworx.io/stats-nz/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/stats-nz/mcp 上的 tools/list 会返回上表中的工具，以及共享的 Pipeworx 元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 以及网关范围内的其他工具。因此，你看到的工具数量会多于此表中的数量：目前，单个工具包端点除了该工具包自己的工具外，还会列出大约 30 个共享工具。连接的 initialize 响应会说明确切范围，是当天情况的权威依据。

这是有意为之，并非意外的多路复用。元工具让范围受限的连接也能回答本工具包未涵盖的问题——通过 ask_pipeworx 跨整个目录路由——而无需添加第二个 MCP 服务。目前无法挂载不包含这些工具的工具包端点；如果额外的架构定义占用的上下文超过了路由带来的价值，请连接一次完整网关，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不仅仅是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一网关和相同的 1819+ 个数据源。唯一的区别是哪些工具包的工具会被直接列出；无论连接哪个 URL，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/statsnz_datasets \
  -H 'Content-Type: application/json' \
  -d '{"query":"household income","limit":5}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/statsnz_datasets。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需往返网关：

{
  "mcpServers": {
    "stats-nz": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-stats-nz"]
    }
  }
}

或者直接运行它以确认服务已启动：

npx -y @pipeworx/mcp-stats-nz

它通过 stdin/stdout 使用 MCP 通信，并仅针对此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接所添加的任何共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗英语提问，而不是直接调用工具——此方式既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Stats Nz data" })

网关会选择合适的工具并自动填入参数。

更多内容

• 文档和指南
• pipeworx.io

许可证

MIT