> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawdot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# errand_search_addresses

> MCP 工具 errand_search_addresses —— 按关键词或当前位置搜地址，同时返回命中的已存地址

## errand\_search\_addresses

搜索地址，同时返回两份结果：搜到的候选地点（`candidates`），以及用户已经存过、且命中本次搜索的地址（`saved_matches`）。同名地址可能有多处，不要自动取第一个，应摆给用户挑。`saved_matches` 里的地址门牌和联系电话都已经齐全，选中即可直接下单，不必再让用户重新报一遍。

<Note>
  **地址链路**：搜到候选地点后，用 `errand_save_address` 存进地址簿；命中 `saved_matches` 的地址已经存过，可以跳过保存，直接拿 `id` 当 `address_id` 下单。
</Note>

### 两种找法，至少给一样

* **用户说了地名**（「送到人民广场」）→ 传 `keyword`，可加 `city` 缩小范围。
* **用户说「从我现在的位置」** → 没有地名可搜，传他的 `lat` / `lng`。会返回这个位置所属的几个地点名，从具体到宽泛（如「星洲花园南区圣陶沙韵」「星洲花园南区」「星洲花园」），摆给用户确认哪个说法对。
* **两个都传** → 按 `keyword` 搜，坐标用来把近的排前面。

<Warning>
  用户说地名时**不要让坐标顶替 `keyword`**，否则「送到人民广场」会变成搜他当前位置。
</Warning>

### 参数

| 参数                 | 类型     | 必填 | 默认 | 说明                                                              |
| ------------------ | ------ | -- | -- | --------------------------------------------------------------- |
| `consent_grant_id` | string | 是  | —  | 用户授权记录 ID（`cg_` 前缀），来自 `errand_verify_user_bind`                |
| `keyword`          | string | 否  | —  | 地名/地址关键词，如「西湖文化广场」。与 `lat`/`lng` 至少给一样，都不给返回 `KEYWORD_REQUIRED` |
| `city`             | string | 否  | —  | 城市名，缩小搜索范围（如「杭州」）                                               |
| `lat`              | number | 否  | —  | 用户当前位置的纬度（GCJ-02）。只给它就是按位置找地址；与 `keyword` 同时给则用于就近排序            |
| `lng`              | number | 否  | —  | 同上，经度（GCJ-02）。与 `lat` 一起给，缺一个视为没给位置                             |

### 返回

```json theme={null}
{
  "candidates": [
    { "name": "五一广场", "address": "黄兴中路88号", "lat": 28.1965, "lng": 112.9773, "adcode": "430102" }
  ],
  "saved_matches": [
    {
      "id": "plat_12",
      "contact_name": "王先生",
      "contact_phone_masked": "138****5678",
      "address": "五一广场 黄兴中路88号",
      "detail": "东门",
      "lat": 28.1965,
      "lng": 112.9773,
      "tag": "公司",
      "match_reason": "same_place"
    }
  ]
}
```

| 字段                                     | 类型             | 说明                                                                                           |
| -------------------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `candidates`                           | array          | 搜到的候选地址                                                                                      |
| `candidates[].name`                    | string         | 地点名称。按位置找时，同一位置会返回几个名称，从具体到宽泛                                                                |
| `candidates[].address`                 | string         | 详细地址                                                                                         |
| `candidates[].lat`                     | number         | 纬度（GCJ-02），回填下单的 `from_address`/`to_address`。**按位置找时恒等于传入的经纬度**——选哪条只决定给骑手看的地名，取件点始终是用户所在的位置 |
| `candidates[].lng`                     | number         | 经度（GCJ-02）                                                                                   |
| `candidates[].adcode`                  | string         | 行政区编码                                                                                        |
| `saved_matches`                        | array          | 用户已存过、且命中本次搜索的地址；没有命中为空数组                                                                    |
| `saved_matches[].id`                   | string         | 地址 ID（`plat_` 前缀），可直接当 `address_id` 下单                                                       |
| `saved_matches[].contact_name`         | string         | 联系人（可空）                                                                                      |
| `saved_matches[].contact_phone_masked` | string         | 脱敏联系电话（如 `138****5678`）；没存过电话时为空串                                                            |
| `saved_matches[].address`              | string         | 地址                                                                                           |
| `saved_matches[].detail`               | string         | 门牌补充（如「3 号楼 303」）；没填过为空串                                                                     |
| `saved_matches[].lat`                  | number         | 纬度（GCJ-02）                                                                                   |
| `saved_matches[].lng`                  | number         | 经度（GCJ-02）                                                                                   |
| `saved_matches[].tag`                  | string         | 标签                                                                                           |
| `saved_matches[].source`               | string         | 地址来源，跑腿存的恒为 `errand`                                                                         |
| `saved_matches[].last_used_at`         | string \| null | 最近使用时间                                                                                       |
| `saved_matches[].use_count`            | integer        | 使用次数                                                                                         |
| `saved_matches[].match_reason`         | string         | 命中方式：`keyword`（关键词对上了名称/门牌/标签/联系人）、`same_place`（与某条候选是同一个坐标）、`both`（两者都命中）                   |

<Note>
  搜索无结果且用户没有已存地址时，返回 `{ "candidates": [], "saved_matches": [] }`，不是报错。
</Note>

### 错误码

| code                        | 说明                            |
| --------------------------- | ----------------------------- |
| `CONSENT_GRANT_REQUIRED`    | 缺少用户授权（未传 `consent_grant_id`） |
| `CONSENT_GRANT_INVALID`     | 用户授权无效                        |
| `CONSENT_GRANT_EXPIRED`     | 用户授权已过期，需重新授权                 |
| `CONSENT_GRANT_WRONG_CAP`   | 授权属于其它能力，跑腿需单独绑定              |
| `CAP_NOT_BOUND`             | 该 Agent 未开通跑腿能力               |
| `KEYWORD_REQUIRED`          | 关键词与经纬度都没给                    |
| `ERRAND_LOCATE_UNAVAILABLE` | 地址搜索服务暂未开通                    |
| `ADDRESS_SEARCH_FAILED`     | 地址搜索失败，稍后再试                   |

完整错误码见 [错误处理](/gateway/error-handling)。

### 调用示例

按地名找：

```json theme={null}
{
  "name": "errand_search_addresses",
  "arguments": {
    "consent_grant_id": "<consent_grant_id>",
    "keyword": "五一广场",
    "city": "长沙"
  }
}
```

按当前位置找：

```json theme={null}
{
  "name": "errand_search_addresses",
  "arguments": {
    "consent_grant_id": "<consent_grant_id>",
    "lat": 30.290000,
    "lng": 120.096000
  }
}
```