🔥3步掌握行政区划API：2023最新版多级联动数据应用指南

你是否在开发地址选择功能时，因行政区划数据获取困难而影响项目进度？是否在处理多级联动地址时，因数据格式不统一而反复调试？本文将带你通过"问题-方案-实践"三步法，高效使用Administrative-divisions-of-China项目的2023行政区划数据，解决地址数据获取与联动难题。

数据特性：全面解析行政区划数据体系

Administrative-divisions-of-China项目提供中华人民共和国省级（省份）、地级（城市）、县级（区县）、乡级（乡镇街道）、村级（村委会居委会）五级行政区划数据，数据来源为国家统计局2023年统计用区划代码和城乡划分代码，截止时间2023-06-30，发布时间2023-09-11。

基础数据字典：五级数据结构详解

文件列表	JSON	CSV
省级（省份、直辖市、自治区）	provinces.json	provinces.csv
地级（城市）	cities.json	cities.csv
县级（区县）	areas.json	areas.csv
乡级（乡镇、街道）	streets.json	streets.csv
村级（村委会、居委会）	villages.json	villages.csv

各级数据包含code和name字段，以下为省级数据预览：

code	name
13	河北省
14	山西省
15	内蒙古自治区
45	广西壮族自治区

联动数据模型：多级数据关联方式

文件列表	普通	带编码
“省份、城市” 二级联动数据	pc.json	pc-code.json
“省份、城市、区县” 三级联动数据	pca.json	pca-code.json
“省份、城市、区县、乡镇” 四级联动数据	pcas.json	pcas-code.json
“省份、城市、区县、乡镇、村庄” 五级联动数据	-	-

多级联动数据包含对应的上级编码字段，例如县级数据包含code、name、cityCode、provinceCode字段。

获取方案：如何导出JSON格式数据？

环境准备

首先需要克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/ad/Administrative-divisions-of-China
cd Administrative-divisions-of-China
npm install

JSON数据导出

使用项目提供的export_json.sh脚本导出JSON格式数据：

# 执行JSON导出脚本
npm run json

提示：脚本会从SQLite数据库中查询数据并生成JSON文件，输出到dist目录下

CSV数据导出

使用export_csv.sh脚本导出CSV格式数据：

# 执行CSV导出脚本
npm run csv

数据库直接查询

通过lib/sqlite.js模块可以直接操作SQLite数据库：

const { Province, City, Area, Street, Village, init } = require('./lib/sqlite.js');

async function queryData() {
  await init();
  
  // 查询所有省份
  const provinces = await Province.findAll();
  console.log(provinces.map(p => ({ code: p.code, name: p.name })));
  
  // 查询特定省份的城市
  const cities = await City.findAll({
    where: { provinceCode: '11' } // 北京市
  });
  console.log(cities.map(c => ({ code: c.code, name: c.name })));
}

queryData();

实战技巧：如何使用Postman测试行政区划API？

环境变量配置

1. 打开Postman，创建新的环境
2. 添加环境变量：
   • base_url：本地数据文件路径，如file:///path/to/Administrative-divisions-of-China/dist
   • province_file：provinces.json
   • city_file：cities.json

创建API请求

① 创建获取省份列表的GET请求：

• URL: {{base_url}}/{{province_file}}

② 创建获取城市列表的GET请求：

• URL: {{base_url}}/{{city_file}}

③ 添加测试脚本验证响应格式：

pm.test("响应状态码为200", function () {
  pm.response.to.have.status(200);
});

pm.test("响应为JSON格式", function () {
  pm.response.to.be.json;
});

pm.test("JSON数组包含code和name字段", function () {
  const responseData = pm.response.json();
  pm.expect(responseData).to.be.an('array');
  pm.expect(responseData[0]).to.have.property('code');
  pm.expect(responseData[0]).to.have.property('name');
});

多级联动实现

使用curl命令获取省份数据：

curl "file:///path/to/Administrative-divisions-of-China/dist/provinces.json"

Python请求代码示例：

import requests
import json

url = "file:///path/to/Administrative-divisions-of-China/dist/provinces.json"
response = requests.get(url)
provinces = json.loads(response.text)

for province in provinces[:5]:
    print(f"{province['code']}: {province['name']}")

常见问题速查表

问题	解决方案
导出的JSON文件为空	确保已执行npm install安装依赖，检查dist目录是否存在data.sqlite文件
脚本执行权限不足	运行chmod +x export_json.sh export_csv.sh赋予执行权限
Postman无法加载本地文件	确认文件路径正确，浏览器可能限制本地文件访问，建议使用Postman桌面版
数据不完整或过时	项目数据来源为国家统计局2023年数据，如需更新可关注项目仓库更新
如何实现前端多级联动	可使用pc-code.json等联动数据文件，通过上级code筛选下级数据