省市区树形数据

省市区树形数据:返回全国省-市-区县完整 JSON 树,下拉选择器数据源

省市区树形数据:返回全国省-市-区县完整 JSON 树,供小程序、后台表单三级联动下拉使用。
数据源自民政部县级区划(与身份证解析共用 idcard_regions.json)。

支持完整树 tree、仅省级 provinces、按 parent 懒加载 children 三种模式。

调用地址:https://api.ynlskj.com.cn/gateway/regiontree

请求方法:GET

在其他地方怎么调用

  1. 请求地址用上面的调用地址,参数拼在网址后面,例如 ?action=tree
  2. 方法用 GET
  3. API Key 只能放在请求头 X-API-Key,不要写进网址,也不要写进 Query 框
  4. Key 在「个人中心 → API Key」里复制,登录后会自动填入你自己的 Key

参数说明

参数位置必填说明
actionQuerytree 完整三级树(默认)、provinces 仅省级、children 按 parent 懒加载
parentQuerychildren 时必填上级 code,如 110000(省)或 110100(市)
include_legacyQuery为 1 时包含历史区划码,默认仅现行数据
X-API-KeyHeader你的 API Key

这个接口是干什么的?

返回全国省-市-区县三级 JSON 树形数据,直接用于小程序、后台表单的级联选择器(Cascader)、地址组件数据源。

数据与「身份证格式解析」共用民政部县级区划包(约 3000 条现行区县),无需自己维护字典文件。

三种获取模式

action说明适用
tree(默认)一次返回完整三级树 tree[]首次加载后本地缓存,适合体积可控的项目
provinces仅返回省级列表第一级下拉
childrenparent 返回下一级懒加载级联,减少首包体积

节点结构

字段说明
code6 位行政区划码。省 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

返回说明

字段说明
retok 成功,err 失败
data.tree完整三级树数组(action=tree
data.provinces省级列表(action=provinces
data.children子级列表(action=children
data.count数量统计:树模式为 {provinces,cities,districts},其他为整数
data.parent / levelchildren 模式下的上级 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}}

在线调试

登录后可在线调试。调试会真实调用网关并消耗次数。

去登录