# WG-Gesucht Search

Search the live WG-Gesucht rental catalog. categories, city_id, and rent_types are all required: the platform returns an error when any one is missing. This endpoint returns one summary card per listing and never fetches full detail, so a search always costs exactly one upstream lookup. Pass the city_id and rent_types you searched with back to /listings to hydrate specific offers.

- **Documentation:** [https://scrappa.co/docs/wg-gesucht-api/wg_gesucht_search](https://scrappa.co/docs/wg-gesucht-api/wg_gesucht_search)
- **API group:** WG-Gesucht API
- **Endpoint:** `GET https://scrappa.co/api/wg-gesucht/search`

## 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 |
| --- | --- | --- | --- |
| `categories` | integer | Yes | Listing type. 0 = WG-Zimmer, 1 = 1-Zimmer-Wohnung, 2 = Wohnung, 3 = Haus. Required. |
| `city_id` | integer | Yes | WG-Gesucht city id, from the locations endpoint. Required. |
| `rent_types` | integer | Yes | 0 = all, 1 = fixed term, 2 = unlimited term, 3 = short term or nightly. Required. |
| `page` | integer | No | 1-based page number. Default 1. |
| `limit` | integer | No | Cards per page, 1-111. Default 30. |
| `ot` | string | No | Comma-separated district ids from the districts endpoint. Exact and additive. This is the reliable way to scope a search to districts. |
| `sort_column` | integer | No | 0 relevance, 1 date created, 2 rooms, 4 rent price, 5 floor area, 6 available from. |
| `sort_order` | string | No | Empty for ascending, 1 for descending. This value space is specific to this API. |
| `rMin` | number | No | Minimum total monthly rent in euros. |
| `rMax` | number | No | Maximum total monthly rent in euros. |
| `sMin` | number | No | Minimum usable area in square metres. |
| `sMax` | number | No | Maximum usable area in square metres. |
| `rmMin` | number | No | Minimum number of rooms. |
| `rmMax` | number | No | Maximum number of rooms. |
| `dFr` | string | No | Earliest move-in date as YYYY-MM-DD. |
| `dTo` | string | No | Latest move-out date as YYYY-MM-DD. |
| `fur` | boolean | No | Only furnished listings. |
| `kit` | boolean | No | Only listings with their own or a shared kitchen. |
| `bal` | boolean | No | Only listings with a balcony. |
| `ff` | boolean | No | Only listings in a building with a lift. |
| `gar` | boolean | No | Only listings with a garage. |
| `pet` | boolean | No | Only listings where pets are allowed. |
| `pets_present` | boolean | No | Exclude listings with pets already living there. |
| `img_only` | boolean | No | Only listings that have photos. |
| `radDis` | number | No | Radius in metres around an address. Requires radAdd, radLat, and radLng together; a radius alone is ignored and widens the query to the whole city. |
| `radAdd` | string | No | Address the radius is measured from. |
| `radLat` | number | No | Latitude of the radius centre. |
| `radLng` | number | No | Longitude of the radius centre. |
| `aMin` | number | No | Lowest flatmate age to include. This is an age, not an area. |
| `aMax` | number | No | Highest flatmate age to include. This is an age, not an area. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/wg-gesucht/search?categories=2&city_id=8&rent_types=2&limit=3"
```

## Example response

```json
{
    "success": true,
    "data": {
        "offers": [
            {
                "offer_id": 13841674,
                "offer_title": "Helle 2-Zimmer-Wohnung in Prenzlauer Berg",
                "category": 2,
                "category_label": "Wohnung",
                "city_id": 8,
                "total_costs": 850,
                "number_of_rooms": 2,
                "property_size": 52,
                "district_custom": "Prenzlauer Berg",
                "postcode": "10405",
                "available_from_date": "2026-11-01T00:00:00+00:00",
                "thumb": "https://img.wg-gesucht.de/media/up/abc123.jpg"
            }
        ],
        "total_items": 185,
        "page": 1,
        "number_of_pages": 7,
        "counts_by_category": [
            404,
            404,
            185,
            36
        ],
        "images_base_url": "https://img.wg-gesucht.de/"
    },
    "meta": {
        "duration_ms": 412,
        "endpoint_family": "search"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | The requested query combination is not served. This response is not billable. |
| 422 | Validation Error | A public parameter is invalid, including a missing scope field or a category and rent type the platform does not serve. This response is not billable. |
| 503 | Service Unavailable | The service could not obtain a complete result. This response is not billable. |

## 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)