4. 基础能力 API 4.7 地区列表【基础探测通过，待数据联调】

Table of Contents

4.7 地区列表【基础探测通过，待数据联调】

GET /tieup/api/v1/regions

查询参数：

参数 类型 必填 说明
level integer 否 最大返回层级：1=省，2=省市，3=省市区；默认 3，非法值按 3 处理
region_scope string 否 mainland、hongkong、macau、taiwan

响应字段：

字段 类型 说明
code string 行政区划编码
parent_code string 父级行政区划编码，顶级为 0
name string 地区名称
level integer 地区层级：1=省/直辖市/特别行政区，2=市，3=区县
region_scope string 地区范围：mainland=中国大陆，hongkong=香港，macau=澳门，taiwan=台湾
sort integer 排序值
children array 子级地区列表，末级为空数组
items[].code string 编码
items[].parent_code string 父级编码
items[].name string 名称
items[].level integer 层级
items[].region_scope string 地区范围
items[].sort integer 排序值
items[].children array 子级列表
items[].children[].code string 编码
items[].children[].parent_code string 父级编码
items[].children[].name string 名称
items[].children[].level integer 层级
items[].children[].region_scope string 地区范围
items[].children[].sort integer 排序值
items[].children[].children array 子级列表
items[].children[].children[].code string 编码
items[].children[].children[].parent_code string 父级编码
items[].children[].children[].name string 名称
items[].children[].children[].level integer 层级
items[].children[].children[].region_scope string 地区范围
items[].children[].children[].sort integer 排序值
items[].children[].children[].children array 子级列表

示例：

[
  {
    "code": "44",
    "parent_code": "0",
    "name": "广东省",
    "level": 1,
    "region_scope": "mainland",
    "sort": 44,
    "children": [
      {
        "code": "4403",
        "parent_code": "44",
        "name": "深圳市",
        "level": 2,
        "region_scope": "mainland",
        "sort": 4403,
        "children": [
          {
            "code": "440305",
            "parent_code": "4403",
            "name": "南山区",
            "level": 3,
            "region_scope": "mainland",
            "sort": 440305,
            "children": []
          }
        ]
      }
    ]
  }
]

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "code": "44",
      "parent_code": "0",
      "name": "广东省",
      "level": 1,
      "region_scope": "mainland",
      "sort": 44,
      "children": [
        {
          "code": "4403",
          "parent_code": "44",
          "name": "深圳市",
          "level": 2,
          "region_scope": "mainland",
          "sort": 4403,
          "children": [
            {
              "code": "440305",
              "parent_code": "4403",
              "name": "南山区",
              "level": 3,
              "region_scope": "mainland",
              "sort": 440305,
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

说明：

  • 鉴权：公开接口，不需要 Authorization。
  • 仅返回 status = 1 的地区。
  • level 控制树的最大深度，不再表示只查询某一层；接口不再使用 parent_code 做分级懒加载。
  • 测试状态：已完成代码实现和 PHP 语法检查，待地区数据联调。