搜索API对接指南-02-搜索建议与即时搜索

本篇面向前端联想词/搜索框团队，独立阅读 GET /search/suggestions 与 GET /search/instant。

搜索接口

3.7 搜索建议接口

• 端点: GET /search/suggestions
• 描述: 返回搜索建议（自动补全/热词），支持多语言。

查询参数

参数	类型	必填	默认值	描述
q	string	Y	-	查询字符串（至少 1 个字符）
size	integer	N	10	返回建议数量（1-50）
language	string	N	en	请求语言，如 zh / en / ar / ru，用于路由到对应语种 suggestion 索引
debug	bool	N	false	是否开启调试（目前主要用于排查 suggestion 排序与语言解析）

租户标识：同 -01-搜索接口，通过请求头 X-Tenant-ID 或 query 参数 tenant_id 传递。

响应示例

{
  "query": "iph",
  "language": "en",
  "resolved_language": "en",
  "suggestions": [
    {
      "text": "iphone 15",
      "lang": "en",
      "score": 12.37,
      "rank_score": 5.1,
      "sources": ["query_log", "qanchor"],
      "lang_source": "log_field",
      "lang_confidence": 1.0,
      "lang_conflict": false
    }
  ],
  "took_ms": 12
}

请求示例

curl "http://localhost:6002/search/suggestions?q=芭&size=5&language=zh" \
  -H "X-Tenant-ID: 162"

3.8 即时搜索接口

⚠️ 当前版本未开放该能力。接口会明确返回 501 Not Implemented，避免误用未完成实现。

• 端点: GET /search/instant
• 描述: 即时搜索预留端点，后续会在独立实现完成后开放。

查询参数

参数	类型	必填	默认值	描述
q	string	Y	-	搜索查询（至少 2 个字符）
size	integer	N	5	返回结果数量（1-20）

请求示例

curl "http://localhost:6002/search/instant?q=玩具&size=5"

当前响应

{
  "error": "/search/instant is not implemented yet. Use POST /search/ for production traffic.",
  "status_code": 501
}