Metadata-Version: 2.3
Name: nbsdata
Version: 1.0.2
Summary: Data from National Bureau of Statistics of China
Author: rhozhang
Author-email: rhozhang <rhozhang@163.com>
Requires-Dist: polars>=1.42.1
Requires-Dist: requests>=2.34.2
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/rhozhang/nbsdata
Project-URL: Repository, https://github.com/rhozhang/nbsdata
Description-Content-Type: text/markdown

# 国家统计局数据

*nbsdata* 包目的是从中国国家统计局获取数据，使用该包时请自觉遵守国家统计局有关数据使用的规范。

## 安装

```bash
pip install nbsdata
```

注意本包依赖 requests 和 polars 两个包，请自行安装。

## 使用

在获取统计局数据时，首先需要获取：

- cid: 数据集代码
- indicatorid: 指标代码
- provinceid: 获取地区数据时需要省级单位代码，如“浙江”为 "330000000000". 对于全国数据，使用 "000000000000"
- period: 获取数据时需要指定时间段.

### 包的加载

```python
import nbsdata as nbs
```

以下以获取 2021 年 1 季度至 2026 年 1 季度“浙江”的“农村居民人均可支配收入”的数据为例，介绍数据获取的整个流程。

### 获取数据集代码

从根节点出发，依次查询，直至叶节点为止。

```python
nbs.get_cid('regional_quarterly')
```

获取的 cid 为 "854f819b04104191a5ae2f2cba270e6c". 以该 cid 为父节点，继续查询：

```python
nbs.get_cid('regional_quarterly', '854f819b04104191a5ae2f2cba270e6c')
```

此时得到“人民生活”节点对应的 cid 为 "a7b44a1c308f4533ae28fc0665c96c5a". 继续查询：

```python
nbs.get_cid('regional_quarterly', 'a7b44a1c308f4533ae28fc0665c96c5a')
```

得到“居民人均可支配收入”对应的 cid 为 "1065e991d0c84623bf0e0d012f36c0e3", 并且显示该节点为叶节点，数据集代码查询结束。

### 获取指标代码

现在查询叶节点“居民人均可支配收入”对应的具体指标对应的指标代码：

```python
nbs.get_indicatorids('1065e991d0c84623bf0e0d012f36c0e3')
```

从返回的数据框中可得到包含“农村居民人均可支配收入”的指标对应的代码为 "c6a1a68990ea4d6dafad3dbcf530d5cb"。

### 获取地区代码

获取“浙江”对应的地区代码：

```python
nbs.query_province_code('浙江')
```

返回浙江的代码为 "330000000000".

### 获取数据

现在我们已经完成了获取数据的所有准备，可以开始获取数据了。

```python
nbs.getdata(
    cid = '1065e991d0c84623bf0e0d012f36c0e3',
    indid = 'c6a1a68990ea4d6dafad3dbcf530d5cb',
    period = '202101SS-202601SS',
    region = '330000000000'
)
```

返回一个 21 * 4 的数据框：

│ region ┆ time     ┆ value ┆ unit │
│ ---    ┆ ---      ┆ ---   ┆ ---  │
│ 浙江省 ┆ 202101SS ┆ 11686 ┆ 元   │
│ 浙江省 ┆ 202102SS ┆ 20357 ┆ 元   │
│ 浙江省 ┆ 202103SS ┆ 28474 ┆ 元   │
│ 浙江省 ┆ 202104SS ┆ 35247 ┆ 元   │
│ 浙江省 ┆ 202201SS ┆ 12541 ┆ 元   │
│ …      ┆ …        ┆ …     ┆ …    │
│ 浙江省 ┆ 202501SS ┆ 15043 ┆ 元   │
│ 浙江省 ┆ 202502SS ┆ 25986 ┆ 元   │
│ 浙江省 ┆ 202503SS ┆ 36383 ┆ 元   │
│ 浙江省 ┆ 202504SS ┆ 45154 ┆ 元   │
│ 浙江省 ┆ 202601SS ┆ 15934 ┆ 元   |

注意上述数据为季度累计值，我们可以在此基础上利用 polars 进行整理，得到各季度的当前值。

```python
df2 = df.with_columns(
    pl.col('time').str.head(4).cast(pl.Int8).alias('year'),
    pl.col('time').str.slice(4, 2).cast(pl.Int8).alias('quarter')
).sort(
    'region', 'year', 'quarter'
).select(
    pl.col('region'),
    pl.col('year'),
    pl.col('quarter'),
    pl.col('value').diff().over('year').fill_null(pl.col('value'))
)
```

**参考文献**

- <https://data.stats.gov.cn>
- <https://zhuanlan.zhihu.com/p/2020899586898707578>
