NaisiNaisi Lib Docs

naisi_region_list

查看 Markdown

获取指定类型有效地区；忽略已删除记录。 parent_code=null 返回元信息和全部 items；显式 0 返回根节点，其他父编码返回有效直属下级。 元信息为 region_type、version、source_version、updated_at、total_count、active_count、deleted_count、items。 updated_at 为 UTC Unix 秒；deleted_count 是数据包提供的版本删除统计。 元素公共字段为 region_code、parent_code、region_kind、level、name；国内另含 short_name， 国际另含 en_name、zh_name、numeric，籍贯另含 native_place_name。元素不附 parents 或 region_type。 籍贯 region_kind 按 area_code 关联国内表读取；native_place_name 空字符串原样返回。 成功读取的空数据集保留元信息；未授权或加载失败返回 []。

函数签名

function naisi_region_list(int $region_type, ?int $parent_code = null): array

调用前提

应用入口先调用 naisi_is_ext_license_valid 并确认返回 true。只验证同一请求内已有的有效 FULL/BASIC 证明；没有证明或证明失效时立即返回失败值，不现场补做完整校验。

授权类别：LICENSE；执行模式：PROOF。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

参数

$region_type

  • 类型：int
  • 必填：是
  • 默认值：无
  • 方向：输入参数。

整数选择器：NAISI_REGION_TYPE_CHINA=1（国内行政区划）、NAISI_REGION_TYPE_GLOBAL=2（全球）、NAISI_REGION_TYPE_NATIVE_PLACE=3（籍贯）。其他整数为业务失败。

$parent_code

  • 类型：?int
  • 必填：否
  • 默认值：null
  • 方向：输入参数。

直属父级编码；null 获取完整数据集，0 获取根节点。

返回值

成功时返回全量元信息或直属下级数组，结构见上方说明；未授权或加载失败返回 []。

关联常量

调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

$region_type = 1;
$parent_code = 361100;

$result = naisi_region_list($region_type, $parent_code);
var_export($result);

编码与异常

籍贯与国内行政区划共用编码。get/code_to_name 不增加类型参数，国内编码使用行政区划名称和父链；列表、搜索、名称解析按传入类型选择数据。get/code_to_name 可读取库中仍保留的软删除记录，其余接口过滤软删除记录；物理删除的历史记录无法查询。

参数必须与签名声明的原始 PHP 类型一致，不做弱类型转换；类型不匹配返回 []。参数数量错误仍遵循 PHP 标准异常规则。文本使用 UTF-8，地区文本及分隔符最多 4096 字节，不允许 NUL。没有引用输出参数。

版本信息

  • 实现模块：region
  • 授权类别：LICENSE / PROOF
  • 失败回退：[]
  • 文档同步：2026-10-18