行政区划 API

行政区划数据查询接口。

概述

提供行政区划数据的查询功能，支持获取全部行政区划、获取下级区划、关键词搜索等操作。

Base URL: https://api.newayz.com

接口列表

接口 方法 路径 说明
获取省市区列表 GET /location/scenario/v1/districts/list 获取全部省市区三级行政区划
获取下级区划 GET /location/scenario/v1/districts/children 根据父级 adcode 获取下 级区划
行政区划搜索 GET /location/scenario/v1/districts/search 根据关键词搜索行政区划

接口详情

1.获取省市区列表

获取全部省市区三级行政区划列表。

请求路径: https://api.newayz.com/location/scenario/v1/districts/list

请求参数:

字段名 类型 必填 说明 说明
access_key string 是 访问密钥
output string 否 flat 输出结构:flat= 扁平结构;nested=嵌套结构

响应参数:

字段名 类型 说明
status int 状态码，0 表示成功
message string 状态消息
data_version string 数据版本
result array 行政区划列表

ListDistrict结构:

字段名 类型 说明
adcode string 行政区划 ID
province string 省份
city string 城市
district string 区县
level int 级别：1=省/2=市/3=区县
location object 中心点经纬度
location.lat float64 纬度
location.lng float64 经度
polygon array 边界点串（二维数组）
districts array 下级区划（嵌套结构，仅 nested 模式返回）

示例请求:

# 扁平结构（默认）
curl "https://api.newayz.com/location/scenario/v1/districts/list"
# 嵌套结构
curl "https://api.newayz.com/location/scenario/v1/districts/list?output=nested"

示例响应 (flat 模式):

{
    "status": 0,
    "message": "success",
    "data_version": "20250721",
    "result": [
        {
            "adcode": "110000",
            "province": "北京市",
            "level": 1,
            "location": {
                "lat": 39.904179,
                "lng": 116.407387
            }
        },
        {
            "adcode": "110100",
            "province": "北京市",
            "city": "北京市",
            "level": 2,
            "location": {
                "lat": 39.904989,
                "lng": 116.405285
            }
        }
    ]
}

示例响应 (nested 模式):

{
    "status": 0,
    "message": "success",
    "data_version": "20250721",
    "result": [
        {
            "adcode": "110000",
            "location": {
                "lat": 39.904179,
                "lng": 116.407387
            },
            "districts": [
                {
                    "adcode": "110100",
                    "province": "北京市",
                    "city": "北京市",
                    "level": 2,
                    "location": {
                        "lat": 39.904989,
                        "lng": 116.405285
                    },
                    "districts": [
                        {
                            "adcode": "110101",
                            "province": "北京市",
                            "city": "北京市",
                            "district": "东城区",
                            "level": 3,
                            "location": {
                                "lat": 39.928359,
                                "lng": 116.416334
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

2. 获取下级行政区划

根据父级 adcode 获取下级行政区划。

请求路径: https://api.newayz.com/location/scenario/v1/districts/children

请求参数:

参数名 类型 必填 默认值 说明
access_key string 是 - 访问密钥
parent_adcode string 否 空 父级行政区划 ID， 缺省返回省级
need_polygon boolean 否 false 是否需要边界数据

响应参数:

字段名 类型 说明
status int 状态码，0 表示成功
message string 状态消息
data_version string 数据版本
result array 下级区划列表

示例请求:

# 获取省级列表
curl "https://api.newayz.com/location/scenario/v1/districts/children"

# 获取北京市下辖区县
curl "https://api.newayz.com/location/scenario/v1/districts/children?parent_adcode=110000"

# 获取区县下街道（需要边界数据）
curl "https://api.newayz.com/location/scenario/v1/districts/children?parent_adcode=110101&need_polygon=true"

示例响应:

{
    "status": 0,
    "message": "success",
    "data_version": "20250721",
    "result": [
        {
            "adcode": "110000",
            "province": "北京市",
            "level": 1,
            "location": {
                "lat": 39.904179,
                "lng": 116.407387
            }
        },
        {
            "adcode": "110100",
            "province": "北京市",
            "city": "北京市",
            "level": 2,
            "location": {
                "lat": 39.904989,
                "lng": 116.405285
            }
        }
    ]
}

3. 行政区划搜索

根据关键词搜索行政区划，支持按名称或 adcode 搜索。

请求路径: https://api.newayz.com/location/scenario/v1/districts/search

请求参数:

参数名 类型 必填 默认值 说明
status int 是 - 访问密钥
keyword string 是 - 搜索关键词（名称 或 adcode）
need_polygon boolean 否 false 是否需要边界数据

响应参数:

字段名 类型 说明
status int 状态码，0 表示成功
message string 状态消息
data_version string 数据版本
result array 搜索结果（二维数组，按级别分 组）

SearchItem 结构:

字段名 类型 说明
adcode string 行政区划 ID
name string 完整名称
level int 级别：1=省/2=市/3=区县/4=街道
location object 中心点经纬度
location.lat float64 纬度
location.lng float64 经度
address string 地址层级拼接（逗号分隔）

示例请求:

# 按名称搜索
curl "https://api.newayz.com/location/scenario/v1/districts/search?keyword=朝阳区"

# 按 adcode 搜索
curl "https://api.newayz.com/location/scenario/v1/districts/search?keyword=110105"

# 搜索并返回边界数据
curl "https://api.newayz.com/location/scenario/v1/districts/search?keyword=海淀区&need_polygon=true"

示例响应:

{
    "status": 0,
    "message": "success",
    "data_version": "20250721",
    "result": [
        [
            {
                "adcode": "110105",
                "name": "朝阳区",
                "level": 3,
                "location": {
                    "lat": 39.921444,
                    "lng": 116.443136
                },
                "address": "北京市,北京市,朝阳区"
            }
        ]
    ]
}

status说明

status 说明
0 成功
1001 请求参数错误（如 keyword 必填但未提供）
2000 服务器内部错误

错误响应

{
    "status": 1001,
    "message": "keyword is required"
}

数据级别说明

level 说明
1 省级（省/直辖市/自治区/特别行政区）
2 市级（城市/地区）
3 区县级（区/县/县级市）
4 街道级（街道/镇/乡）