{ "openapi": "3.0.1", "info": { "title": "Immowelt Scraper — German Real Estate Listings", "description": "Scrape immowelt.de — one of Germany's largest property portals — every active sale or rental listing for any city · narrowed by price · size · rooms · property type and year. Incremental mode tracks new and changed listings across scheduled runs.", "version": "0.2", "x-build-id": "sQZ3AzbE4BhhObwgm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/blackfalcondata~immowelt-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-blackfalcondata-immowelt-scraper", "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/blackfalcondata~immowelt-scraper/runs": { "post": { "operationId": "runs-sync-blackfalcondata-immowelt-scraper", "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/blackfalcondata~immowelt-scraper/run-sync": { "post": { "operationId": "run-sync-blackfalcondata-immowelt-scraper", "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", "properties": { "query": { "title": "🔍 Search Term", "type": "string", "description": "City, region, or postal area to search (e.g. \"Berlin\", \"München\", \"Charlottenburg\"). Use a JSON array for several. Equivalent to the City field — use whichever you prefer." }, "country": { "title": "🌍 Country", "enum": [ "DE" ], "type": "string", "description": "Which Immowelt market to search.", "default": "DE" }, "maxResults": { "title": "💯 Max Results", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Maximum total listings to return after dedupe and filters (0 = unlimited). You are charged per emitted record, so this is your primary cost control. When both `maxResults` and `maxPages` are set, the run stops at whichever cap is reached first.", "default": 100 }, "startUrls": { "title": "🔗 Start URLs", "type": "array", "description": "Immowelt listing URLs (e.g. https://www.immowelt.de/expose/2pg5u5z) to scrape those specific listings, and/or search URLs copied from your browser (e.g. https://www.immowelt.de/classified-search?distributionTypes=Rent&estateTypes=Apartment&locations=...) to run that search with its location and filters.", "items": { "type": "string" } }, "radiusKm": { "title": "📏 Search Radius (km)", "minimum": 0, "maximum": 200, "type": "integer", "description": "Search this many kilometres around the centre of the city (or around Latitude/Longitude). 0 = the city boundary only; with Latitude/Longitude, 0 means 10 km.", "default": 0 }, "distributionType": { "title": "Buy or Rent", "enum": [ "buy", "rent", "buy_and_rent" ], "type": "string", "description": "Filter by sale, rent, or both.", "default": "buy" }, "estateType": { "title": "Property Type", "enum": [ "apartment_and_house", "apartment", "house", "all_residential", "all_types", "plot", "garage_parking", "temporary_living", "shared_apartment", "other_residential", "all_commercial", "office", "retail", "hospitality", "industrial", "investment", "agriculture", "commercial_plot" ], "type": "string", "description": "Which kinds of property to return. \"Apartments & Houses\" returns only apartments and houses. Choose \"All residential types\" to also get plots, parking spaces, temporary and shared living, or \"All types\" to add commercial property. Commercial options (office, retail, …) search commercial listings.", "default": "apartment_and_house" }, "estateSubtypes": { "title": "Property Subtypes", "type": "array", "description": "Optional finer property subtypes (e.g. MAISONETTE, PENTHOUSE, TERRACED_HOUSE). Leave empty for all subtypes.", "items": { "type": "string" } }, "priceMin": { "title": "💰 Min Price (€)", "minimum": 0, "type": "integer", "description": "Only listings priced at or above this amount." }, "priceMax": { "title": "💰 Max Price (€)", "minimum": 0, "type": "integer", "description": "Only listings priced at or below this amount." }, "areaMin": { "title": "Min Living Area (m²)", "minimum": 0, "type": "integer", "description": "Only listings with living area at or above this size." }, "areaMax": { "title": "Max Living Area (m²)", "minimum": 0, "type": "integer", "description": "Only listings with living area at or below this size." }, "plotAreaMin": { "title": "Min Plot Area (m²)", "minimum": 0, "type": "integer", "description": "Only listings with a plot of at least this size (houses and plots)." }, "plotAreaMax": { "title": "Max Plot Area (m²)", "minimum": 0, "type": "integer", "description": "Only listings with a plot of at most this size." }, "roomsMin": { "title": "Min Rooms", "minimum": 0, "type": "integer", "description": "Only listings with at least this many rooms." }, "roomsMax": { "title": "Max Rooms", "minimum": 0, "type": "integer", "description": "Only listings with at most this many rooms." }, "constructionYearMin": { "title": "Built After (year)", "minimum": 1800, "maximum": 2100, "type": "integer", "description": "Only listings built in or after this year." }, "constructionYearMax": { "title": "Built Before (year)", "minimum": 1800, "maximum": 2100, "type": "integer", "description": "Only listings built in or before this year." }, "features": { "title": "Must Have Features", "type": "array", "description": "Only listings that have ALL of the selected features.", "items": { "type": "string", "enum": [ "BALCONY_OR_TERRACE", "GARDEN", "CELLAR", "FITTED_KITCHEN", "GARAGE_OR_PARKING_AREA", "PASSENGER_LIFT", "BARRIER_FREE", "GROUND_FLOOR", "FURNISHED", "PETS_ALLOWED", "SENIOR_FRIENDLY", "ATTIC", "NEW_BUILDING", "OLD_BUILDING", "RENOVATED_OR_RESTRUCTURED", "FREE_OF_COMMISSION", "AIR_CONDITIONED", "BATH_WITH_TUB", "BATH_WITH_WINDOW", "FLAT_SHARE_POSSIBLE", "CERTIFICATE_OF_ELIGIBILITY", "AVAILABLE_FOR_RENT", "RENTED", "JUDICIAL_SALE", "NEW_BUILDING_PROJECT", "HERITAGE_PROTECTION_DEPRECIATION", "RESTRUCTURING_DEPRECIATION", "PRIME_LOCATION", "FULLY_DEVELOPED", "PARTLY_DEVELOPED", "UNDEVELOPED" ], "enumTitles": [ "Balcony or terrace", "Garden", "Cellar", "Fitted kitchen", "Garage or parking space", "Lift", "Barrier-free", "Ground floor", "Furnished", "Pets allowed", "Senior-friendly", "Attic", "New building", "Old building", "Renovated", "No commission", "Air conditioning", "Bath with tub", "Bathroom with window", "Flat share possible", "Social housing certificate (WBS) required", "Vacant (not rented out)", "Currently rented out (investment)", "Foreclosure auction", "Part of a new-build project", "Listed building (heritage tax relief)", "Redevelopment area (tax relief)", "Prime location", "Plot: fully serviced", "Plot: partly serviced", "Plot: not serviced" ] } }, "excludeFeatures": { "title": "Exclude Features", "type": "array", "description": "Exclude listings that have ANY of the selected features.", "items": { "type": "string", "enum": [ "BALCONY_OR_TERRACE", "GARDEN", "CELLAR", "FITTED_KITCHEN", "GARAGE_OR_PARKING_AREA", "PASSENGER_LIFT", "BARRIER_FREE", "GROUND_FLOOR", "FURNISHED", "PETS_ALLOWED", "SENIOR_FRIENDLY", "ATTIC", "NEW_BUILDING", "OLD_BUILDING", "RENOVATED_OR_RESTRUCTURED", "FREE_OF_COMMISSION", "AIR_CONDITIONED", "BATH_WITH_TUB", "BATH_WITH_WINDOW", "FLAT_SHARE_POSSIBLE", "CERTIFICATE_OF_ELIGIBILITY", "AVAILABLE_FOR_RENT", "RENTED", "JUDICIAL_SALE", "NEW_BUILDING_PROJECT", "HERITAGE_PROTECTION_DEPRECIATION", "RESTRUCTURING_DEPRECIATION", "PRIME_LOCATION", "FULLY_DEVELOPED", "PARTLY_DEVELOPED", "UNDEVELOPED" ], "enumTitles": [ "Balcony or terrace", "Garden", "Cellar", "Fitted kitchen", "Garage or parking space", "Lift", "Barrier-free", "Ground floor", "Furnished", "Pets allowed", "Senior-friendly", "Attic", "New building", "Old building", "Renovated", "No commission", "Air conditioning", "Bath with tub", "Bathroom with window", "Flat share possible", "Social housing certificate (WBS) required", "Vacant (not rented out)", "Currently rented out (investment)", "Foreclosure auction", "Part of a new-build project", "Listed building (heritage tax relief)", "Redevelopment area (tax relief)", "Prime location", "Plot: fully serviced", "Plot: partly serviced", "Plot: not serviced" ] } }, "sort": { "title": "🔀 Sort By", "enum": [ "relevance", "newest", "price_asc", "price_desc", "area_asc", "area_desc", "rooms_asc", "rooms_desc", "distance" ], "type": "string", "description": "Ordering of results. \"Nearest first\" needs a search radius or latitude/longitude.", "default": "relevance" }, "newBuildProjects": { "title": "🏗️ New-build projects", "enum": [ "exclude", "include", "only" ], "type": "string", "description": "New-build developments are listed as one project with several units. Leave them out (default), include them alongside regular listings, or return projects only. A project row carries its construction dates, number of units and every unit with its own price, area, rooms and link. A project row lists the units the search shows for it (often a few of the total), and is not checked against the post-fetch filters below except furnished: a project has no detail page, so a project is left out whenever such a filter is set.", "default": "exclude" }, "sellerType": { "title": "👤 Seller", "enum": [ "any", "private", "professional" ], "type": "string", "description": "Private owners or professional agencies only. Strict: a listing that does not state this on its page is left out, not let through. Checked on each listing's full page after it is fetched, so full details are turned on automatically, and the search reads further (up to 100 pages unless you set Max pages) until enough listings match.", "default": "any" }, "energyEfficiencyClasses": { "title": "⚡ Energy efficiency class", "type": "array", "description": "Keep listings whose energy certificate shows one of these classes. Strict: a listing that does not state this on its page is left out, not let through. Checked on each listing's full page after it is fetched, so full details are turned on automatically, and the search reads further (up to 100 pages unless you set Max pages) until enough listings match.", "items": { "type": "string", "enum": [ "A+", "A", "B", "C", "D", "E", "F", "G", "H" ], "enumTitles": [ "A+", "A", "B", "C", "D", "E", "F", "G", "H" ] } }, "heatingTypes": { "title": "🔥 Heating", "type": "array", "description": "Keep listings whose heating type or energy source matches any of these. Strict: a listing that does not state this on its page is left out, not let through. Checked on each listing's full page after it is fetched, so full details are turned on automatically, and the search reads further (up to 100 pages unless you set Max pages) until enough listings match.", "items": { "type": "string", "enum": [ "central", "floor", "self_contained", "heat_pump", "district", "gas", "oil", "electric", "fireplace_stove", "solar", "wood_pellets" ], "enumTitles": [ "Central heating", "Underfloor heating", "Self-contained (per-floor) heating", "Heat pump", "District heating", "Gas", "Oil", "Electric", "Fireplace / stove", "Solar", "Wood / pellets" ] } }, "floorMin": { "title": "🏢 Floor from", "minimum": -1, "maximum": 100, "type": "integer", "description": "Lowest floor (0 = ground floor, -1 = basement). Strict: a listing that does not state this on its page is left out, not let through. Checked on each listing's full page after it is fetched, so full details are turned on automatically, and the search reads further (up to 100 pages unless you set Max pages) until enough listings match." }, "floorMax": { "title": "🏢 Floor up to", "minimum": -1, "maximum": 100, "type": "integer", "description": "Highest floor (0 = ground floor). Strict: a listing that does not state this on its page is left out, not let through. Checked on each listing's full page after it is fetched, so full details are turned on automatically, and the search reads further (up to 100 pages unless you set Max pages) until enough listings match." }, "includeKeywords": { "title": "🔤 Must mention", "type": "array", "description": "Keep listings whose title or description mentions any of these words (case-insensitive), e.g. \"Altbau\", \"Dachterrasse\". Strict: a listing that does not state this on its page is left out, not let through. Checked on each listing's full page after it is fetched, so full details are turned on automatically, and the search reads further (up to 100 pages unless you set Max pages) until enough listings match.", "items": { "type": "string" } }, "excludeKeywords": { "title": "🚫 Must not mention", "type": "array", "description": "Leave out listings whose title or description mentions any of these words (case-insensitive). Strict: a listing without a description is left out, because the word cannot be ruled out. Checked on each listing's full page after it is fetched, so full details are turned on automatically, and the search reads further (up to 100 pages unless you set Max pages) until enough listings match.", "items": { "type": "string" } }, "furnished": { "title": "🛋️ Furnished", "enum": [ "any", "furnished", "unfurnished" ], "type": "string", "description": "Furnished (fully or partly) listings only, or unfurnished only. Applied by the search itself, so it costs nothing extra; every kept listing is re-checked and one not marked furnished is left out.", "default": "any" }, "lat": { "title": "🌐 Latitude", "minimum": -90, "maximum": 90, "type": "number", "description": "Search around a point instead of a place name. Pair with Longitude; the radius comes from \"Search Radius (km)\" (10 km when 0). Takes precedence over City." }, "lon": { "title": "🌐 Longitude", "minimum": -180, "maximum": 180, "type": "number", "description": "Longitude of the search centre. Pair with Latitude." }, "polygon": { "title": "🗺️ Search Polygon", "type": "array", "description": "Search inside your own area: at least 3 corner points, one per line, each as \"latitude,longitude\" (e.g. 53.76,9.62). Takes precedence over Latitude/Longitude and City.", "items": { "type": "string" } }, "includeDetails": { "title": "📋 Include Full Details", "type": "boolean", "description": "Fetch each listing's detail page for the full description, energy certificate, exact address, and contact. Slightly slower.", "default": true }, "descriptionMaxLength": { "title": "✂️ Description Max Length", "minimum": 0, "type": "integer", "description": "Truncate description to this many characters. 0 = no truncation.", "default": 0 }, "compact": { "title": "📦 Compact Output", "type": "boolean", "description": "Output only core fields (for AI-agent / MCP workflows).", "default": false }, "descriptionFormat": { "title": "Description format", "enum": [ "all", "text" ], "type": "string", "description": "Keep all description fields, or only the plain-text `description`.", "default": "all" }, "excludeEmptyFields": { "title": "Exclude empty fields from output", "type": "boolean", "description": "Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.", "default": false }, "incrementalMode": { "title": "♻️ Incremental Mode", "type": "boolean", "description": "Compare against previous run state. Only new / changed listings are emitted. State is keyed automatically from your search inputs. Tip: to reliably detect removed listings (see `emitExpired`), set `maxResults` to 0 — a capped run only sees part of the search, so removals can't be confirmed and are left untouched.", "default": false }, "stateKey": { "title": "🔑 State Key", "type": "string", "description": "Optional stable identifier for the tracked search universe. Leave empty to auto-derive a stable identifier from your search inputs — different location/filter combinations get isolated state automatically." }, "emitUnchanged": { "title": "♻️ Emit Unchanged Records", "type": "boolean", "description": "When incremental, also emit listings that haven't changed.", "default": false }, "emitExpired": { "title": "⚰️ Emit Expired Records", "type": "boolean", "description": "When incremental, also emit listings no longer found. Requires full coverage to be accurate: set `maxResults` to 0, otherwise a capped run can't tell \"removed\" from \"not fetched this run\" and emits nothing as expired.", "default": false }, "skipReposts": { "title": "🚫 Skip Reposts", "type": "boolean", "description": "Exclude listings detected as reposts of previously seen listings.", "default": false }, "notifyOnlyChanges": { "title": "🆕 Notify Only on Changes", "type": "boolean", "description": "When ON together with Incremental Mode, send notifications only for NEW and UPDATED listings. Has no effect outside incremental mode.", "default": false }, "notificationLimit": { "title": "🔢 Notification Limit", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of listings included per notification batch (1–20). Prevents spam on large result sets.", "default": 5 }, "telegramToken": { "title": "📱 Telegram Bot Token", "type": "string", "description": "Telegram bot token from @BotFather. Pairs with Telegram Chat ID. Pair with Incremental Mode for real-time alerts on new/updated listings only." }, "telegramChatId": { "title": "💬 Telegram Chat / Channel ID", "type": "string", "description": "Chat ID (from @userinfobot) or channel ID (starts with -100 for channels). Required when Telegram Bot Token is set." }, "discordWebhookUrl": { "title": "🎮 Discord Webhook URL", "type": "string", "description": "Discord channel webhook URL (Server Settings → Integrations → Webhooks → New Webhook). Sends rich embeds colour-coded by change type (green=NEW, amber=UPDATED)." }, "slackWebhookUrl": { "title": "💼 Slack Incoming Webhook URL", "type": "string", "description": "Slack incoming webhook URL (Slack App → Incoming Webhooks → Add New Webhook). Formats listings as Slack blocks." }, "whatsappPhoneNumberId": { "title": "📞 WhatsApp Phone Number ID", "type": "string", "description": "Numeric WhatsApp Business phone-number ID from Meta dashboard." }, "whatsappAccessToken": { "title": "📲 WhatsApp Access Token", "type": "string", "description": "WhatsApp Cloud API permanent System User token from Meta Business. Pairs with WhatsApp Phone Number ID and recipient phone." }, "whatsappTo": { "title": "📨 WhatsApp Recipient (E.164)", "type": "string", "description": "Recipient phone in E.164 format (e.g. \"15551234567\"). Recipient must have messaged the business number within the last 24h, otherwise Meta rejects free-form text." }, "webhookUrl": { "title": "🔗 Generic Webhook URL", "type": "string", "description": "POSTs a JSON payload `{metadata, items}` to your endpoint. Universal hook for n8n / Make / Zapier / custom backends." }, "webhookHeaders": { "title": "📑 Webhook Headers (JSON)", "type": "object", "description": "Optional headers (e.g. `{\"Authorization\": \"Bearer ...\"}`) sent with the webhook POST." }, "appConnector": { "title": "Send results to Notion (or another connected app)", "type": "string", "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results. Notion is supported today (a run-summary page); other MCP connectors are best-effort as Apify expands its catalog." }, "mcpIssueTeam": { "title": "Issue tracker team", "type": "string", "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one." }, "city": { "title": "🏙️ City / Location", "type": "string", "description": "City or region to search in (e.g. \"Berlin\", \"München\", \"Hamburg\"). Use a JSON array for multiple locations. Same effect as the Search Term field." }, "location": { "title": "📍 Location (legacy)", "type": "string", "description": "Legacy field. Use 'City / Location' instead." }, "maxPages": { "title": "📄 Max Pages", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum result pages to fetch per location. Defensive safety bound — `maxResults` is the primary record cap.", "default": 5 }, "cityName": { "title": "🏙️ City Name", "type": "string", "description": "Alias for City / Location — either field works. City or region to search in (e.g. \"München\", \"Hamburg\")." } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }