willhaben-search

使用 AI 驱动的语义搜索，在 willhaben.at（奥地利最大的在线交易平台）上搜索和浏览商品列表。

API 基础信息

基础 URL：https://api.nochda.at

无需身份认证。所有接口均返回 JSON 格式数据。

curl "https://api.nochda.at/api/health"

速率限制：全局 50 次请求/分钟，search/suggest 接口为 10 次请求/分钟。

典型工作流程

1. 查找合适类目：使用 GET /api/categories/suggest?q=...
2. 搜索商品列表：使用 GET /api/search?categoryId=...&query=...
3. 获取商品详情：使用 GET /api/listings/:id

接口列表

类目建议（语义化）

GET /api/categories/suggest?q=

利用 AI 技术识别用户搜索意图，推荐最匹配的类目。当你不确定应选择哪个类目进行搜索时，请从此接口开始。

curl "https://api.nochda.at/api/categories/suggest?q=mountain%20bike"

响应示例：

{
  "suggestions": [
    {"id": 4552, "label": "Fahrräder", "parentLabel": "Sport/Sportgeräte", "score": 1.0},
    {"id": 2145, "label": "Mountainbikes", "parentLabel": "Fahrräder", "score": 0.82}
  ]
}

请将最佳匹配建议项中的 id 作为后续搜索接口的 categoryId 参数值。该接口最多返回 5 条建议，按相关性得分（0–1）降序排列。

搜索商品列表

GET /api/search?categoryId=&query=

在指定类目内执行语义化搜索，支持自然语言查询。

curl "https://api.nochda.at/api/search?categoryId=4552&query=full%20suspension%20trail%20bike&maxPrice=2000&recentDays=30"

查询参数：

响应示例：

{
  "results": [
    {
      "id": 12345,
      "title": "Giant Trance X 29 2024",
      "description": "Full suspension trail bike, excellent condition...",
      "price": 1800,
      "location": "Wien",
      "url": "https://willhaben.at/iad/kaufen-und-verkaufen/d/...",
      "images": ["https://cache.willhaben.at/...jpg"],
      "publishedAt": "2026-03-08T10:30:00Z",
      "similarity": 0.87
    }
  ],
  "totalCandidates": 85
}

结果按语义相关性排序。每条结果均包含指向原始 willhaben 商品页的直接 url 链接。单次响应最多返回 40 条结果。

获取商品详情

GET /api/listings/:id

获取指定商品的完整信息，包括可比价格参考上下文。

curl "https://api.nochda.at/api/listings/12345"

响应示例：

{
  "listing": {
    "id": 12345,
    "title": "Giant Trance X 29 2024",
    "description": "Full suspension trail bike, excellent condition...",
    "price": 1800,
    "location": "Wien",
    "url": "https://willhaben.at/iad/kaufen-und-verkaufen/d/...",
    "images": ["https://cache.willhaben.at/...jpg"],
    "publishedAt": "2026-03-08T10:30:00Z",
    "categoryLabel": "Fahrräder"
  },
  "compAnalysis": {
    "avgPrice": 2100,
    "medianPrice": 1950,
    "compCount": 30
  }
}

compAnalysis 将当前商品价格与同一类目下最相似的 30 个商品进行对比分析。若数据不足，该字段可能为 null。

类目浏览

根类目列表：

curl "https://api.nochda.at/api/categories"

全部类目（扁平化列表）：

curl "https://api.nochda.at/api/categories/all"

某类目的子类目：

curl "https://api.nochda.at/api/categories/123/children"

返回格式：{ "parent": {...}, "children": [...] }。

按名称搜索类目：

curl "https://api.nochda.at/api/categories/search?q=auto"

对于存在重名的类目，会额外提供 disambiguatedLabel 字段用于区分（例如："PKW (Auto/Motorrad)"）。

所有类目对象均包含以下字段：id、label、parentCategoryId、image。

错误处理

错误响应均为 JSON 格式：{"error": "Description"}。

注意事项

• 所有价格单位均为 EUR
• 搜索功能由 AI 驱动，支持自然语言查询（例如：“cozy armchair for reading”效果良好）
• 类目结构为树形层级（根类目 → 子类目），搜索时默认包含所有后代类目
• 请始终引导用户跳转至结果中的 url 字段所指向的页面，以便其在 willhaben 上查看完整商品信息