# China NBS Statistics | GDP & Economic Data (`happyfirst/datanbs-mcp-worker`) Actor

Search Chinese national statistics, browse monthly, quarterly and annual catalogs, and retrieve indicator metadata and time series from data.stats.gov.cn. Unofficial tool.中国国家统计数据，数据源自中国国家统计局。

- **URL**: https://apify.com/happyfirst/datanbs-mcp-worker.md
- **Developed by:** [happyfirst](https://apify.com/happyfirst) (community)
- **Stats:** 2 total users, 1 monthly users, 85.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## China NBS Statistics | 中国国家数据

Search and retrieve China's national statistics from **data.stats.gov.cn**. This Actor supports dataset searches, monthly/quarterly/annual catalog browsing, indicator metadata, and nationwide statistical time series. It is an **unofficial tool**, not affiliated with or endorsed by the National Bureau of Statistics of China.

查询中国国家统计局“国家数据”的公开数据：搜索指标和数据集、浏览全国月度/季度/年度目录、获取指标 UUID 和单位、查询全国统计时间序列。本工具非国家统计局官方产品。

### Quick start / 快速开始

Run this input to search GDP:

```json
{
  "action": "search",
  "search": "国内生产总值",
  "pageSize": 5,
  "maxResults": 20
}
```

Open **Dataset → Statistics** to view results. The **Identifiers** view shows IDs needed for follow-up queries. JSON export includes each row's original upstream metadata in `raw`. CSV/Excel exports are available through Apify.

运行后在 Dataset 中查看统计结果；Identifiers 视图提供后续查询所需编号。JSON 导出保留原始元数据；可通过 Apify 导出 CSV 或 Excel。

### Operations / 查询方式

| action | Purpose | Required inputs |
| --- | --- | --- |
| `search` | Search datasets and indicator observations / 搜索数据 | `search` |
| `catalog` | Browse one catalog level / 浏览一层目录 | `code` (`1` monthly, `2` quarterly, `3` annual) |
| `indicators` | List indicator UUIDs, units, notes / 指标列表 | `cid` |
| `statistics` | Retrieve nationwide time series / 全国统计数值 | `cid`, `indicatorIds`, `dts`, `rootId` |

Each run performs one operation and one upstream request. There is no automatic pagination, recursive catalog traversal, or automatic choice of a GDP series. Chinese keywords work best. `search` defaults to page 1 and page size 5 (maximum 10). Upstream may return several indicator rows per dataset, so page size is not necessarily the number of output rows.

每次运行执行一项查询。搜索结果可能同时包含累计值、当季值、增长速度等不同口径，请按指标名称和单位选择。`maxResults` 限制保存条数，不会自动抓取更多页。

#### Retrieve statistics / 查询时间序列

1. Run `search` and copy a dataset `cid`.
2. Run `indicators` with that `cid`, and copy the desired `indicatorId`.
3. Run `catalog` with the matching `code` and no `pid`; copy the root `nodeId` as `rootId`.
4. Run `statistics` with those IDs and a matching time range.

Catalog example:

```json
{"action":"catalog","code":"2"}
```

Quarterly GDP indicator example:

```json
{"action":"indicators","cid":"28d936104e304aa191e338eb82b6dc09"}
```

Example of cumulative GDP for the first two quarters of 2026 (IDs verified on September 9, 2026; obtain fresh IDs if the upstream catalog changes):

```json
{
  "action": "statistics",
  "cid": "28d936104e304aa191e338eb82b6dc09",
  "indicatorIds": ["8c5fab362d124fa7b91af833b3bd7397"],
  "dts": ["202601SS-202602SS"],
  "rootId": "a94b8b7365a94874968cabbe392cf679",
  "maxResults": 100
}
```

Monthly ranges use `MM`, for example `202601MM-202607MM`. Quarterly ranges use `SS`, for example `202601SS-202602SS`. Use time codes supported by the selected dataset. Statistics queries accept at most 10 indicator IDs and 5 time ranges. Region is fixed to nationwide (`000000000000`).

### Output / 输出

| Field | Meaning |
| --- | --- |
| `action` | Executed operation |
| `name` | Upstream indicator or catalog display name |
| `cid` | Dataset ID, when available |
| `indicatorId` | Indicator UUID; not a catalog node ID |
| `nodeId` | Catalog node ID, for catalog results |
| `period`, `periodName` | Time code and display label |
| `value` | Original upstream value; strings and nulls are preserved |
| `unit` | Upstream unit if supplied as a separate field; otherwise null (search titles may contain units) |
| `region` | Region name, when supplied |
| `sourceUrl`, `retrievedAt` | Source homepage and retrieval timestamp |
| `raw` | Original metadata for this record |

A statistics dataset item represents **one indicator in one reporting period**. Search, catalog, and indicator-list items each represent one returned row. We do not reinterpret cumulative values as quarterly values, infer units from names, or replace missing values with zero. The source link identifies the official website, not a deep link to a specific table.

One run saves at most `maxResults` records (default 100, maximum 1000). `OUTPUT` in the default key-value store summarizes the upstream row count, selected count, stored count, truncation, and dataset ID. It does not expose additional unsaved records. Results may be fewer if a platform spending limit is reached. An empty query saves no dataset items.

### Pricing / 计费口径

Consult this Actor's current Pricing tab for actual charges. If per-result pricing is enabled, **one result means one saved dataset row**, as defined above, not one whole query or one dataset. A query returning 2 periods for 3 indicators may create 6 results. Any enabled Actor-start charge is separate and can apply even when a query fails or is empty. No custom charging event is emitted by this code; the default dataset-item event is handled by Apify.

计费以平台 Pricing 页面为准。若启用按结果计费，统计查询按保存的“指标 × 报告期”记录数计费；搜索、目录、指标列表按实际保存行数计费。空结果和错误不会创建结果记录，但平台设置的启动费用仍可能产生。

### Limits and errors / 限制与错误

- Nationwide data only; no provincial/city comparison, forecasting, or seasonal adjustment performed by this Actor.
- No NBS API key or Cloudflare Worker credentials required. Requests go directly to the official data endpoint.
- Upstream requests time out after 20 seconds and responses are limited to 5 MiB. Narrow the time range or indicator selection if needed.
- Invalid input, HTTP failures, non-JSON challenge pages, upstream business errors, and unexpected data structures fail the run. Details are written to the `ERROR` key-value record and run status.
- Availability, catalog IDs, published values, and upstream response formats can change. A successful search on another platform does not guarantee that Apify's network can reach the source.
- No proxy or browser challenge bypass is included. If access is restricted, report the error through this Actor's Issues tab.

### API and MCP

Use Apify Console's generated API examples to run this Actor with the JSON inputs above. The Actor can also be invoked through Apify's MCP integration. It is a task that runs and exits; it does not host a persistent `/mcp` endpoint or use Standby mode. The repository's Cloudflare Worker separately retains its Streamable HTTP `/mcp` service.

# Actor input Schema

## `action` (type: `string`):

Run one operation. Search first to discover CID; get indicator and root IDs before querying statistics.

## `search` (type: `string`):

Required for search. Use a short Chinese keyword, for example 国内生产总值 or 居民消费价格指数.

## `pagenum` (type: `integer`):

Used by search only. No automatic pagination.

## `pageSize` (type: `integer`):

Used by search only. Upstream may return multiple indicator rows per dataset.

## `code` (type: `string`):

Used by catalog only; omit pid to get its root node.

## `pid` (type: `string`):

Optional for catalog. Use a returned nodeId to browse one level below it.

## `cid` (type: `string`):

Required for indicators and statistics. Obtain it from search results.

## `dt` (type: `string`):

Optional upstream filter for indicators only.

## `name` (type: `string`):

Optional upstream filter for indicators only.

## `indicatorIds` (type: `array`):

Required for statistics, 1-10 UUIDs from indicators output (indicatorId).

## `dts` (type: `array`):

Required for statistics, 1-5 ranges. Monthly: 202601MM-202607MM; quarterly: 202601SS-202602SS. Use the selected dataset’s time codes.

## `rootId` (type: `string`):

Required for statistics. Use nodeId from catalog with the matching frequency and no pid.

## `maxResults` (type: `integer`):

Limits saved dataset records. Does not trigger extra pages or limit how much data the upstream sends.

## Actor input object example

```json
{
  "action": "search",
  "search": "国内生产总值",
  "pagenum": 1,
  "pageSize": 5,
  "code": "2",
  "maxResults": 100
}
```

# Actor output Schema

## `records` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "search": "国内生产总值"
};

// Run the Actor and wait for it to finish
const run = await client.actor("happyfirst/datanbs-mcp-worker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "search": "国内生产总值" }

# Run the Actor and wait for it to finish
run = client.actor("happyfirst/datanbs-mcp-worker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "search": "国内生产总值"
}' |
apify call happyfirst/datanbs-mcp-worker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,happyfirst/datanbs-mcp-worker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/0HceZPXhf4FeToFVl/builds/bE905H2ii5CKJl7UY/openapi.json