{"skill":{"slug":"willhaben-search","displayName":"Willhaben Search","summary":"Willhaben marketplace search API for finding listings, browsing categories, and getting listing details on Austria's largest classifieds platform.","description":"---\nname: willhaben-search\ndescription: Willhaben marketplace search API for finding listings, browsing categories, and getting listing details on Austria's largest classifieds platform.\nhomepage: https://api.nochda.at\nmetadata: {\"clawdbot\":{\"emoji\":\"🔍\"}}\n---\n\n# willhaben-search\n\nSearch and browse listings on willhaben.at — Austria's largest online marketplace — using AI-powered semantic search.\n\n## API Basics\n\nBase URL: `https://api.nochda.at`\n\nNo authentication required. All endpoints return JSON.\n\n```bash\ncurl \"https://api.nochda.at/api/health\"\n```\n\nRate limits: 50 req/min global, 10 req/min for search/suggest.\n\n## Typical Workflow\n\n1. **Find the right category** with `GET /api/categories/suggest?q=...`\n2. **Search listings** with `GET /api/search?categoryId=...&query=...`\n3. **Get listing details** with `GET /api/listings/:id`\n\n## Endpoints\n\n### Suggest Categories (Semantic)\n\n`GET /api/categories/suggest?q=<query>`\n\nFind the best category for a user's intent using AI. Start here when you don't know which category to search in.\n\n```bash\ncurl \"https://api.nochda.at/api/categories/suggest?q=mountain%20bike\"\n```\n\n**Response:**\n```json\n{\n  \"suggestions\": [\n    {\"id\": 4552, \"label\": \"Fahrräder\", \"parentLabel\": \"Sport/Sportgeräte\", \"score\": 1.0},\n    {\"id\": 2145, \"label\": \"Mountainbikes\", \"parentLabel\": \"Fahrräder\", \"score\": 0.82}\n  ]\n}\n```\n\nUse the `id` of the best-matching suggestion as `categoryId` in search. Returns up to 5 suggestions ranked by relevance (score 0–1).\n\n---\n\n### Search Listings\n\n`GET /api/search?categoryId=<id>&query=<query>`\n\nSemantic search within a category. Understands natural language queries.\n\n```bash\ncurl \"https://api.nochda.at/api/search?categoryId=4552&query=full%20suspension%20trail%20bike&maxPrice=2000&recentDays=30\"\n```\n\n**Query Parameters:**\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `categoryId` | Yes | Category ID (from suggest or browse) |\n| `query` | Yes | Natural language search (max 500 chars) |\n| `maxPrice` | No | Maximum price in EUR |\n| `recentDays` | No | Only show listings from the last N days |\n\n**Response:**\n```json\n{\n  \"results\": [\n    {\n      \"id\": 12345,\n      \"title\": \"Giant Trance X 29 2024\",\n      \"description\": \"Full suspension trail bike, excellent condition...\",\n      \"price\": 1800,\n      \"location\": \"Wien\",\n      \"url\": \"https://willhaben.at/iad/kaufen-und-verkaufen/d/...\",\n      \"images\": [\"https://cache.willhaben.at/...jpg\"],\n      \"publishedAt\": \"2026-03-08T10:30:00Z\",\n      \"similarity\": 0.87\n    }\n  ],\n  \"totalCandidates\": 85\n}\n```\n\nResults are ranked by semantic relevance. Each result includes a direct `url` link to the original willhaben listing. Returns up to 40 results.\n\n---\n\n### Get Listing Details\n\n`GET /api/listings/:id`\n\nFull details for a specific listing including comparable pricing context.\n\n```bash\ncurl \"https://api.nochda.at/api/listings/12345\"\n```\n\n**Response:**\n```json\n{\n  \"listing\": {\n    \"id\": 12345,\n    \"title\": \"Giant Trance X 29 2024\",\n    \"description\": \"Full suspension trail bike, excellent condition...\",\n    \"price\": 1800,\n    \"location\": \"Wien\",\n    \"url\": \"https://willhaben.at/iad/kaufen-und-verkaufen/d/...\",\n    \"images\": [\"https://cache.willhaben.at/...jpg\"],\n    \"publishedAt\": \"2026-03-08T10:30:00Z\",\n    \"categoryLabel\": \"Fahrräder\"\n  },\n  \"compAnalysis\": {\n    \"avgPrice\": 2100,\n    \"medianPrice\": 1950,\n    \"compCount\": 30\n  }\n}\n```\n\n`compAnalysis` compares the listing's price against the 30 most similar listings in the same category. It can be `null` if not enough data is available.\n\n---\n\n### Browse Categories\n\n**Root categories:**\n```bash\ncurl \"https://api.nochda.at/api/categories\"\n```\n\n**All categories (flat list):**\n```bash\ncurl \"https://api.nochda.at/api/categories/all\"\n```\n\n**Children of a category:**\n```bash\ncurl \"https://api.nochda.at/api/categories/123/children\"\n```\n\nReturns `{ \"parent\": {...}, \"children\": [...] }`.\n\n**Search categories by name:**\n```bash\ncurl \"https://api.nochda.at/api/categories/search?q=auto\"\n```\n\nCategories with duplicate names include a `disambiguatedLabel` (e.g. `\"PKW (Auto/Motorrad)\"`).\n\nAll category objects have: `id`, `label`, `parentCategoryId`, `image`.\n\n## Error Handling\n\nErrors return JSON: `{\"error\": \"Description\"}`.\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Invalid or missing parameters |\n| 404 | Resource not found |\n| 429 | Rate limited — retry after `Retry-After` header value |\n| 500 | Server error |\n\n## Notes\n\n- All prices are in EUR\n- Search is AI-powered — natural language queries like \"cozy armchair for reading\" work well\n- Categories form a hierarchy (root → children); search includes all descendant categories\n- Always link users to the `url` field so they can view the full listing on willhaben","tags":{"latest":"0.0.2"},"stats":{"comments":0,"downloads":546,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":2},"createdAt":1773118971621,"updatedAt":1778491799807},"latestVersion":{"version":"0.0.2","createdAt":1773119791628,"changelog":"- Changed the listings search endpoint from POST /api/search to GET /api/search with query parameters.\n- Updated documentation and examples to reflect the GET-based search endpoint usage.\n- No changes to endpoint parameters or response formats.\n- Other endpoints and overall functionality remain unchanged.","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"saimo","userId":"s177hj95p152wp1917kk5mtz5983ycmb","displayName":"Saimo","image":"https://avatars.githubusercontent.com/u/5740385?v=4"},"moderation":null}