📖 禾搜开放 API 文档

GET /api/search 核心

BM25 全文搜索，支持 site: 指令、域名过滤、分类筛选。

参数

返回字段

{
  "query": "沂蒙路",
  "took": 12,
  "total": 83995,
  "page": 1,
  "pages": 14000,
  "results": [{ "title":"...", "url":"...", "domain":"...", "snippet":"...", "score":23.4, "jump_url":"/s/xxx" }],
  "related": ["沂蒙精神", "沂蒙老区"],
  "related_content": [{"title":"...", "url":"...", "from_kw":"沂蒙精神"}],
  "pois": [{ "name":"沂蒙路", "city":"临沂市", "province":"山东省", "kind":"路", "address":"兰山区", "lat":35.078, "lon":118.338 }],
  "poi_total": 7,
  "ads": {"top":[], "bottom":[]}
}

调用样例

curl -s "http://search.cybq.com/api/search?q=沂蒙路" \
  -H "X-API-Key: 你的Key"

# Python
import requests
r = requests.get("http://search.cybq.com/api/search",
    params={"q":"农业", "page":1, "per_page":10},
    headers={"X-API-Key":"你的Key"})
data = r.json()

GET /api/poi-list 新增

按城市 + 类别分页列出 POI 地点，用于搜索结果侧栏"📍 本地地点"展示。

参数

返回示例

{
  "ok": true,
  "city": "临沂市",
  "kind": "路",
  "page": 1,
  "per_page": 5,
  "total": 747,
  "pages": 150,
  "items": [
    {"name":"安居路", "city":"临沂市", "province":"山东省", "kind":"路", "address":"", "lat":35.080, "lon":118.390},
    {"name":"沂河东路", "city":"临沂市", "province":"山东省", "kind":"路", "address":"", "lat":35.020, "lon":118.415}
  ]
}

调用样例

curl -s "http://search.cybq.com/api/poi-list?city=临沂市&kind=路&page=1&per_page=10"

# JavaScript
fetch("/api/poi-list?city=临沂市&kind=路&page=1&per_page=10")
  .then(r => r.json()).then(console.log)

GET /api/geocode

地名→坐标。支持城市、区县、街道、路、小区、商场。

参数

返回示例

{ "ok": true, "name":"临沂市", "city":"临沂市", "province":"山东省",
    "kind":"城市", "lat":35.06, "lon":118.35 }

调用样例

curl -s "http://search.cybq.com/api/geocode?q=沂蒙路"

# 地图定位（前端自动调用，定位搜索词坐标）
fetch("/api/geocode?q=" + encodeURIComponent(searchWord))

GET /api/geo-ip

根据 IP 返回城市（用于未搜关键词时自动定位用户所在城市）。

返回示例

{ "ok": true, "city":"临沂市", "region":"山东" }

GET /api/hotwords

公开热搜词（首页快捷入口），10 分钟缓存。

参数

返回示例

{ "items": [
    {"word":"临沂天气", "heat":86832},
    {"word":"农业补贴", "heat":45200}
]}

调用样例

curl -s "http://search.cybq.com/api/hotwords?limit=10"

GET /api/wordnav

词库导航：8 个通用分类 + 16 个行业大类，每类取 N 个高频词。

返回示例

{ "categories": [
    {"type":"common", "name":"农业农资", "words":["小麦价格","化肥厂家","种子..."]},
    {"type":"industry", "name":"建材家居", "words":["瓷砖批发","地板品牌"...]}
]}

调用样例

curl -s "http://search.cybq.com/api/wordnav"

GET /diqu

地区行业导航页：全国省→市全量内链 + 行业词表（爬虫入口页）。

前端访问：https://search.cybq.com/diqu

返回 HTML 页面，包含所有省份、城市、行业分类的可点击链接。

GET /p/{省}/{市}/{地点} POI

地点详情页：某城市某地点的行业查询页（如 /p/山东省/临沂市/沂蒙路）。

返回内容

• 地点基本信息（地址、电话、类型、坐标）
• 该地点的行业入口（装修/家政/搬家等）
• 附近地点推荐
• 嵌入本地矢量地图
• 相关搜索结果

调用样例

curl -s "http://search.cybq.com/p/山东省/临沂市/沂蒙路"
# 浏览器直接打开：
# https://search.cybq.com/p/山东省/临沂市/沂蒙路

GET /p/{省}/{市}

城市 POI 总览页：列出该城市所有路/小区/商超/建筑/公司商户。

调用样例

curl -s "http://search.cybq.com/p/山东省/临沂市"
# 浏览器打开：
# https://search.cybq.com/p/山东省/临沂市

GET Sitemap

搜索引擎索引：

🔄 典型调用流程

场景：用户在搜索框输入"沂蒙路"，获取搜索结果 + POI 列表

步骤 1: 搜索
GET /api/search?q=沂蒙路&page=1&per_page=6
→ 返回 results（网页结果）+ pois（POI 地点）

步骤 2: 侧栏 POI 列表（自动触发）
GET /api/poi-list?city=临沂市&kind=路&page=1&per_page=20
→ 返回 POI 列表 + 分页

步骤 3: 点击某个 POI（如"沂蒙路"）
浏览器跳转 → /p/山东省/临沂市/沂蒙路
→ 地点详情页（行业入口 + 地图 + 附近地点）

步骤 4: 地图定位（前端自动）
GET /api/geocode?q=沂蒙路
→ 返回坐标 {lat, lon}，地图 marker 定位

📋 各模式速查表

⚠️ 注意事项

• CDN 缓存：前端静态资源（index.html）经过 Cloudflare，返回可能延迟几分钟
• 搜索缓存：同参数 5 分钟内命中 Redis 缓存，直接返回
• 并发限制：搜索有并发闸门，高峰时返回 503 "检索排队已满"，请 3 秒后重试
• POI 数据：来自高德/OSM，每 3 小时更新一轮；新增 POI 需等待深挖任务
• 极限词过滤：结果中含极限词（最/第一/顶级等）会被自动替换或隐藏
• API Key：知识付费用户每次搜索扣费；游客免费不限