省市区树形数据
省市区树形数据:返回全国省-市-区县完整 JSON 树,下拉选择器数据源
省市区树形数据:返回全国省-市-区县完整 JSON 树,供小程序、后台表单三级联动下拉使用。
数据源自民政部县级区划(与身份证解析共用 idcard_regions.json)。
支持完整树 tree、仅省级 provinces、按 parent 懒加载 children 三种模式。
数据源自民政部县级区划(与身份证解析共用 idcard_regions.json)。
支持完整树 tree、仅省级 provinces、按 parent 懒加载 children 三种模式。
调用地址:https://api.ynlskj.com.cn/gateway/regiontree
请求方法:GET
在其他地方怎么调用
- 请求地址用上面的调用地址,参数拼在网址后面,例如
?action=tree - 方法用
GET - API Key 只能放在请求头
X-API-Key,不要写进网址,也不要写进 Query 框 - Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key
参数说明
| 参数 | 位置 | 必填 | 说明 |
|---|---|---|---|
action | Query | 否 | tree 完整三级树(默认)、provinces 仅省级、children 按 parent 懒加载 |
parent | Query | children 时必填 | 上级 code,如 110000(省)或 110100(市) |
include_legacy | Query | 否 | 为 1 时包含历史区划码,默认仅现行数据 |
X-API-Key | Header | 是 | 你的 API Key |
这个接口是干什么的?
返回全国省-市-区县三级 JSON 树形数据,直接用于小程序、后台表单的级联选择器(Cascader)、地址组件数据源。
数据与「身份证格式解析」共用民政部县级区划包(约 3000 条现行区县),无需自己维护字典文件。
三种获取模式
| action | 说明 | 适用 |
|---|---|---|
tree(默认) | 一次返回完整三级树 tree[] | 首次加载后本地缓存,适合体积可控的项目 |
provinces | 仅返回省级列表 | 第一级下拉 |
children | 按 parent 返回下一级 | 懒加载级联,减少首包体积 |
节点结构
| 字段 | 说明 |
|---|---|
code | 6 位行政区划码。省 110000、市 110100、区县 110101 |
name | 名称,如「北京市」「东城区」 |
children | 下级节点数组(完整树模式) |
请求示例
| 场景 | Query 示例 |
|---|---|
| 完整三级树 | ?action=tree 或不传参数 |
| 仅省级 | ?action=provinces |
| 某省下的市 | ?action=children&parent=110000 |
| 某市下的区县 | ?action=children&parent=110100 |
| 含历史区划 | ?action=tree&include_legacy=1 |
懒加载级联示例(伪代码)
provinces = GET /gateway/regiontree?action=provinces cities = GET /gateway/regiontree?action=children&parent=110000 districts = GET /gateway/regiontree?action=children&parent=110100
说明
- 默认
GET请求,参数放 Query;数据只读,建议客户端本地缓存 - 完整树约 3000+ 区县,体积较大时可改用
children懒加载 - 更新数据:服务器执行
php cli/build_idcard_regions.php
返回说明
| 字段 | 说明 |
|---|---|
ret | ok 成功,err 失败 |
data.tree | 完整三级树数组(action=tree) |
data.provinces | 省级列表(action=provinces) |
data.children | 子级列表(action=children) |
data.count | 数量统计:树模式为 {provinces,cities,districts},其他为整数 |
data.parent / level | children 模式下的上级 code 与级别(province/city) |
data.include_legacy | 是否包含历史区划 |
msg | 本站提示,如「次数充足,剩余 99 次」或「次数不足,剩余 0 次」 |
remain_quota | 本次调用后的剩余次数 |
可直接复制的代码
未登录时示例只显示「你的密钥」。登录后会自动填入你自己的 Key,不会展示别人的。
<?php
$ch = curl_init('https://api.ynlskj.com.cn/gateway/regiontree?action=tree');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: 你的密钥'],
]);
echo curl_exec($ch);
请求参数演示
{"action":"tree"}
响应演示
{"ret":"ok","data":{"action":"tree","count":{"provinces":34,"cities":342,"districts":2978},"tree":[{"code":"110000","name":"北京市","children":[{"code":"110100","name":"北京市","children":[{"code":"110101","name":"东城区"},{"code":"110102","name":"西城区"}]}]}],"include_legacy":false}}