# Immoweb Scraper - Belgium Property Listings, Prices & Agents (`topapi/immoweb-scraper`) Actor

Scrape Immoweb.be, Belgium's biggest property site: houses, apartments, land, offices for sale or rent. Price, m², bedrooms, address, GPS, EPC, agency; details add-on with agency phone, e-mail, description, cadastral income. Filters, search links, monitor mode. $0.76 per 1,000 listings.

- **URL**: https://apify.com/topapi/immoweb-scraper.md
- **Developed by:** [Top Api](https://apify.com/topapi) (community)
- **Categories:** Real estate, Lead generation, E-commerce
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.76 / 1,000 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/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

### What does Immoweb Scraper do?

Immoweb Scraper reads property listings from **[Immoweb](https://www.immoweb.be)** (immoweb.be), Belgium's largest property website: houses, apartments, new-build projects, student rooms (kots), land, garages and parking, offices, commercial and industrial property, **for sale or for rent**. Search by city, postal code, district or province with Immoweb's own filters, or paste Immoweb search links and listing links. Each row has the price, old price, price per m², bedrooms, living and land area, full address, GPS, EPC score, agency, photos and dates. Turn on **Listing details** for the agency's phone, e-mail, website and IPI number, the full description in French and Dutch, EPC kWh/m² and certificate number, cadastral income, construction year, condition, facades, bathrooms, kitchen, garden and terrace size, parking, heating, flood zone, permits, view and save counts and every photo.

- **Every Immoweb filter** - price, bedrooms, rooms, living area, land area, construction year, EPC score, building condition, facades, parking, garden / terrace / kitchen size, garden, terrace, pool, lift, fireplace, accessible, furnished, available now, newly built, investment, public sales, life annuity, under option, published or updated in the last N days, subtypes (villa, penthouse, duplex ...), sort. They go into Immoweb's own search, so you pay only for listings that match.
- **Search links and listing links** - paste any Immoweb result page (English, French or Dutch, with its filters and sort) or listing link, or listing ids.
- **More than 9,960 listings per search** - Immoweb lets a visitor page through 9,960 listings of one search. When a search has more and you ask for more, the actor splits it by province, then by price band, and reads every part.
- **Monitor mode** - a scheduled run delivers only new listings and listings whose price changed (with the earlier price), and is not charged when nothing changed.
- **New-build projects unit by unit** - each project's units (apartments or houses, with floor, bedrooms, m², price and status) in the project row, and optionally each available unit as its own row.
- **Pay per listing** - $0.76 per 1,000 listings; details $0.36 per 1,000 more; no start fee.

### What data can I get?

Fill rates measured on real runs (2,000 newest sales across Belgium; 1,000 Brussels rentals with details; 150 Gent / Antwerp / Liège sales with details). A field is empty when Immoweb has no value for that listing.

| Field | What it is | Filled (measured) |
|---|---|---|
| `id`, `url`, `title` | Immoweb listing id, listing page, title (the advertiser's, or "House for sale - Gent 9000") | 100% |
| `transaction`, `transactionType`, `transactionSubtype` | sale / rent; FOR_SALE / FOR_RENT; BUY_REGULAR, RENT_REGULAR, PUBLIC_SALE ... (details) | 100% |
| `propertyType`, `propertySubtype` | HOUSE, APARTMENT, project groups, LAND, GARAGE, OFFICE, COMMERCIAL, INDUSTRY, OTHER; VILLA, DUPLEX, PENTHOUSE, FLAT_STUDIO, KOT ... | 100% |
| `price`, `currency`, `priceDisplay`, `priceKind`, `priceHidden` | Price or monthly rent in EUR, as shown, its kind, price-on-request flag | price 97-100% (the rest are on request) |
| `oldPrice`, `priceDropPct` | The price before the last reduction, and the drop in % | 5-9% of sales (reduced listings) |
| `pricePerSqm`, `hasStartingPrice` | Price per m² of living area (Immoweb's, else price / area); "from" price | 88-90% of sales |
| `priceMin`, `priceMax`, `bedroomRange`, `surfaceRange` | New-build projects: price, bedroom and m² ranges of the units | on project rows |
| `monthlyRent`, `monthlyCharges`, `yearlyRent`, `yearlyRentPerSqm` | Rentals: rent, charges; commercial rentals: yearly rent and per m² | rent 100%, charges 86% of rentals; yearly rent 67% of office / commercial rentals |
| `bedrooms`, `rooms`, `livingAreaSqm`, `landAreaSqm` | Bedrooms, rooms, living area, land | 97-100%, 21-27%, 84-90%, 54% of sales |
| `street`, `houseNumber`, `box`, `floor` | Address as the advertiser shows it | street 79-96%, number 78-95% |
| `postalCode`, `locality`, `district`, `province`, `region`, `regionCode`, `country`, `placeName` | Location | 100% (placeName 2-7%) |
| `latitude`, `longitude` | Map pin | 79-96% |
| `epcScore`, `epcLogoUrl` | EPC / PEB energy score A++ to G | 90-94% |
| `agencyName`, `agencyLogoUrl` | Agency or advertiser | 100%, 72-93% |
| `flag`, `secondaryFlags` | Immoweb's badge: new, new_price, under_option ... | 80-92% |
| `isProject`, `projectName`, `projectSoldPercent` | New-build project rows | on project rows |
| `imageUrl`, `images`, `imageCount` | Photos: the first 4 from search results, every photo with details | 100% |
| `hasVideo`, `hasVirtualTour`, `adSize` | Media flags; the ad format bought (XL, L, M, S) | 100% (flags set when present) |
| `modifiedAt`, `position`, `totalInSearch`, `searchUrl`, `scrapedAt` | Last update; position and total in the search; the Immoweb page it came from | 100% |

**With Listing details on** (one extra read per listing):

| Field | What it is | Filled (measured, details rows) |
|---|---|---|
| `description`, `descriptionFr`, `descriptionNl` | Full description (original language), French and Dutch versions | 100%; 85-98%; 73-88% |
| `sellerType`, `agencyId`, `agencyName` | AGENCY / PRIVATE ..., Immoweb customer id | 100% |
| `agencyPhone`, `agencyMobile`, `agencyEmail`, `agencyWebsite` | Agency phone, mobile, the e-mail Immoweb publishes for the listing, website | 68-73%, 30-37%, 74-84%, 53-67% |
| `agencyStreet`, `agencyPostalCode`, `agencyLocality`, `agencyLatitude`, `agencyLongitude`, `agencyIpiNumber`, `agencyContactHours` | Agency office address and map pin, IPI / BIV licence number, when it takes calls | 74-84%, IPI 71-77% |
| `createdAt`, `daysOnMarket`, `expiresAt` | Published on Immoweb, days since, publication end | 100%, 100%, 16-26% |
| `viewCount`, `bookmarkCount` | Times viewed and saved on Immoweb | 100% |
| `epcKwhPerSqm`, `epcKwhPerYear`, `co2Emission`, `epcReference`, `epcUrl`, `renovationObligation` | Energy certificate figures and number | kWh/m² 63-86%, reference 38-71% |
| `cadastralIncome`, `monthlyCosts` | Cadastral income (revenu cadastral / kadastraal inkomen); monthly costs | 48% of sales; 31-86% |
| `constructionYear`, `buildingCondition`, `facadeCount`, `buildingFloors`, `streetFacadeWidth` | Building | 49-56%, 77-78%, 59-68%, 48-79% |
| `bathrooms`, `showerRooms`, `toilets`, `kitchenType`, `kitchenSurface`, `livingRoomSurface`, `diningRoomSurface`, `bedroomSurfaces` | Rooms | bathrooms 81-90%, toilets 83-85%, kitchen 70-82% |
| `hasGarden`, `gardenSurface`, `gardenOrientation`, `hasTerrace`, `terraceSurface`, `terraceOrientation` | Outside | terrace 51-59% |
| `hasLift`, `hasSwimmingPool`, `hasFireplace`, `fireplaceCount`, `hasBasement`, `hasAttic`, `hasDressingRoom`, `hasLaundryRoom`, `hasAirConditioning`, `hasDisabledAccess`, `hasArmoredDoor`, `hasAlarm`, `hasVisiophone`, `hasCaretaker`, `hasSauna`, `hasJacuzzi`, `hasCableTV`, `hasInternet` | Equipment (true / false as the advertiser filled it) | 33-93% |
| `heatingType`, `hasHeatPump`, `hasPhotovoltaicPanels`, `hasSolarThermalPanels`, `hasDoubleGlazing` | Energy equipment | heating 73-74%, glazing 87-88% |
| `parkingIndoor`, `parkingOutdoor`, `parkingTotal` | Parking places | 18-29% |
| `floodZoneType`, `isConstructionPermitObtained`, `urbanPlanningZone`, `hasPlotDivisionAuthorization`, `hasPriorityPurchaseRight`, `isBreachingUrbanPlanning`, `buildableGroundFloorSurface` | Planning and flood zone | flood zone 53-76% |
| `hasElectricalCertificate`, `hasAsbestosCertificate`, `hasFloodCertificate`, `landWidth`, `sewerConnection`, `hasUtilitiesConnection` | Certificates and land | 11-72% |
| `availabilityDate`, `availabilityPeriod`, `isFurnished`, `areSmallPetsAllowed`, `areBigPetsAllowed` | Availability, furnished, pets (rentals) | 43%, 43%, 69%, 42%, 37% of rentals |
| `isInvestmentProperty`, `currentMonthlyRentalIncome` | Investment sales | flag 100% |
| `isNewClassified`, `isNewPrice`, `isUnderOption`, `isSoldOrRented`, `isNewlyBuilt`, `isPublicSale`, `isNotarySale`, `isInvestmentProject` | Listing flags | 100% (notary sale when shown) |
| `externalReference` | The agency's own reference | 69-79% |
| `virtualTourUrl`, `videoUrl`, `floorPlanUrls`, `documentUrls` | Media links (floor plans and documents mostly on project rows) | when the listing has them |
| `projectDeliveryDate`, `projectUnitCount`, `projectUnits` | New-build projects: delivery date, every unit (id, type, status AVAILABLE / SOLD, floor, price, bedrooms, m², link) | on project rows |

Monitor rows also carry `changeType` (new, price-changed, details, expired), `firstSeenAt` and `previousSeenPrice`. Project units delivered as rows carry `parentProjectId` and `unitStatus`. With **Include Immoweb's own JSON** each row has `raw` (the site's search result object and, with details, its listing object).

#### Example row (details on)

```json
{
  "id": "21990230",
  "url": "https://www.immoweb.be/en/classified/house/for-sale/gent/9000/21990230",
  "title": "Residentieel wonen in alle rust, met het Gentse stadscent...",
  "transaction": "sale",
  "propertyType": "HOUSE",
  "propertySubtype": "HOUSE",
  "price": 595000,
  "currency": "EUR",
  "pricePerSqm": 4474,
  "cadastralIncome": 1484,
  "bedrooms": 3,
  "bathrooms": 1,
  "livingAreaSqm": 133,
  "landAreaSqm": 351,
  "street": "Stormvogelstraat",
  "houseNumber": "49",
  "postalCode": "9000",
  "locality": "Gent",
  "province": "East Flanders",
  "region": "Flanders",
  "latitude": 51.0360486,
  "longitude": 3.6897361,
  "epcScore": "B",
  "epcKwhPerSqm": 147,
  "epcReference": "20261021-0003979658-RES-1",
  "constructionYear": 2007,
  "buildingCondition": "GOOD",
  "kitchenType": "HYPER_EQUIPPED",
  "heatingType": "GAS",
  "hasDoubleGlazing": true,
  "parkingIndoor": 1,
  "floodZoneType": "NON_FLOOD_ZONE",
  "sellerType": "AGENCY",
  "agencyName": "OC vastgoed",
  "agencyPhone": "+3292330200",
  "agencyWebsite": "http://www.ocvastgoed.be",
  "agencyIpiNumber": "502286",
  "description": "Deze woning in de Stormvogelstraat 49 geniet van een rustige, residentiële ligging op korte afstand van het centrum van Gent. ...",
  "detailsScraped": true
}
```

### How to use it

1. Type one or more **locations** (a city, a postal code, "district: Gent", "Antwerp province", "Brussels", or "Belgium"), choose **for sale** or **for rent** and the **property types**. Or paste **Immoweb links** - search pages and listing pages - or **listing ids**.
2. Add any **filters**. They are sent to Immoweb's own search.
3. Set **Max listings** and turn on **Listing details** if you need agency contacts, descriptions and building data.
4. Run. Download the rows as JSON, CSV or Excel, or read them through the API.

#### Input example

```json
{
  "locations": ["Gent", "Antwerp province", "1000, 1050"],
  "transaction": "sale",
  "propertyTypes": ["house", "apartment"],
  "minPrice": 250000,
  "maxPrice": 600000,
  "minBedrooms": 2,
  "epcScores": ["A", "B", "C"],
  "sortBy": "newest",
  "maxItems": 500,
  "includeDetails": true
}
```

With links:

```json
{
  "startUrls": [
    "https://www.immoweb.be/en/search/apartment/for-rent/gent/9000?countries=BE&maxPrice=1200&orderBy=newest",
    "https://www.immoweb.be/fr/recherche/maison/a-vendre/liege/4000?countries=BE&minPrice=200000",
    "https://www.immoweb.be/en/classified/house/for-sale/seraing/4100/21989959"
  ],
  "maxItems": 300
}
```

#### Inputs

| Input | What it does |
|---|---|
| `locations` | Cities (all their localities, as on Immoweb), postal codes ("9000" or "1000, 1050"), "district: <name>", provinces ("Antwerp province", "Limburg", "Brussels" = the Brussels region) or "Belgium". One search per line. |
| `transaction` | `sale` or `rent`. |
| `propertyTypes` | `house-and-apartment`, `house`, `apartment`, `new-project-houses`, `new-project-apartments`, `kot` (rent only), `land`, `garage`, `office`, `commercial`, `industry`, `other`. One search per type. |
| `startUrls` | Immoweb search links (English, French or Dutch; the link's filters, sort, location and start page are kept) and listing links. |
| `listingIds` | Listing ids to re-check. |
| `countries` | Immoweb also lists properties abroad: e.g. `FR`, `ES`, `LU` (with no location). |
| `minPrice` ... `maxConstructionYear`, `epcScores`, `buildingConditions`, `propertySubtypes`, `minRooms` ... `minTerraceArea`, `hasGarden` ... `hasVirtualTour`, `publicSale`, `lifeAnnuitySale`, `underOption`, `postedWithinDays`, `modifiedWithinDays` | Immoweb's own filters. |
| `extraFilters` | Any other Immoweb search parameter, sent as is. |
| `includeKeywords`, `keywordMatch`, `excludeKeywords` | Keep or drop listings by words in the title (and the description, with details on). |
| `agencyNames`, `excludeAgencyNames` | Keep or drop agencies by name. |
| `excludeProjects`, `withPriceOnly`, `onlyPriceReduced`, `minPriceDropPct`, `minPricePerSqm`, `maxPricePerSqm` | More filters. These run before anything is charged. |
| `sortBy` | `newest` (default), `relevance`, `cheapest`, `most_expensive`, `postal_code`. |
| `maxItems`, `maxItemsPerSearch`, `maxPagesPerSearch` | Caps (60 listings a page). `maxItems` 0 = no limit. |
| `includeDetails` | Listing details add-on (charged per listing that carries them). |
| `expandProjectUnits`, `includeSoldUnits` | Deliver each available unit of a new-build project as its own row (sold units on request). |
| `splitLargeSearches` | On by default: a search over 9,960 listings is read in parts (province, then price band). |
| `language` | Language of the listing links: `en`, `fr`, `nl`. |
| `deduplicate`, `compact`, `descriptionMaxLength`, `includeRawData` | Output options. |
| `monitorMode`, `monitorStoreName`, `emitPriceChanges`, `emitUnchanged`, `emitExpired`, `resetMonitor` | Monitor mode (below). |
| `webhookUrl` | POST a summary with the first rows when a run delivers something (Slack and Discord links get a message). |
| `maxConcurrency`, `maxRequestsPerMinute`, `proxyConfiguration` | Advanced. No proxy is needed. |

An empty input `{}` reads the 100 newest houses and apartments for sale in all of Belgium (the defaults).

### Monitor mode

Turn on `monitorMode` and schedule the actor (for example every morning). The first run delivers the listings of your searches; each later run with the same input delivers only:

- **new** listings (`changeType: "new"`),
- listings whose **price changed** (`changeType: "price-changed"`, with `previousSeenPrice`),
- listings an earlier run delivered without details when this run asks for details (`changeType: "details"`, once),
- with `emitExpired`, listings an earlier run delivered that are no longer on Immoweb (`changeType: "expired"`, free rows).

A run that finds nothing new delivers nothing and is not charged (measured: $0.00008 of platform usage). Raising `maxItems` on a later run delivers the listings below the earlier window once. Use `monitorStoreName` to keep several monitors with the same input apart.

### How much does it cost?

Pay per event, no start fee:

| Event | Price |
|---|---|
| Listing (a row) | $0.00076 ($0.76 per 1,000) |
| Listing details (add-on, per row that carries them) | $0.00036 ($0.36 per 1,000) |

Examples: 1,000 listings = $0.76; 1,000 listings with details = $1.12. Listings removed by a filter, duplicates and unchanged listings in monitor mode are never charged. Set a maximum cost per run in the Console and the run stops cleanly at it.

### Speed

Measured on the platform: 2,000 listings in 10 s; 10,417 listings (every office for rent in Belgium, read in 11 parts) in 256 s; 13,229 listings (every house and apartment for sale in Antwerp province, read in price bands) in 385 s; 1,000 listings with details in about 1 minute at the default 512 MB (2 minutes at 256 MB, 51 s at 1,024 MB).

### Limits

- Immoweb pages through at most 9,960 listings per search; with `splitLargeSearches` (default) a bigger search is read in parts. A part split by price band cannot include listings whose price is on request.
- Search results carry the first 4 photos; details carry every photo.
- Agency e-mails are the addresses Immoweb publishes for the listing (often the agency's listing-feed address). Private sellers' phone numbers are not shown by Immoweb.
- Fields not delivered because Immoweb leaves them empty on every listing read (3,800+ rows): balcony, sea view, approximate-pin flag, fitness room, tennis court, closed-box garages, English description, expected return, 360 tour, project phase and builder.

### FAQ

**Do I need a proxy or an Immoweb account?** No. The actor reads the same public data a visitor sees, with no login.

**Can I paste a French or Dutch Immoweb link?** Yes - `/fr/recherche/...`, `/nl/zoeken/...`, `/en/search/...`, map links and listing links in any of the three languages.

**How do I get only new listings every day?** Turn on `monitorMode`, sort by newest (default) and schedule the actor.

**How do I get the agency's phone number?** Turn on `includeDetails`.

# Actor input Schema

## `locations` (type: `array`):

Belgian cities or municipalities (all their localities are included, as on Immoweb), 4-digit postal codes ("9000", or several on one line: "1000, 1050"), districts ("district: Gent"), provinces ("Antwerp province", "Brussels", "Limburg") or "Belgium". One search per line. Leave empty to search all of Belgium.

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

Listings for sale or for rent.

## `propertyTypes` (type: `array`):

One search per type. 'Houses and apartments' is Immoweb's combined search.

## `startUrls` (type: `array`):

Search result links copied from your browser (English, French or Dutch, with any filters, sort and location: https://www.immoweb.be/en/search/house/for-sale/gent/9000?countries=BE\&minPrice=200000) and listing links (https://www.immoweb.be/en/classified/house/for-sale/seraing/4100/21989959). The link's own filters win over the filters below.

## `listingIds` (type: `array`):

Immoweb listing ids (the number at the end of a listing link) to re-check, one per line.

## `minPrice` (type: `integer`):

Price, or monthly rent for rentals.

## `maxPrice` (type: `integer`):

Price, or monthly rent for rentals.

## `minBedrooms` (type: `integer`):

Only listings with at least this many bedrooms.

## `maxBedrooms` (type: `integer`):

Only listings with at most this many bedrooms.

## `minLivingArea` (type: `integer`):

Living area at least this many m².

## `maxLivingArea` (type: `integer`):

Living area at most this many m².

## `minLandArea` (type: `integer`):

Land / plot at least this many m².

## `maxLandArea` (type: `integer`):

Land / plot at most this many m².

## `minConstructionYear` (type: `integer`):

Built in this year or later.

## `maxConstructionYear` (type: `integer`):

Built in this year or earlier.

## `epcScores` (type: `array`):

Only listings with one of these energy certificate scores.

## `buildingConditions` (type: `array`):

Only listings in one of these conditions.

## `propertySubtypes` (type: `array`):

Immoweb subtypes, e.g. VILLA, BUNGALOW, TOWN_HOUSE, MANSION, APARTMENT_BLOCK, MIXED_USE_BUILDING, DUPLEX, PENTHOUSE, FLAT_STUDIO, GROUND_FLOOR, LOFT, TRIPLEX, SERVICE_FLAT, KOT, BUILDING_LAND, OFFICES, WAREHOUSE, COMMERCIAL_PREMISES, LOCK_UP_GARAGE.

## `minRooms` (type: `integer`):

At least this many rooms.

## `maxRooms` (type: `integer`):

At most this many rooms.

## `minFacades` (type: `integer`):

At least this many facades (2 = terraced, 3 = semi-detached, 4 = detached).

## `maxFacades` (type: `integer`):

At most this many facades.

## `minParkingPlaces` (type: `integer`):

At least this many parking places.

## `minGardenArea` (type: `integer`):

Garden at least this many m².

## `minTerraceArea` (type: `integer`):

Terrace at least this many m².

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

Only listings with a garden.

## `hasTerrace` (type: `boolean`):

Only listings with a terrace.

## `hasTerraceOrGarden` (type: `boolean`):

Only listings with a terrace or a garden.

## `hasSwimmingPool` (type: `boolean`):

Only listings with a swimming pool.

## `hasLift` (type: `boolean`):

Only listings with a lift.

## `hasFireplace` (type: `boolean`):

Only listings with a fireplace.

## `hasDisabledAccess` (type: `boolean`):

Only listings accessible for people with disabilities.

## `isFurnished` (type: `boolean`):

Only furnished listings.

## `isImmediatelyAvailable` (type: `boolean`):

Only listings available now.

## `isNewlyBuilt` (type: `boolean`):

Only newly built properties.

## `isAnInvestmentProperty` (type: `boolean`):

Only properties sold as an investment.

## `hasVirtualTour` (type: `boolean`):

Only listings with a virtual tour.

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

Include, exclude or keep only public sales (auctions).

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

Include, exclude or keep only life annuity sales (viager / lijfrente).

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

Include, exclude or keep only listings under option.

## `postedWithinDays` (type: `integer`):

Immoweb's 'max days since activation'.

## `modifiedWithinDays` (type: `integer`):

Immoweb's 'max days since last modification'.

## `extraFilters` (type: `object`):

Any other parameter of Immoweb's search, sent as is, e.g. {"minKitchenSurface": 10, "isAWorkSpaceProperty": true}.

## `includeKeywords` (type: `array`):

Keep a listing only when its title (and its description, with details on) contains one of these words.

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

With several keywords to include: any of them, or all of them.

## `excludeKeywords` (type: `array`):

Drop a listing when its title (and description, with details on) contains one of these words.

## `agencyNames` (type: `array`):

Keep listings whose agency name contains one of these.

## `excludeAgencyNames` (type: `array`):

Drop listings whose agency name contains one of these.

## `excludeProjects` (type: `boolean`):

Drop project listings (a group of units with a price range).

## `withPriceOnly` (type: `boolean`):

Drop listings whose price is on request.

## `onlyPriceReduced` (type: `boolean`):

Listings Immoweb shows with an old price or a 'new price' flag.

## `minPriceDropPct` (type: `integer`):

Only listings whose price fell at least this much from the old price Immoweb shows.

## `minPricePerSqm` (type: `integer`):

Only sales whose price per m² is at least this.

## `maxPricePerSqm` (type: `integer`):

Only sales whose price per m² is at most this.

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

Order of the results (Immoweb's own sort). Newest first suits monitoring.

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

Stop after this many listings in total (0 = no limit).

## `maxItemsPerSearch` (type: `integer`):

Stop each search (location x type x sale/rent, or link) after this many listings.

## `maxPagesPerSearch` (type: `integer`):

60 listings a page.

## `includeDetails` (type: `boolean`):

Read each delivered listing's own page data: agency phone, e-mail, website and IPI number, full description (French / Dutch / English), EPC kWh/m² and reference, CO2, cadastral income, construction year, condition, facades, bathrooms, toilets, kitchen, garden / terrace size, parking, heating, flood zone, permits, views and saves, all photos, publication date and days on market. Charged per listing that carries them.

## `expandProjectUnits` (type: `boolean`):

For project listings, also deliver each of the project's units (apartments or houses) as its own listing row.

## `includeSoldUnits` (type: `boolean`):

With project units on: also deliver units the project shows as sold (default: available units only).

## `splitLargeSearches` (type: `boolean`):

Immoweb pages through at most 9,960 listings per search. When a search has more and your max wants more, it is split by province, then by price band, so every listing can be reached.

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

Language of the listing links in the rows.

## `deduplicate` (type: `boolean`):

A listing found by two searches is delivered (and charged) once.

## `compact` (type: `boolean`):

A short row (id, link, title, price, area, address, EPC, agency) without empty fields.

## `descriptionMaxLength` (type: `integer`):

0 = full text.

## `includeRawData` (type: `boolean`):

Add the site's search result object (and listing object, with details) as `raw`.

## `monitorMode` (type: `boolean`):

Each run delivers only listings the earlier runs of the same input did not deliver, plus listings whose price changed. Schedule it to get new listings daily.

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

Keeps separate memories for separate monitors with the same input.

## `emitPriceChanges` (type: `boolean`):

Monitor mode: deliver a listing again when its price changed (changeType price-changed).

## `emitUnchanged` (type: `boolean`):

Monitor mode: deliver listings again even when nothing changed.

## `emitExpired` (type: `boolean`):

A free row (changeType expired) for each listing an earlier run delivered that a search read to its end no longer shows.

## `resetMonitor` (type: `boolean`):

Monitor mode: start this monitor over (every listing counts as new once).

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

POST a summary with the first rows when a run delivers something (Slack and Discord webhook links get a message).

## `maxConcurrency` (type: `integer`):

Requests in flight at once.

## `maxRequestsPerMinute` (type: `integer`):

Pace limit for all requests to Immoweb.

## `proxyConfiguration` (type: `object`):

Not needed: the run starts on the platform's own connection and moves to Apify datacenter, then residential (Belgium), only if Immoweb refuses it. Set a proxy to start there instead.

## Actor input object example

```json
{
  "locations": [
    "Gent"
  ],
  "transaction": "sale",
  "propertyTypes": [
    "house-and-apartment"
  ],
  "keywordMatch": "any",
  "sortBy": "newest",
  "maxItems": 20,
  "includeDetails": false,
  "expandProjectUnits": false,
  "includeSoldUnits": false,
  "splitLargeSearches": true,
  "language": "en",
  "deduplicate": true,
  "compact": false,
  "includeRawData": false,
  "monitorMode": false,
  "emitPriceChanges": true,
  "emitUnchanged": false,
  "emitExpired": false,
  "resetMonitor": false,
  "maxConcurrency": 16,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

One item per property listing.

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

Per-search counts (total on Immoweb, read, delivered, pages, split parts), filters and egress statistics (written for Console runs, large runs and runs with a problem).

# 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 = {
    "locations": [
        "Gent"
    ],
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("topapi/immoweb-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 = {
    "locations": ["Gent"],
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("topapi/immoweb-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 '{
  "locations": [
    "Gent"
  ],
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call topapi/immoweb-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,topapi/immoweb-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/VtVFJ5CsXmTnhLrmX/builds/0NqNhw7wdnlB1LZT8/openapi.json
