如何用Postman高效调用行政区划数据API：从本地模拟到多级联动实现

2026-05-03 10:08:43作者：明树来

在开发地址选择功能时，你是否曾因行政区划数据获取困难而停滞不前？是否在处理多级联动地址时，因数据格式不统一而反复调试？行政区划数据作为基础地理信息，广泛应用于电商配送、政务系统、地图服务等场景，但数据分散、格式混乱、更新不及时等问题一直困扰着开发者。本文将带你通过Postman构建本地API服务，高效解决行政区划数据获取与联动难题，让地址功能开发不再卡壳——行政区划数据API使用指南。

1_剖析开发痛点：为什么地址功能总是卡壳？

地址功能开发中，开发者常面临三大核心痛点：

数据获取渠道混乱
国家统计局官网数据需手动下载且格式不规范，第三方API存在调用限制，自建爬虫又面临法律风险和数据准确性问题。多数项目最终只能使用过时的静态数据文件，导致用户投诉"地址选项找不到最新街道"。

格式转换成本高
不同项目对数据格式需求差异大：前端需要JSON树形结构实现联动，后端数据库需要扁平化表结构，报表系统又需要CSV格式。手动转换不仅耗时，还容易出现字段缺失、编码错误等问题。

多级联动实现复杂
从"省份→城市→区县→乡镇"的四级联动，需要处理父子关系维护、数据过滤、动态加载等逻辑。传统嵌套循环实现方式不仅代码冗余，还会导致页面加载缓慢。

⚠️ 避坑指南：不要直接使用网络上的"精简版"行政区划数据，这些数据往往缺失乡级以下信息，且未包含最新的区划调整（如撤县设区、乡镇合并等行政变更）。

2_构建本地API模拟服务：3步实现无后端调用

既然项目未提供现成API接口，我们可以通过Postman构建本地模拟服务，实现与真实API一致的调用体验。

2.1_准备数据文件

📌 步骤1：获取完整数据

克隆项目代码库：

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

安装依赖并导出数据：
```
cd Administrative-divisions-of-China
npm install
bash export_json.sh  # 生成JSON格式数据
bash export_csv.sh   # 生成CSV格式数据
```
执行成功后，会在项目根目录生成dist文件夹，包含各级数据文件（如provinces.json、cities.json等）。

2.2_配置Postman本地请求

📌 步骤2：创建Collection

打开Postman，点击"New"→"Collection"，命名为"行政区划数据API"
创建请求文件夹：按"省级→地级→县级→乡级→村级"层级组织请求
添加GET请求，示例配置：
- 请求名称："获取省级列表"
- 请求URL：file:///path/to/Administrative-divisions-of-China/dist/provinces.json
- 响应格式：JSON

2.3_实现模拟接口功能

📌 步骤3：配置响应处理

在请求"Tests"标签页添加响应处理脚本：

// 格式化响应数据，添加请求元信息
pm.response.json().forEach(item => {
  item.requestTime = new Date().toISOString();
  item.dataSource = "国家统计局2023年数据";
});
pm.response.json(pm.response.json());

保存请求并发送，即可获得带元信息的标准化响应

⚠️ 避坑指南：Windows系统需注意文件路径格式，正确格式为file:///C:/path/to/provinces.json（注意三个斜杠和反斜杠转义）。

3_拆解数据结构：5分钟看懂行政区划数据

3.1_数据文件分类

项目提供两类核心数据文件，满足不同开发需求：

基础数据文件（按行政级别划分）

省级数据：dist/provinces.json（包含34个省级行政区）
地级数据：dist/cities.json（包含333个地级行政区）
县级数据：dist/areas.json（包含2843个县级行政区）
乡级数据：dist/streets.json（包含41636个乡镇街道）
村级数据：dist/villages.json（包含662238个村委会居委会）

联动数据文件（按层级关系划分）

二级联动：dist/pc.json（省份-城市）、dist/pc-code.json（带编码版）
三级联动：dist/pca.json（省份-城市-区县）、dist/pca-code.json（带编码版）
四级联动：dist/pcas.json（省份-城市-区县-乡镇）、dist/pcas-code.json（带编码版）

3.2_核心字段解析

所有数据文件均包含两个基础字段：

code：行政区划代码（如"110000"代表北京市）
name：行政区名称（如"北京市"、"朝阳区"）

多级联动数据额外包含上级编码字段：

城市数据：provinceCode（所属省份编码）
区县数据：cityCode（所属城市编码）、provinceCode（所属省份编码）

⚠️ 避坑指南：行政区划代码并非固定不变，每年都会有区划调整（如2023年新设的直辖市、撤县设区等），建议每季度更新一次数据。

4_实现多级联动地址：从前端到后端的完整方案

4.1_前端联动组件开发

以三级联动（省份→城市→区县）为例，使用Vue.js实现动态加载：

// 简化版联动组件逻辑
export default {
  data() {
    return {
      provinceList: [],
      cityList: [],
      areaList: [],
      selectedProvince: '',
      selectedCity: ''
    };
  },
  mounted() {
    // 加载省级数据
    this.loadProvinces();
  },
  methods: {
    async loadProvinces() {
      // 实际项目中替换为Postman模拟接口URL
      const res = await fetch('/api/provinces');
      this.provinceList = await res.json();
    },
    async loadCities(provinceCode) {
      // 根据省份编码筛选城市数据
      const res = await fetch('/api/cities');
      const allCities = await res.json();
      this.cityList = allCities.filter(city => city.provinceCode === provinceCode);
    },
    async loadAreas(cityCode) {
      // 根据城市编码筛选区县数据
      const res = await fetch('/api/areas');
      const allAreas = await res.json();
      this.areaList = allAreas.filter(area => area.cityCode === cityCode);
    }
  },
  watch: {
    selectedProvince(val) {
      this.loadCities(val);
      this.selectedCity = '';
      this.areaList = [];
    },
    selectedCity(val) {
      this.loadAreas(val);
    }
  }
};

4.2_后端数据接口实现

使用Node.js+Express构建真实API接口，连接项目提供的SQLite数据库：

const express = require('express');
const sqlite3 = require('sqlite3').verbose();
const app = express();
const port = 3000;

// 连接数据库
const db = new sqlite3.Database('dist/data.sqlite', (err) => {
  if (err) {
    console.error('数据库连接失败:', err.message);
  } else {
    console.log('已连接到行政区划数据库');
  }
});

// 获取省级数据接口
app.get('/api/provinces', (req, res) => {
  db.all('SELECT code, name FROM provinces', (err, rows) => {
    if (err) {
      res.status(500).json({ error: err.message });
    } else {
      res.json(rows);
    }
  });
});

// 获取城市数据接口（带省份筛选）
app.get('/api/cities', (req, res) => {
  const { provinceCode } = req.query;
  let sql = 'SELECT code, name, provinceCode FROM cities';
  const params = [];
  
  if (provinceCode) {
    sql += ' WHERE provinceCode = ?';
    params.push(provinceCode);
  }
  
  db.all(sql, params, (err, rows) => {
    if (err) {
      res.status(500).json({ error: err.message });
    } else {
      res.json(rows);
    }
  });
});

app.listen(port, () => {
  console.log(`行政区划API服务运行在 http://localhost:${port}`);
});

⚠️ 避坑指南：生产环境需为API添加缓存机制，建议使用Redis缓存热门查询结果，减少数据库压力（如省级数据缓存1小时，城市数据缓存30分钟）。

5_扩展应用：从数据可视化到跨平台集成

5.1_数据可视化实现

使用ECharts展示行政区划层级关系，以省级数据为例：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>行政区划层级可视化</title>
  <script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
</head>
<body>
  <div id="chart" style="width: 800px; height: 600px;"></div>
  
  <script>
    // 初始化图表
    const chart = echarts.init(document.getElementById('chart'));
    
    // 从API获取数据
    fetch('/api/provinces')
      .then(res => res.json())
      .then(data => {
        // 构建层级数据
        const treeData = {
          name: '中国行政区划',
          children: data.map(province => ({
            name: province.name,
            value: province.code,
            // 实际项目中可添加下级数据
            children: []
          }))
        };
        
        // 配置项
        const option = {
          tooltip: {
            trigger: 'item',
            formatter: '{b}: {c}'
          },
          series: [{
            type: 'tree',
            data: [treeData],
            top: '10%',
            left: '7%',
            bottom: '10%',
            right: '20%',
            symbolSize: 7,
            label: {
              position: 'left',
              verticalAlign: 'middle',
              align: 'right'
            },
            leaves: {
              label: {
                position: 'right',
                verticalAlign: 'middle',
                align: 'left'
              }
            },
            emphasis: {
              focus: 'descendant'
            },
            expandAndCollapse: true,
            animationDuration: 550,
            animationDurationUpdate: 750
          }]
        };
        
        chart.setOption(option);
      });
  </script>
</body>
</html>

5.2_跨平台数据集成方案

MySQL同步策略
将SQLite数据迁移至MySQL，适合中大型应用：

-- 创建省级表
CREATE TABLE provinces (
  code VARCHAR(6) PRIMARY KEY,
  name VARCHAR(50) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 从SQLite导入数据（通过工具或脚本）
-- 建议使用Navicat等工具的"数据传输"功能，或编写Node.js迁移脚本

Redis缓存方案
缓存热门查询结果，提高读取性能：

// Node.js缓存示例
const redis = require('redis');
const client = redis.createClient();

async function getProvinces() {
  // 尝试从缓存获取
  const cachedData = await client.get('provinces_data');
  if (cachedData) {
    return JSON.parse(cachedData);
  }
  
  // 缓存未命中，从数据库获取
  const data = await new Promise((resolve, reject) => {
    db.all('SELECT code, name FROM provinces', (err, rows) => {
      if (err) reject(err);
      else resolve(rows);
    });
  });
  
  // 设置缓存（有效期1小时）
  await client.set('provinces_data', JSON.stringify(data), { EX: 3600 });
  return data;
}

5.3_数据更新监控实现

基于国家统计局发布接口，实现自动更新提醒：

// 简化版更新监控脚本
const axios = require('axios');
const fs = require('fs');
const path = require('path');

// 统计局数据发布页面URL（示例）
const statsUrl = 'http://www.stats.gov.cn/tjsj/tjbz/tjyqhdmhcxhfdm/';

async function checkForUpdates() {
  try {
    const response = await axios.get(statsUrl);
    const html = response.data;
    
    // 提取最新数据日期（假设页面包含"截至XXXX年XX月XX日"字样）
    const dateMatch = html.match(/截至(\d{4}年\d{2}月\d{2}日)/);
    if (!dateMatch) throw new Error('未找到数据日期');
    
    const latestDate = dateMatch[1];
    const lastCheckFile = path.join(__dirname, 'last_update_check.txt');
    
    // 读取上次检查记录
    let lastDate = '';
    if (fs.existsSync(lastCheckFile)) {
      lastDate = fs.readFileSync(lastCheckFile, 'utf8').trim();
    }
    
    // 检查是否有更新
    if (latestDate !== lastDate) {
      console.log(`发现行政区划数据更新: ${lastDate} → ${latestDate}`);
      // 发送邮件通知或自动执行更新脚本
      // sendUpdateNotification(latestDate);
      // executeUpdateScript();
      
      // 更新检查记录
      fs.writeFileSync(lastCheckFile, latestDate);
    } else {
      console.log('数据已是最新版本');
    }
  } catch (error) {
    console.error('检查更新失败:', error.message);
  }
}

// 每天检查一次
setInterval(checkForUpdates, 24 * 60 * 60 * 1000);
checkForUpdates(); // 立即执行一次