五级行政区联动

接口标识: district 价格: 0.05 元/次 VIP免费同步响应

接口介绍
接口文档
在线测试

接口简介

五级行政区联动接口提供全国省、市、区县、乡镇街道、社区村五级行政区划数据，可按各级行政区ID逐级联动获取下级列表，也可凭村级ID反查完整的上级链路。基于66万+条离线行政区数据本地查询，毫秒级返回。适合地址级联选择器、物流分单与地址数据标准化等场景。

详细介绍

![五级行政区联动接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261109/apiops_district__1794166640_bbe16aeb7aff.png)

从省到村，一个接口搞定五级行政区划联动：逐级传入行政区ID即可获取下一级列表，凭村级ID还能反查完整上级链路。66万+条离线数据本地查询、毫秒级返回，是地址级联选择器与物流分单的基础件。

## 接口概述

五级行政区联动接口面向电商收货地址、物流分单、政务表单、数据治理等需要标准化行政区划的场景：内置66万余条省/市/区县/乡镇街道/社区村五级行政区数据（源自开源中国行政区划数据集 github.com/modood/Administrative-divisions-of-China），全部查询在本地库完成，无上游依赖。级联规则简单直接——参数全空返回省级列表，传省级ID得市，传市级ID得区县，传县级ID得乡镇，传乡镇ID得村；反向传入村级ID，则一次性返回该村完整的省市县镇上级链路。每条记录同时携带五级ID与名称字段，可直接驱动前端级联选择器或补全订单地址结构。

## 核心能力

1. **五级级联**：省→市→区县→乡镇街道→社区村逐级下钻，覆盖全国五级行政区划。
2. **村级反查**：传入村级ID直接返回完整上级链路，一条记录拿到五级归属。
3. **编码标准化**：省级输出6位、市及以下输出12位标准编码，传入编码自动归一化识别。
4. **全字段返回**：每条记录附带五级ID与名称，前端级联与数据入库无需二次拼接。
5. **条数可控**：单次默认返回前100条、最多500条，乡镇下辖村的长列表可预期。

## 产品优势

- **接入简单**：POST请求、JSON返回，五个参数全部选填，按需传一级即可。
- **毫秒级响应**：本地离线数据查询，无上游波动与配额限制，支持高并发。
- **数据完备**：66万+条五级记录，含乡镇街道与社区村两级，长尾地址也能覆盖。
- **口径统一**：编码与名称一次对齐，避免各系统自建地区表造成的口径混乱。
- **降本增效**：替代自建维护行政区划库，数据随平台统一更新。

## 效果展示

一句话理解：它就像一本「全国地名目录」的检索窗口——报上一级地名的编号，立刻翻出它下辖的所有子级；报一个村的编号，立刻告诉你它属于哪个镇、哪个县、哪个市、哪个省。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| provinceid | 110000 | 省级行政区ID，传入后返回其下辖市级列表；五个参数全空则返回省级列表 |

你会拿到的结果：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 记录ID | 32 | `id` |
| 所属省份 | 北京市（110000） | `provincename` / `provinceid` |
| 下辖市级 | 市辖区（110100000000） | `cityname` / `cityid`，作为下一级查询的入参 |

API请求示例：

```
POST /api/v1/district
provinceid=110000
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "list": [
      {
        "id": 32,
        "provinceid": "110000",
        "provincename": "北京市",
        "cityid": "110100000000",
        "cityname": "市辖区",
        "countyid": "",
        "countyname": "",
        "townid": "",
        "townname": "",
        "villageid": "",
        "villagename": ""
      }
    ]
  }
}
```

返回的 `list` 中每条记录都带全五级字段，未涉及的层级为空字符串；把本级返回的 `cityid` 作为下一次请求的入参，即可继续下钻到区县，逐级驱动前端级联选择器。

## 应用场景

- **电商收货地址**：注册与下单页的省市区县街道多级级联选择器数据源
- **物流分单**：按乡镇/村级编码自动归属配送网点与分拨中心
- **政务与企业表单**：属地信息标准化采集，避免手填地名口径混乱
- **数据治理**：历史订单地址批量反查补全五级编码，统一分析口径
- **O2O服务围栏**：按村级ID圈定服务可达范围，精细化开城

## 应用案例

- **生鲜电商**：接入前地址选择只到区县，乡镇村靠手填，分单错误频发；接入后五级级联直达村组，配送范围判定有标准编码可依，错分明显减少。
- **物流SaaS平台**：各家客户自建的地区表版本不一，同一个镇有多种写法；接入后统一以12位标准编码落库，跨客户报表可按村镇维度直接聚合。

常见问题

Q：这个接口能做什么？

A：查询中国五级行政区划（省/市/区县/乡镇街道/社区村）：不传参数返回省级列表；逐级传入行政区ID可获得下一级列表；传入村级ID可反查该村完整的省市县镇上级链路。

Q：级联参数应该怎么传？

A：五个参数全部选填，按需传最深一级即可：查市传 provinceid，查区县传 cityid，查乡镇传 countyid，查村传 townid。多个同传时按村→镇→县→市→省的优先级取最深层级生效。

Q：行政区ID是什么格式？

A：输出编码省级为6位（如110000）、市及以下为12位（如110100000000，尾部补零）。传入编码会自动归一化：省级取前2位、市级前4位、县级前6位、乡镇前9位、村级12位，因此传补零前后的编码均可识别。

Q：单次最多返回多少条？

A：默认返回前100条，可通过 limit 参数在1-500范围内调整，超出按边界值收敛。乡镇下辖村数量较多时建议传更大的 limit 一次取全。

Q：传入不存在的行政区ID会怎样？

A：返回错误响应（错误码50000，提示「查询失败，请稍后重试」），data 为空。请核对编码是否为库内收录的有效行政区编码。

行政区划五级联动省市县镇村地址级联区划代码物流分单

接口地址： https://www.phpwc.cn/api/district

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`provinceid`	string	选填	-	省级行政区ID
`cityid`	string	选填	-	市级行政区ID
`countyid`	string	选填	-	区县级行政区ID
`townid`	string	选填	-	乡镇（街道）级行政区ID
`villageid`	string	选填	-	社区（村）级行政区ID

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`list`−	array	行政区列表
`id`	int	记录ID
`provinceid`	string	省级行政区ID
`provincename`	string	省级名称
`cityid`	string	市级行政区ID
`cityname`	string	市级名称
`countyid`	string	区县级行政区ID
`countyname`	string	区县级名称
`townid`	string	乡镇级行政区ID
`townname`	string	乡镇级名称
`villageid`	string	村级行政区ID
`villagename`	string	村级名称
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

请先登录后使用在线测试