naisi_region_search

按必填类型搜索有效地区，国内仅搜索 name、short_name、pinyin、pinyin_short， 国际仅搜索 name、en_name、zh_name，籍贯仅搜索 native_place_name；不搜索编码、numeric 或 full_name。 按精确、前缀、包含匹配排序，同级按编码排序；ASCII 字母不区分大小写。 返回扁平数组，公共字段为 region_code、region_type、region_kind、level、name、full_name， 国内另含 short_name、pinyin、pinyin_short；国际另含 en_name、zh_name、numeric；籍贯另含 native_place_name。 不附 parents；full_name 按真实父链用 / 拼接，国际使用 zh_name，国内/籍贯使用 name；所需名称缺失返回空字符串。 空关键词、非正数 limit、未命中、未授权或加载失败返回 []。

函数签名

function naisi_region_search(string $keyword, int $region_type, int $limit = 20): array

调用前提

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

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

参数

$keyword

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

要匹配的编码、名称、拼音或英文关键词。

$region_type

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

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

$limit

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

搜索结果数量上限，默认 20；非正数返回空数组。

返回值

成功时返回上方说明的扁平数组；空关键词、非正 limit、未命中、未授权或加载失败返回 []。

调用示例

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

$keyword = '广信区';
$region_type = 1;
$limit = 1;

$result = naisi_region_search($keyword, $region_type, $limit);
var_export($result);

编码与异常

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

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

版本信息

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