# WG-Gesucht.de Listing Monitor (`cg_nguyen/wg-gesucht-de`) Actor wg-gesucht.de as a JSON feed. Monitor flat-share (WG-Zimmer) listings across DACH: Berlin, Munich, Hamburg, Frankfurt, Cologne, Vienna, Zurich. Typed output: rent breakdown, district, photos, language, availability. Pay-per-event: $0.005/new, $0.001/dedup. First 50 free. - **URL**: https://apify.com/cg\_nguyen/wg-gesucht-de.md - **Developed by:** [CG Nguyễn](https://apify.com/cg_nguyen) (community) - **Categories:** Real estate, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $50.00 / 1,000 new listings This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## wg-gesucht.de Listings — Berlin / Munich / Hamburg, fresh in minutes > **wg-gesucht.de as a JSON feed** — for relocation consultants, expat developers, and AI agents who can't waste a minute when a listing drops. Scrapes public room-share (WG-Zimmer) listings from [wg-gesucht.de](https://www.wg-gesucht.de) across DACH cities. Returns clean, typed JSON with rent breakdown, district, photos, availability, and language preference. **Charges only for new listings you didn't see before** (pay-per-event), so polling every 15 minutes is cheap. --- ### ⚠️ Before you run — proxy is required wg-gesucht.de blocks datacenter IPs with a "please confirm you are human" challenge. **This Actor will not work without a residential (or your own DE-IP) proxy.** You must use one of: 1. **Apify Residential Proxy (DE)** — the default prefill. Requires Apify **Starter plan ($49/mo) or higher**. **Not available on the Free plan** — Free-plan runs will fail fast (within ~3 seconds) with a clear error message. 2. **Your own DE-IP proxy** — set `proxy_config.useApifyProxy: false` and `proxy_config.proxyUrls: ["http://user:pass@de-proxy.example.com:8080"]`. This is wg-gesucht's anti-scraping policy, not the Actor's choice. If you want to test the Actor end-to-end without a paid plan, message the maintainer for a free test run. --- ### Why this exists Berlin, Munich, and Hamburg flat-shares are **5–10× oversubscribed**. Good listings disappear in under 15 minutes during peak season (Aug–Oct, Jan–Mar). wg-gesucht's own Premium tier (€9.90/mo) gets you fast-track messaging — but it does **not** push alerts faster than the public feed. By the time you refresh the page, the listing is gone. This actor closes that gap. It polls the public feed, deduplicates, and emits one event per genuinely new listing — straight into your Telegram bot, Notion DB, Slack webhook, internal tool, or AI agent. It is **not** an end-user consumer app. There's no UI, no notifications, no login. You bring the automation; we bring the clean data. --- ### Who it's for | Persona | Use case | |---|---| | **Expat job-mover** | Pipes new Berlin/Munich listings into a personal Telegram bot. Lands an apartment one week faster than refreshing the site by hand. | | **Relocation consultancy** | Replaces 2 hrs/week of manual searching per junior consultant. One actor seat ≈ one part-time intern. | | **AI agent (MCP)** | Apify Actors are automatically MCP tools. Claude / / Codex agents call this when their user asks about Berlin housing. Zero integration work. | | **Corporate HR mobility** | Internal tooling for relocating engineers (SAP, Adidas, BMW). License access org-wide via Apify Enterprise. | --- ### Input | Field | Type | Default | Notes | |---|---|---|---| | `city` | `string` | `Berlin` | One of: Berlin, Munich, Hamburg, Frankfurt, Cologne, Stuttgart, Düsseldorf, Leipzig, Vienna, Zurich. | | `max_rent` | `integer` | `1200` | Hard cap on warm rent (€/month). | | `min_rooms` | `integer` | `1` | 1 = studio. | | `furnished` | `enum` | `any` | `any`, `furnished`, `partly`, `unfurnished`. | | `target_audience` | `enum` | `any` | `wg` (shared flat), `single_apartment`, `couple_apartment`, `any`. | | `language` | `enum` | `any` | `any`, `DE`, `EN`, `DE+EN`. Filters listings by description-language flags. | | `days_back` | `integer` | `7` | Skip listings older than N days. | | `max_results` | `integer` | `100` | Hard cap per run. Stops crawling once hit. | | `polite_mode` | `boolean` | `false` | If true, suppress emit if the same listing fired in the last 60 minutes. | | `proxy_config` | `object` | Apify Residential DE | wg-gesucht serves a Cloudflare challenge to datacenter IPs. Don't change unless you know what you're doing. | Full schema with descriptions: see the **Input** tab in the Apify console. --- ### Output — one listing per record Real, unredacted sample from a verified run: ```json { "listing_id": "9883205", "url": "https://www.wg-gesucht.de/wg-zimmer-in-Berlin-Wedding.9883205.html", "title": "Ein günstiges Zimmer mit Balkon zu mieten", "city": "Berlin", "district": "Wedding", "address_street": "See Straße", "rent_warm_eur": 500, "rent_kalt_eur": 350, "utilities_eur": 150, "deposit_eur": 1000, "rooms": 2, "sqm": 14, "furnished": "furnished", "available_from": "2026-05-31", "available_until": null, "contact_method": "in_app_message", "language_pref": ["DE", "EN"], "photos": ["https://img.wg-gesucht.de/...", "..."], "description": "Hey ihr Lieben, bei mir (Armin) ist ab sofort ein voll möbliertes WG-Zimmer frei...", "change_type": "new", "posted_at": "2026-05-15T08:14:00.000Z", "scraped_at": "2026-05-15T08:31:42.117Z" } ```` Every field is byte-verified against the live wg-gesucht page. Fill-rate from the last 100-record run: `listing_id, url, title, city, district, rent_warm_eur, rent_kalt_eur, rooms, sqm` at **100%**; `utilities_eur` 90%, `deposit_eur` 60% (some listings legitimately omit Kaution), `available_until` 40% (rest are `unbefristet`). *** ### Pricing — Pay Per Event | Event | Price | When it fires | |---|---|---| | `actor_start` | **free** | Once per run. | | `listing_new` | **$0.005** | A listing you haven't seen before (deduped by `listing_id` in a persistent key-value store across runs). | | `listing_skipped` | **$0.001** | A listing already seen — cheap heartbeat so you can confirm the actor is alive and the cache is warm. | **The first 50 events are free.** Test the actor end-to-end without paying a cent. Realistic monthly cost by persona: | You are... | Polling | New/mo | Skip/mo | Monthly cost | |---|---|---|---|---| | Daily window-shopper | Manual | ~100 | ~500 | **~$1** | | Active job-mover | Hourly | ~700 | ~5,000 | **~$8.50** | | Crunch-mode | Every 15 min | ~1,500 | ~50,000 | **~$57** | | Multi-city (3 cities) | Every 15 min | ~4,500 | ~150,000 | **~$172** | | Relocation agency (5 clients × 5 cities) | Every 15 min | ~7,500 | ~250,000 | **~$287** | You pay Apify; Apify pays the actor author. No credit card upgrade required beyond what Apify already charges for compute and proxy. *** ### How it stays fresh - **Residential DE proxy** — wg-gesucht serves a Cloudflare "are you human" challenge to datacenter IPs. We use Apify's residential DE pool by default. - **Polite delays** — built-in rate-limiting between detail fetches. We don't hammer the site. - **Per-listing dedup** — listing IDs are stored in a per-actor key-value store keyed `wg-gesucht-seen`. Stays warm across runs. - **Stale-prune** — IDs older than 30 days are dropped to keep the store light. - **`polite_mode`** — optional suppression of dupe emits within 60 minutes, for users polling at very high cadence. *** ### Limits & legal - Scrapes only **publicly accessible** pages. No login. No paywall bypass. - Respects rate-polite delays. - German-language listings are parsed in DE (so "Miete kalt", "Nebenkosten", "Kaution" all map to typed fields). - You are responsible for your own use of the data. The actor does not contact landlords on your behalf, does not store personal data of listing creators beyond what wg-gesucht itself displays publicly, and does not bypass any technical access controls. *** ### Frequently asked **Q: Why not just use the wg-gesucht.de RSS feed?** There is no public RSS for filtered WG-Zimmer searches that includes rent kalt, deposit, room count, district, or language preference as structured fields. The RSS would force you to scrape every detail page yourself anyway — which is what this actor does for you, with dedup. **Q: Why does it cost money? The data is public.** Because keeping it flowing isn't. The actor burns ~$0.80 of Apify residential proxy bandwidth per Berlin run of 10 listings. Pricing reflects the upstream cost plus author margin. Apify's first 50 free events let you confirm it works before you spend. **Q: Can I monitor a custom search URL instead of city-level?** Open a request via the Apify console issues tab. If 3+ users ask, it ships in the next minor version. **Q: Why "pay-per-event" and not subscription?** Because polling at 15-minute cadence in low-supply months wastes your money. PPE means you pay for results, not for cycles. Sleeping users cost nothing. **Q: Is there an MCP endpoint?** Yes — automatically. Every Apify Actor with an input schema is exposed as an MCP tool. Just point your Claude / / Codex client at the Apify MCP gateway and this actor appears as `wg-gesucht-de-listings`. *** ### Roadmap - v1.0 — Berlin, Munich, Hamburg, Frankfurt, Cologne (DACH-DE). - v1.1 — Vienna, Zurich (DACH-AT/CH). - v1.2 — `apartment` and `house` listings (1-Zimmer and full apartments, not just WG-Zimmer). - v1.3 — Custom-URL input (paste any wg-gesucht search URL). - v2.0 — Sibling actors for Immobilienscout24 and Immowelt as a unified DACH housing API. *** ### Sister actor Found the room — now you need the job? [`cg_nguyen/germany-visa-jobs`](https://apify.com/cg_nguyen/germany-visa-jobs) emits federal Bundesagentur listings with a `visaStatus` (`confirmed | likely | unlikely | unknown`) stamped on each row. Same author, same pay-per-event pricing. *** ### Author Built by [@cg\_nguyen](https://apify.com/cg_nguyen). Backend engineer based in Vietnam, working with European clients. Bugs and feature requests via the Apify console issues tab. # Actor input Schema ## `city` (type: `string`): Which German/DACH city to monitor. ## `max_rent` (type: `integer`): Listings above this warm rent (Warmmiete, incl. utilities) are excluded. ## `min_rooms` (type: `integer`): Minimum number of rooms (1 = studio). ## `furnished` (type: `string`): Filter by furnishing status. ## `target_audience` (type: `string`): wg = shared flat (Wohngemeinschaft) · single\_apartment = 1-Zimmer-Wohnung · couple\_apartment = couples-okay · any = all of the above. ## `language` (type: `string`): Filter by language flagged in the listing description. ## `days_back` (type: `integer`): Stop paginating when results are older than this many days. ## `max_results` (type: `integer`): Hard cap on listings emitted per single run. ## `polite_mode` (type: `boolean`): If true, suppress emit if the same listing was emitted in the last 60 minutes. Cuts noise on rapid polls. ## `proxy_config` (type: `object`): ⚠️ REQUIRED: wg-gesucht.de blocks datacenter IPs with a human-verification challenge. You MUST use one of: (1) Apify Residential Proxy in DE — requires Apify Starter plan ($49/mo) or higher, NOT available on Free plan; or (2) your own DE-IP proxy via proxyUrls. The Actor will fail fast with a clear message if no usable proxy is configured. ## Actor input object example ```json { "city": "Berlin", "max_rent": 1200, "min_rooms": 1, "furnished": "any", "target_audience": "any", "language": "any", "days_back": 7, "max_results": 5, "polite_mode": false, "proxy_config": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "DE" } } ``` # Actor output Schema ## `listings` (type: `string`): Full dataset of WG-Zimmer listings collected in this run. ## `overviewTable` (type: `string`): Compact table view of the dataset (title, city, district, rent, size, link). ## `rentBreakdown` (type: `string`): Table view focused on rent kalt / utilities / warm / deposit. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "days_back": 7, "max_results": 5, "proxy_config": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "DE" } }; // Run the Actor and wait for it to finish const run = await client.actor("cg_nguyen/wg-gesucht-de").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "days_back": 7, "max_results": 5, "proxy_config": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "DE", }, } # Run the Actor and wait for it to finish run = client.actor("cg_nguyen/wg-gesucht-de").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "days_back": 7, "max_results": 5, "proxy_config": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "DE" } }' | apify call cg_nguyen/wg-gesucht-de --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=cg_nguyen/wg-gesucht-de", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "WG-Gesucht.de Listing Monitor", "description": "wg-gesucht.de as a JSON feed. Monitor flat-share (WG-Zimmer) listings across DACH: Berlin, Munich, Hamburg, Frankfurt, Cologne, Vienna, Zurich. Typed output: rent breakdown, district, photos, language, availability. Pay-per-event: $0.005/new, $0.001/dedup. First 50 free.", "version": "1.1", "x-build-id": "t7LYKkOToP0dKenNx" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cg_nguyen~wg-gesucht-de/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cg_nguyen-wg-gesucht-de", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/cg_nguyen~wg-gesucht-de/runs": { "post": { "operationId": "runs-sync-cg_nguyen-wg-gesucht-de", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/cg_nguyen~wg-gesucht-de/run-sync": { "post": { "operationId": "run-sync-cg_nguyen-wg-gesucht-de", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "city" ], "properties": { "city": { "title": "City", "enum": [ "Berlin", "Munich", "Hamburg", "Frankfurt", "Cologne", "Stuttgart", "Düsseldorf", "Leipzig", "Vienna", "Zurich" ], "type": "string", "description": "Which German/DACH city to monitor.", "default": "Berlin" }, "max_rent": { "title": "Max warm rent (EUR/month)", "minimum": 100, "maximum": 5000, "type": "integer", "description": "Listings above this warm rent (Warmmiete, incl. utilities) are excluded.", "default": 1200 }, "min_rooms": { "title": "Minimum rooms", "minimum": 1, "maximum": 5, "type": "integer", "description": "Minimum number of rooms (1 = studio).", "default": 1 }, "furnished": { "title": "Furnished", "enum": [ "any", "furnished", "partly", "unfurnished" ], "type": "string", "description": "Filter by furnishing status.", "default": "any" }, "target_audience": { "title": "Listing type", "enum": [ "wg", "single_apartment", "couple_apartment", "any" ], "type": "string", "description": "wg = shared flat (Wohngemeinschaft) · single_apartment = 1-Zimmer-Wohnung · couple_apartment = couples-okay · any = all of the above.", "default": "any" }, "language": { "title": "Listing language preference", "enum": [ "any", "DE", "EN", "DE+EN" ], "type": "string", "description": "Filter by language flagged in the listing description.", "default": "any" }, "days_back": { "title": "Max listing age (days)", "minimum": 1, "maximum": 30, "type": "integer", "description": "Stop paginating when results are older than this many days.", "default": 2 }, "max_results": { "title": "Max listings per run", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap on listings emitted per single run.", "default": 5 }, "polite_mode": { "title": "Polite mode (hourly granularity)", "type": "boolean", "description": "If true, suppress emit if the same listing was emitted in the last 60 minutes. Cuts noise on rapid polls.", "default": false }, "proxy_config": { "title": "Proxy configuration (REQUIRED — see description)", "type": "object", "description": "⚠️ REQUIRED: wg-gesucht.de blocks datacenter IPs with a human-verification challenge. You MUST use one of: (1) Apify Residential Proxy in DE — requires Apify Starter plan ($49/mo) or higher, NOT available on Free plan; or (2) your own DE-IP proxy via proxyUrls. The Actor will fail fast with a clear message if no usable proxy is configured." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```