errand_search_addresses

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

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

两种找法，至少给一样

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

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

参数

参数	类型	必填	默认	说明
`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` 一起给，缺一个视为没给位置

{
  "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`（两者都命中）

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

错误码

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`	地址搜索失败，稍后再试

完整错误码见错误处理。

调用示例

按地名找：

{
  "name": "errand_search_addresses",
  "arguments": {
    "consent_grant_id": "<consent_grant_id>",
    "keyword": "五一广场",
    "city": "长沙"
  }
}

按当前位置找：

{
  "name": "errand_search_addresses",
  "arguments": {
    "consent_grant_id": "<consent_grant_id>",
    "lat": 30.290000,
    "lng": 120.096000
  }
}

概览

授权

地址

询价与下单

订单管理

回调与参考

errand_search_addresses

errand_search_addresses

两种找法，至少给一样

参数

返回

错误码

调用示例

​errand_search_addresses

​两种找法，至少给一样

​参数

​返回

​错误码

​调用示例

errand_search_addresses

两种找法，至少给一样

参数

返回

错误码

调用示例