willhaben-搜索

在奥地利最大的在线市场willhaben.at上，使用AI驱动的语义搜索来搜索和浏览列表。

API基础信息

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

无需身份验证。所有端点均返回JSON格式数据。

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

速率限制：全局50次/分钟，搜索/建议10次/分钟。

典型工作流程

1. 1. 找到正确的类别：使用GET /api/categories/suggest?q=...
2. 搜索列表：使用GET /api/search?categoryId=...&query=...
3. 获取列表详情：使用GET /api/listings/:id

端点

建议类别（语义搜索）

GET /api/categories/suggest?q=<查询词>

使用AI为用户意图找到最佳类别。当您不知道要搜索哪个类别时，从这里开始。

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

响应：
json
{
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=<查询词>

在类别内进行语义搜索。理解自然语言查询。

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

查询参数：

响应：
json
{
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

获取特定列表的完整详情，包括可比定价上下文。

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

响应：
json
{
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。

浏览类别

根类别：
bash
curl https://api.nochda.at/api/categories

所有类别（扁平列表）：
bash
curl https://api.nochda.at/api/categories/all

类别的子类别：
bash
curl https://api.nochda.at/api/categories/123/children

返回{ parent: {...}, children: [...] }。

按名称搜索类别：
bash
curl https://api.nochda.at/api/categories/search?q=auto

名称重复的类别包含disambiguatedLabel（例如PKW (Auto/Motorrad)）。

所有类别对象包含：id、label、parentCategoryId、image。

错误处理

错误返回JSON格式：{error: 描述}。

注意事项

• - 所有价格均为欧元
• 搜索由AI驱动——像舒适的阅读扶手椅这样的自然语言查询效果很好
• 类别形成层级结构（根→子类别）；搜索包含所有子类别
• 始终将用户链接到url字段，以便他们可以在willhaben上查看完整列表