search_addresses

列出当前授权用户在网关侧已保存的收货地址（saved_addresses），并在传入 keyword 时返回 POI 候选地址（suggestions）。传入 lat/lng 时，会为每个已保存地址标注 distance_meters，并把最近的一个地址 ID 放在顶层 nearest_address_id。

下单链路位置：本工具拿到的 address_id（已保存地址）或 suggestions[].token（POI 候选）用于下一步 select_address，由 select 返回正式的 address_id，再用于 preview_order 与 create_order。

参数

字段	类型	必填	默认	说明
`consent_grant_id`	string	是	—	用户授权 ID（`cg_` 前缀），标识已授权用户
`keyword`	string \| null	否	`null`	POI 搜索关键词；省略则只列出已保存地址，不返回 `suggestions`
`lat`	number \| null	否	`null`	用户当前纬度（GCJ-02）；启用 `distance_meters` 与 `nearest_address_id`，并为 POI 搜索提供坐标偏好
`lng`	number \| null	否	`null`	用户当前经度（GCJ-02）
`city`	string \| null	否	`null`	城市名，用于限定 POI 搜索范围；传入后优先于 `lat`/`lng` 决定搜索范围
`lang`	string	否	—	本次返回内容使用的语言，枚举 `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`；不传则用绑定时设定的语言（默认中文）
`include_chinese`	boolean	否	false	为 `true` 时响应同时返回中文原文（`<key>_zh`），见双语响应

除 consent_grant_id 外全部字段均为可选。仅当同时具备 keyword 与一个范围信号（lat+lng 坐标对，或可解析的 city）时才返回 POI suggestions；否则 suggestions 为空数组，只返回 saved_addresses。

{
  "saved_addresses": [
    {
      "address_id": "addr_8f3c...",
      "display_name": "武汉市洪山区光谷世界城",
      "address_detail": "3 号楼 101",
      "city": "武汉",
      "lat": 30.5,
      "lng": 114.4,
      "contact_name": "张三",
      "contact_phone_masked": "138****8000",
      "distance_meters": 120
    }
  ],
  "suggestions": [
    {
      "token": "sug_1a2b...",
      "display_name": "光谷世界城",
      "address": "武汉市洪山区珞喻路",
      "city": "武汉",
      "lat": 30.5,
      "lng": 114.4
    }
  ],
  "nearest_address_id": "addr_8f3c..."
}

字段	类型	说明
`saved_addresses`	array	已保存地址列表，按最近使用优先排序
`saved_addresses[].address_id`	string	网关地址 ID（`addr_` 前缀），原样传给 `select_address` 或 `preview_order`
`saved_addresses[].display_name`	string	地址显示名
`saved_addresses[].address_detail`	string	门牌 / 楼层等详情
`saved_addresses[].city`	string	城市名（如「武汉」）。早期创建的地址为空串，表示未知，不代表在其他城市。
`saved_addresses[].lat`	number \| null	纬度（GCJ-02）
`saved_addresses[].lng`	number \| null	经度（GCJ-02）
`saved_addresses[].contact_name`	string \| null	收货人姓名
`saved_addresses[].contact_phone_masked`	string	收货人手机号（脱敏，如 `138****8000`）
`saved_addresses[].distance_meters`	integer \| null	与请求 `lat`/`lng` 的距离（米，整数）；未传坐标或该地址无坐标时为 `null`
`suggestions`	array	POI 候选地址列表；仅在传 `keyword` 且范围可解析时非空
`suggestions[].token`	string	单次有效的建议 token，传给 `select_address` 的 `suggestion_token` 以落地为已保存地址
`suggestions[].display_name`	string	POI 名称
`suggestions[].address`	string	POI 详细地址文案
`suggestions[].city`	string	POI 所在城市名（如「武汉」）
`suggestions[].lat`	number \| null	POI 纬度（GCJ-02）
`suggestions[].lng`	number \| null	POI 经度（GCJ-02）
`nearest_address_id`	string \| null	距请求坐标最近的已保存地址 ID；未传坐标或无可比对地址时为 `null`

使用 nearest_address_id 前务必核对对应地址的 distance_meters：若连最近的地址都很远（如几十公里，说明所有已保存地址都在另一个城市），不要自动选用，应让用户确认或改用 keyword 搜新地址。

错误码

code	说明
`CONSENT_GRANT_REQUIRED` / `CONSENT_GRANT_INVALID` / `CONSENT_GRANT_EXPIRED`	缺少、无效或已过期的用户授权
`CAP_NOT_BOUND` / `CONSENT_GRANT_WRONG_CAP`	Agent 未开通该能力，或授权与能力不匹配

完整错误码见错误处理。

调用示例

{
  "name": "search_addresses",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "keyword": "光谷世界城",
    "lat": 30.5,
    "lng": 114.4,
    "city": "武汉"
  }
}

概览

接入

指南

授权

店铺

地址

下单

支付

search_addresses