# Willhaben Similar Listings API Documentation

<p>Scrappa's `GET /api/willhaben/similar` endpoint is the Willhaben Similar Listings API documentation page for developers who need content-based listing recommendations as structured JSON.

    ## What this endpoint returns

    Pass a listing id together with its agency id and the response returns comparable Austrian listings. Recommendations are chosen from the content of the reference listing, not from the requesting user's history. Because requests are served from rotating proxy exits, treat the ordering as indicative rather than byte-stable.

    ## How to use it

    Use this to enrich a listing page after [Listing Details](/docs/willhaben-api/willhaben_details), and fall back to [Willhaben Search](/docs/willhaben-api/willhaben_search) with the same vertical when you need full result counts and facets.</p>

- **Documentation:** [https://scrappa.co/docs/willhaben-api/willhaben_similar](https://scrappa.co/docs/willhaben-api/willhaben_similar)
- **API group:** Willhaben API
- **Endpoint:** `GET https://scrappa.co/api/willhaben/similar`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `adId` | integer | Yes | Reference listing id. |
| `orgId` | integer | Yes | Agency id of the reference listing. |

## Example response

```json
{
    "data": {
        "adId": 2059921960,
        "orgId": 28894161,
        "results": [
            {
                "id": "2059921961",
                "title": "Helle 3-Zimmer-Wohnung im 10. Bezirk"
            }
        ]
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | The requested listing, agency or seller does not exist upstream. Non-billable, and not retryable: a different exit returns the same 404. |
| 422 | Validation Error | A query parameter failed validation — a missing required id, an unknown vertical, or a value outside the documented range. Messages are per field in Laravel's standard wording, so the accepted vertical ids are published on the `vertical` parameter of each page rather than repeated in the message. Non-billable. |
| 503 | Upstream Rejected The Request | Willhaben answered with a JSON application error — an invalid filter, or a sort id that the vertical does not offer. Non-billable, and not retryable: the same request fails the same way on every exit. Published as 503 because SanitizeApiErrorResponse rewrites every upstream 502 before the response leaves the app; branch on `meta.retryable` rather than on the status code. |
| 503 | Temporarily Unavailable | Willhaben could not be reached at all: no exit was available, the transport failed, the edge refused every exit, or every exit was rate limited. All of these rotate and retry, so this row is always retryable. The `failure_type` says which one happened — `upstream_unreachable`, `transport_error`, `edge_blocked`, `rate_limited` or `attempts_exhausted` — so a caller can tell a dead provider from a throttled one. Non-billable; a later request with a fresh pool fetch is worth making. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)