# `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、未命中、未授权或加载失败返回 []。

## 函数签名

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

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/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、未命中、未授权或加载失败返回 `[]`。

## 调用示例

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

```php
$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`