# WG-Gesucht Scraper - Rental Listings & Housing Requests (`igolaizola/wg-gesucht-scraper`) Actor

Search rooms, apartments, houses, and housing requests on wg-gesucht.de across Germany and nearby European countries by location, rent, dates, size, amenities, and flatshare preferences. Export JSON, CSV, or Excel data, connect through the API or MCP, compare markets, and find your next home faster.

- **URL**: https://apify.com/igolaizola/wg-gesucht-scraper.md
- **Developed by:** [Iñigo Garcia Olaizola](https://apify.com/igolaizola) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## WG-Gesucht Rental Listings & Housing Requests

Find rooms, apartments, houses, and housing requests on wg-gesucht.de across Germany and nearby European countries with practical filters for location, budget, dates, size, amenities, and flatshare preferences. Collect clean rental-market data for relocation, property research, price comparisons, and housing alerts.

### 🚀 Get started

1. Open the Actor in Apify Console and choose **Try for free**.
2. Keep the prefilled location `Berlin`, or enter another city or area.
3. Select the listing type and add the filters that matter to you.
4. Start the run and review the results in the Dataset tab.

The default search looks for active shared-room offers in Berlin and returns up to 100 results. Use `maxItems: 0` when you want all results allowed by your run.

You can start the Actor from Apify Console, the Apify API, or an automation connected to your rental-research workflow.

### 🎯 What you can find

- Available rooms, apartments, houses, and short-term rentals
- Housing requests from people looking for a home
- Listings filtered by rent, size, rooms, dates, furnishing, pets, and amenities
- Flatshares matched by household preferences, smoking rules, gender, and suitability
- New offers for relocation research, market monitoring, and price comparisons
- Public listing links, images, location information, costs, and published contact details

### 🧭 Choose a search area

Use one of these friendly search options:

- `location`: enter a city, district, or place such as `Berlin` or `Munich`. The Actor resolves the name to the closest matching search area.
- `latitude`, `longitude`, and `radiusKm`: search around a map point, such as a university, workplace, or neighborhood. When coordinates are provided, this search takes precedence over `location`.

The default location is `Berlin`, so a new run is ready to return results without extra setup.

### 📝 Input parameters

All fields are optional except `type`. Leave a filter empty when you do not want to restrict the search.

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `maxItems` | integer | `100` | Maximum number of results. `0` collects all results allowed by the run. |
| `location` | text | `Berlin` | City, district, or place to search. Leave empty when using coordinates. |
| `country` | select | — | Limit location matching to Germany (`de`), Austria (`at`), Belgium (`be`), Switzerland (`ch`), Czechia (`cz`), Denmark (`dk`), France (`fr`), Luxembourg (`lu`), the Netherlands (`nl`), or Poland (`pl`), or leave as Any. |
| `sortBy` | select | — | Sort by newest, oldest, lowest rent, highest rent, smallest size, or largest size. |
| `fetchDetails` | boolean | `false` | Add the listing’s extended description, amenities, property information, and published contact details. |
| `type` | select | `offers` | Choose available listings (`offers`) or housing requests (`requests`). |
| `propertyType` | select | `shared-room` | Shared room, one-room apartment, apartment, or house. |
| `rentalPeriod` | select | `any` | Any period, long-term, short-term, or daily rental. |
| `language` | select | `de` | Preferred listing language: German or English. |
| `latitude` | number | — | Map latitude from `-90` to `90`. Use together with `longitude` and `radiusKm`. |
| `longitude` | number | — | Map longitude from `-180` to `180`. Use together with `latitude` and `radiusKm`. |
| `radiusKm` | integer | — | Search distance in kilometres around the coordinates. |
| `includeDeactivated` | boolean | `false` | Include offers that are no longer active. |
| `minRent` | integer | — | Minimum rent or total cost. |
| `maxRent` | integer | — | Maximum rent or total cost. |
| `minRooms` | number | — | Minimum number of rooms, from 2 to 9.5. Half-room values are supported. |
| `maxRooms` | number | — | Maximum number of rooms, from 2 to 9.5. Half-room values are supported. |
| `minSize` | integer | — | Minimum property size in square metres. |
| `maxSize` | integer | — | Maximum property size in square metres. |
| `ageMin` | integer | — | Minimum household age preference. |
| `ageMax` | integer | — | Maximum household age preference. |
| `dateFrom` | date | — | Earliest desired move-in date, formatted as `YYYY-MM-DD`. |
| `dateTo` | date | — | Latest desired move-in date, formatted as `YYYY-MM-DD`. |
| `dateFromDeviation` | integer | — | Move-in date flexibility in days after the earliest date. |
| `dateToDeviation` | integer | — | Move-in date flexibility in days before or after the latest date. |
| `newOffersSince` | select | — | Show listings added in the last 3 days, week, 2 or 3 weeks, month, 2 months, or 3 months. |
| `furnished` | select | — | Any furnishing, furnished, unfurnished, or partly furnished. |
| `kitchen` | select | — | Any kitchen status, kitchen present, or no kitchen. |
| `hasBalcony` | boolean | `false` | Require a balcony or terrace. |
| `hasGarden` | boolean | `false` | Require a garden. |
| `hasKitchen` | boolean | `false` | Require a kitchen. |
| `accessible` | boolean | `false` | Require accessible features. |
| `imagesOnly` | boolean | `false` | Return only results with photos. |
| `onlineViewing` | boolean | `false` | Require online viewing availability. |
| `excludeContacted` | boolean | `false` | Exclude listings already contacted by the account. |
| `swap` | select | — | Any swap status, swap available, or no swap. |
| `swapOnly` | boolean | `false` | Limit results to listings offering a home swap. |
| `flatshareSuitability` | select | — | Any suitability, suitable, or not suitable for a flatshare. |
| `flatshareFriendly` | boolean | `false` | Prefer listings marked as suitable for flatsharing. |
| `flatshareTypes` | multi-select | — | Choose platform tags such as students-only, female-only, male-only, business-people, workers-only, trainees, seniors-only, with-children, communal, mixed-gender, varied-age, vegetarian-vegan, LGBTQIA-friendly, room-for-help, single-parents-only, internationals-welcome, inclusive, functional, new-flatshare, not-specified, and non-communal. |
| `petsAllowed` | boolean | `false` | Require a listing that allows pets. |
| `petPolicy` | select | — | Any pet policy, pets allowed, or pets not allowed. |
| `petsPresent` | select | — | Any status, pets present, or no pets present in the household. |
| `floorLevel` | select | — | Ground, first through fifth, higher than fifth, cellar, basement, raised ground floor, or loft/attic. |
| `gender` | multi-select | — | Preferred genders named by the listing: female, male, diverse, or unspecified. |
| `flatmateGender` | select | — | Gender of current flatmates: any, female, male, diverse, or unspecified. |
| `smoking` | select | — | Smoker or non-smoker preference. |
| `flatshareSmoking` | select | — | Smoking anywhere, in the own room, on the balcony, or not at all. |
| `myAge` | integer | — | Your age for flatshare matching. |
| `myGender` | select | — | Your gender for flatshare matching: female, male, diverse, or unspecified. |
| `minFlatshareSize` | integer | — | Minimum number of current flatmates. |
| `maxFlatshareSize` | integer | — | Maximum number of current flatmates. |

#### Example: Berlin room search

```json
{
  "location": "Berlin",
  "type": "offers",
  "propertyType": "shared-room",
  "rentalPeriod": "long-term",
  "maxRent": 850,
  "minSize": 12,
  "hasKitchen": true,
  "imagesOnly": true,
  "newOffersSince": "last-week",
  "sortBy": "newest",
  "maxItems": 50
}
```

#### Example: coordinate search near a workplace

```json
{
  "latitude": 52.520008,
  "longitude": 13.404954,
  "radiusKm": 5,
  "propertyType": "apartment",
  "minRooms": 2,
  "maxRooms": 3,
  "maxRent": 2200,
  "onlineViewing": true,
  "maxItems": 25
}
```

#### Example: housing request research

```json
{
  "type": "requests",
  "location": "Hamburg",
  "rentalPeriod": "long-term",
  "minSize": 15,
  "dateFrom": "2026-10-01",
  "dateFromDeviation": 14,
  "flatshareSuitability": "suitable",
  "sortBy": "newest",
  "maxItems": 100
}
```

### 📊 Output

Each result keeps the public listing information in a convenient, analysis-ready format.

| Field | Meaning |
| --- | --- |
| `offer_id` / `request_id` | Public listing or housing-request identifier, when available. |
| `offer_title` / `request_title` | Listing or request title. |
| `href` / `url` | Public page links. |
| `sized` / `small` / `thumb` | Available full-size and preview image links from the search results. |
| `town_name` / `city_name` / `country_code` | Town, city, and country. |
| `street` / `postcode` / `district_custom` | Published address and district information. |
| `geo_latitude` / `geo_longitude` | Published map coordinates. |
| `category` / `rent_type` | Property category and rental period. |
| `rent_costs` / `utility_costs` / `other_costs` / `total_costs` | Cost breakdown. |
| `property_size` / `number_of_rooms` | Size and room count. |
| `available_from_date` / `available_to_date` | Availability dates. |
| `furnished` / `garden` / `kitchen_availability` | Main property amenities. |
| `pets_allowed` / `online_tour` | Pet and online-viewing information. |
| `user_data.public_name` / `user_data.company_name` | Published contact name or company. |
| `offer_telephone` / `offer_mobile` | Published phone numbers, when provided. |
| `_details` | Extended information added when `fetchDetails` is enabled. |

Example result:

```json
{
  "offer_id": "13914534",
  "offer_title": "Bright room near Prenzlauer Berg",
  "url": "https://www.wg-gesucht.de/13914534.html",
  "city_name": "Berlin",
  "district_custom": "Prenzlauer Berg",
  "postcode": "10437",
  "property_size": "13",
  "rent_costs": "550",
  "total_costs": "550",
  "available_from_date": "15.09.2026",
  "furnished": "1",
  "pets_allowed": "1",
  "sized": "https://img.wg-gesucht.de/media/example.sized.jpg",
  "small": "https://img.wg-gesucht.de/media/example.small.jpg",
  "thumb": "https://img.wg-gesucht.de/media/example.thumb.jpg",
  "_details": {
    "description": "Quiet room in a friendly shared flat",
    "amenities": ["balcony", "washing machine"]
  }
}
```

### 💳 Pricing

Runs follow the pricing shown on the Actor page. Choosing more results or enabling extended details may use more of your run allowance, so start with a small limit while refining filters.

### 💡 Tips and common recipes

- Start with `maxItems: 10` while tuning filters, then increase it for a larger market view.
- Use `newOffersSince` together with `sortBy: "newest"` to monitor recent opportunities.
- Use `imagesOnly: true` when creating a visual housing catalogue.
- Use `type: "requests"` to find people seeking accommodation rather than available homes.
- Use coordinates and `radiusKm` to compare listings around a campus, office, or transit hub.
- Enable `fetchDetails` when descriptions and extended amenities matter.

### ⚖️ Legal and ethical considerations

- Use only information that is publicly available and follow WG-Gesucht’s terms and applicable laws.
- Do not use published contact details for unsolicited messages or bulk outreach.
- Do not use housing information for unlawful discrimination or sensitive profiling.
- Respect access limits, keep collected data secure, and remove personal data when it is no longer needed.
- This Actor is an independent tool and is not affiliated with or endorsed by WG-Gesucht.

### ❓ FAQ

#### Does the default input return data?

Yes. Berlin is prefilled, and the default search is configured for active shared-room offers.

#### Can I search with only a location?

Yes. Enter a city, district, or place in `location`. The Actor resolves it to the closest matching search area.

#### Can I search around coordinates?

Yes. Provide `latitude`, `longitude`, and `radiusKm` together. Coordinate searches take precedence over a named location.

#### What does `maxItems: 0` do?

It collects all results allowed by the run. Use a positive number when you want a predictable smaller result set.

#### Why are some contact or address fields empty?

WG-Gesucht only publishes information permitted by each advertiser’s privacy settings. Empty values are preserved as provided.

#### What does `fetchDetails` add?

It adds extended descriptions, amenities, property information, and published contact details where available. Individual missing details do not remove the original result.

#### Can I search housing requests?

Yes. Set `type` to `requests`; request results use request-specific fields where available.

### 🛟 Support

For questions, suggestions, or help with a run, contact [igolaizola.com/#contact](https://igolaizola.com/#contact).

# Actor input Schema

## `maxItems` (type: `integer`):

Maximum listings to return; 0 collects every available result.

## `location` (type: `string`):

Location name to search, such as Berlin or Munich. The actor resolves it automatically. Leave empty when using coordinates.

## `country` (type: `string`):

Limit location matching to a country when a name exists in multiple countries.

## `sortBy` (type: `string`):

Sort listings by newest, oldest, lowest rent, highest rent, smallest size, or largest size.

## `fetchDetails` (type: `boolean`):

Fetch one additional detail record per result and store it in \_details. This increases run time and PPE cost.

## `type` (type: `string`):

Search available listings or housing requests.

## `propertyType` (type: `string`):

Primary home type to search for.

## `rentalPeriod` (type: `string`):

Preferred rental period.

## `language` (type: `string`):

Language for translated listing text where available.

## `latitude` (type: `number`):

Center latitude for a coordinate search, from -90 to 90. Use together with longitude and radiusKm. Coordinates take precedence over Location.

## `longitude` (type: `number`):

Center longitude for a coordinate search, from -180 to 180. Use together with latitude and radiusKm.

## `radiusKm` (type: `integer`):

Search radius around the latitude/longitude point, in kilometres. Use with both coordinates.

## `includeDeactivated` (type: `boolean`):

Include listings marked inactive by the platform.

## `minRent` (type: `integer`):

Minimum advertised rent or total monthly cost, depending on listing type.

## `maxRent` (type: `integer`):

Maximum advertised rent or total monthly cost, depending on listing type.

## `minRooms` (type: `number`):

Minimum number of rooms from 2 to 9.5; half-room values are supported.

## `maxRooms` (type: `number`):

Maximum number of rooms from 2 to 9.5; half-room values are supported.

## `minSize` (type: `integer`):

Minimum property size in square metres.

## `maxSize` (type: `integer`):

Maximum property size in square metres.

## `ageMin` (type: `integer`):

Minimum age requested by the flatshare or listing.

## `ageMax` (type: `integer`):

Maximum age requested by the flatshare or listing.

## `dateFrom` (type: `string`):

Earliest desired move-in date (YYYY-MM-DD).

## `dateTo` (type: `string`):

Latest desired move-out date (YYYY-MM-DD).

## `dateFromDeviation` (type: `integer`):

Optional number of days of flexibility around the start date.

## `dateToDeviation` (type: `integer`):

Optional number of days of flexibility around the end date.

## `newOffersSince` (type: `string`):

Only include listings added within the selected recent period.

## `furnished` (type: `string`):

Preferred furnishing state.

## `kitchen` (type: `string`):

Whether a kitchen is present.

## `hasBalcony` (type: `boolean`):

Only listings with a balcony or terrace.

## `hasGarden` (type: `boolean`):

Only listings with a garden.

## `hasKitchen` (type: `boolean`):

Only listings with a kitchen. Use Kitchen for an explicit yes or no choice.

## `accessible` (type: `boolean`):

Only listings with accessibility features.

## `imagesOnly` (type: `boolean`):

Only listings that include images.

## `onlineViewing` (type: `boolean`):

Only listings offering online viewing.

## `excludeContacted` (type: `boolean`):

Exclude listings already contacted by the account.

## `swap` (type: `string`):

Filter listings by apartment-swap availability.

## `swapOnly` (type: `boolean`):

Only listings available for an apartment swap. Use Swap preference for an explicit choice.

## `flatshareSuitability` (type: `string`):

Whether the listing is marked as suitable for a flatshare.

## `flatshareFriendly` (type: `boolean`):

Only listings marked as flatshare friendly. Use Flatshare suitability for an explicit choice.

## `petsAllowed` (type: `boolean`):

Only listings that allow pets. Use Pet policy for an explicit choice.

## `petPolicy` (type: `string`):

Filter whether pets are allowed.

## `petsPresent` (type: `string`):

Filter whether pets are already present in the household.

## `floorLevel` (type: `string`):

Choose a platform floor category: ground, 1st, 2nd, 3rd, 4th, 5th, higher-than-5th, cellar, basement, raised-ground-floor, or loft-attic.

## `gender` (type: `array`):

Select one or more genders the listing is seeking: female, male, diverse, or unspecified.

## `flatmateGender` (type: `string`):

Filter by the gender of the flatmates already living in the household.

## `smoking` (type: `string`):

For housing requests, choose whether the applicant smokes.

## `flatshareSmoking` (type: `string`):

Where smoking is acceptable in the existing flatshare: anywhere, in own room, on balcony, or not at all.

## `flatshareTypes` (type: `array`):

Select one or more flatshare tags exposed by WG-Gesucht.

## `myAge` (type: `integer`):

Your age for flatshare matching.

## `myGender` (type: `string`):

Your gender for flatshare matching.

## `minFlatshareSize` (type: `integer`):

Minimum number of people already living in the flatshare.

## `maxFlatshareSize` (type: `integer`):

Maximum number of people already living in the flatshare.

## Actor input object example

```json
{
  "maxItems": 100,
  "location": "Berlin",
  "country": "",
  "sortBy": "",
  "fetchDetails": false,
  "type": "offers",
  "propertyType": "shared-room",
  "rentalPeriod": "any",
  "language": "de",
  "includeDeactivated": false,
  "newOffersSince": "",
  "furnished": "",
  "kitchen": "",
  "hasBalcony": false,
  "hasGarden": false,
  "hasKitchen": false,
  "accessible": false,
  "imagesOnly": false,
  "onlineViewing": false,
  "excludeContacted": false,
  "swap": "",
  "swapOnly": false,
  "flatshareSuitability": "",
  "flatshareFriendly": false,
  "petsAllowed": false,
  "petPolicy": "",
  "petsPresent": "",
  "floorLevel": "",
  "flatmateGender": "",
  "smoking": "",
  "flatshareSmoking": "",
  "myGender": ""
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "location": "Berlin"
};

// Run the Actor and wait for it to finish
const run = await client.actor("igolaizola/wg-gesucht-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "location": "Berlin" }

# Run the Actor and wait for it to finish
run = client.actor("igolaizola/wg-gesucht-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "location": "Berlin"
}' |
apify call igolaizola/wg-gesucht-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,igolaizola/wg-gesucht-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zKhDRw1wPkBj7Oucm/builds/e2FnBWLJBJW8YdEop/openapi.json