Was this helpful?
How to scrape Zimmo
Technical engineer
Zimmo.be is one of the main property portals in Belgium. People use it to sell and rent houses, apartments, garages, commercial space and units in new-build projects, and the site runs in two languages, Dutch and French. If you need data for a market analysis, most of it sits right on the search pages. Every listing shows a price, an address, a property type, the living area, the number of bedrooms and its EPC energy label.
You can't just download those pages, though. Zimmo is behind Cloudflare, and a plain HTTP client gets a 403 with "Just a moment…". A browser running on a datacentre server gets the same. Cloudflare even turns away headless Chromium from a Belgian home connection, while a normal browser with a window gets straight through.
The data itself has a couple of catches too. There's no ready-made JSON with the listings on the page, so everything has to be read from the rendered tiles. And new-build projects don't show a unit price. You'll see something like "Vanaf € 499.782", which means "from" and is the price of the cheapest unit in the project.
Below we'll walk through the open-source 2scraper/zimmo-scraper. We'll install it, export search results to JSON or CSV, run it at home and on a server, and finish by working out median prices for a city. We'll use the Playwright engine, which is the one the repository recommends. The numbers in this article come from the project's README and changelog, and each one has the date it was measured.
What you get
The scraper takes a link to a zimmo.be search page. Sale or rent both work, and so do the Dutch site (/nl/…/te-koop/) and the French one (/fr/…/a-vendre/). Each listing becomes one row with these fields:
| Field | What's in it | Filled (2026-09-23) |
|---|---|---|
| sku | Zimmo's listing code, e.g. LRZLA | 100% |
| price, currency | Price in euros. null when the listing says "Prijs op aanvraag" (price on request) | 99% |
| listing_type | sale or rent | 100% |
| property_type | huis, appartement, nieuwbouwproject, garage, bedrijfsvastgoed and so on | 100% |
| location | Street address with postcode and town | |
| surface_m2 | Living area in m² | 90% |
| bedrooms | How many bedrooms | 72% |
| epc_label | Energy grade, including A+, A++ and Brussels' minus grades such as E- | 70% |
| url, image_url, title, category, scraped_at | Link, main photo, tile title, your own label, time of the run |
Why isn't everything at 100%? A garage or an office has no bedrooms, and some listings simply don't give an area or an energy grade. The percentages come from 105 tiles on seven live pages (Ghent, Antwerp, Brussels). Every field was checked against the labels the site provides for screen readers, and there wasn't a single mismatch.
Four more fields exist in the schema but are always empty right now: brand, original_price, discount_pct and epc_value. They used to come from JSON the site served until September 2026. In runs on October 27–28 they were empty in all 168 rows, so don't count on them for now.
What you need
Any Python from 3.9 to 3.12 will do. On 3.13 the pinned Playwright 1.44 won't install, because greenlet has no prebuilt wheel there. The easy fix is to create the environment with python3.12 -m venv .venv; the README describes a workaround for newer versions.
Go with Playwright as the engine. Selenium and pyppeteer versions exist too, but pyppeteer hasn't been updated in a long time. Put each engine in its own virtual environment, or their dependencies will start fighting.
The key requirement is a browser with a window. On your own computer that's just the --headful flag. On a server you'll also need a virtual display (xvfb) and a residential IP; 2Captcha residential proxies work. There's also a way to skip all of that. 2Captcha Browser API gives you a remote browser that already has a suitable address and a window.
You don't need a captcha key for normal runs.
Installation
bash
git clone https://github.com/2scraper/zimmo-scraper.git
cd zimmo-scraper
python3.12 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt -r requirements-playwright.txt
playwright install chromium
cp .env.example .env
python3 env_config.py # shows where each setting came from, never prints secrets
There are only four settings in .env. TWOCAPTCHA_KEY only matters if a captcha ever shows up. ZIMMO_URL is a default search and can stay empty. ZIMMO_CDP_ENDPOINT is for the Browser API, and ZIMMO_PROXY is for a residential proxy. Keep passwords and keys here, because anything you type on the command line stays in your shell history and shows up in the process list.
First run
bash
# Houses and apartments for sale in Ghent, 3 pages, JSON and CSV
python3 playwright_scraper.py \
--url "https://www.zimmo.be/nl/gent-9000/te-koop/" \
--pages 3 --headful --category gent-koop --format both --out gent_listings
# Rentals in Antwerp
python3 playwright_scraper.py --url "https://www.zimmo.be/nl/antwerpen-2000/te-huur/" --headful --out antwerp_rent
# The French site: for sale in Brussels
python3 playwright_scraper.py --url "https://www.zimmo.be/fr/bruxelles-1000/a-vendre/" --headful --out brussels_sale
# On a server with no display
xvfb-run -a python3 playwright_scraper.py --url "https://www.zimmo.be/nl/gent-9000/te-koop/" --pages 3 --headful
Pass the link without a page parameter and set the number of pages with --pages. If the link has page in it, the scraper refuses to run and exits with code 2. You can put anything you like in --category. The label goes into every row, which helps when you combine several searches into one table.
Out of the box the scraper reads one page, writes both JSON and CSV to files called zimmo_listings, retries twice and runs in a single worker with no pauses.
How the scraper gets the data
The site is built with Angular. None of the listing data is in a structured block. The only JSON-LD on the page is a breadcrumb, and the embedded Angular state holds headings and counters. So the scraper waits for the tiles to render and reads them.
The class names the site's build generates change from release to release, so they're useless as anchors. The scraper holds on to the parts that stay put instead. Each listing is its own zimmo-listing element. The listing code lives in .zimmo-code and becomes the sku field. Bedrooms, area and energy grade are recognised by their icon files: bedrooms.svg, floorspace-surface.svg, energy-labels/epc_b.svg. The Dutch and French sites use the same icons and only translate the labels next to them, which is why one parser handles both languages.
The scraper is also careful about where a search ends. Each page shows the total number of results, such as "51 resultaten" or "51 résultats". If it says 0, the search is empty. If the counter says 51 but the page also reads "We vonden helaas geen resultaten", you've gone past the last page. That's what page 4 of a 51-result search looked like in a test on October 28, and the run simply stopped there with the status complete.
A page with no listings and no counter, on the other hand, is treated as one that didn't finish loading, which can happen when a proxy drops the connection. The scraper tries again and then records the page as failed. It won't mistake it for the end of the results. The French site has one gap. Nobody has captured yet how it phrases "no results", so a French search that runs past its last page ends as partial.
Other responses get their own handling as well. A 403 with "Even geduld..." is the Cloudflare check, and unless listings show up after it, the page counts as blocked. A 404 means the site has no such page. 429 and 5xx get retried. If the grid rendered but not a single row could be pulled from it, that's a parser failure, not an empty search.
Getting past Cloudflare
Cloudflare on Zimmo looks at two things: where the request comes from and whether the browser has a window. Here's what the repository's authors saw on September 23, 2026, all on the same address, /nl/gent-9000/te-koop/:
| From | Browser | Result |
|---|---|---|
| Datacentre (Hetzner), no proxy | curl with any User-Agent | HTTP 403 "Just a moment…" |
| Datacentre, no proxy | Chromium with or without a window | Cloudflare check, exit 3 |
| GitHub Actions runner | Chromium with a window under xvfb | Cloudflare check, exit 3 |
| Belgian home IP | Chromium without a window | Cloudflare check, exit 3 |
| Belgian home IP | Chromium with a window | Let through: 63 rows, 3 of 3 pages |
| German home IP | Chromium with a window | Let through: 21 rows |
| 2Captcha Browser API, Belgian profile | Its own | Let through: 63 rows, 3 of 3 pages |
On October 13 a US home IP was refused, while the Belgian and German ones got through again. All three engines were run through the Belgian IP with a window on three pages, and they returned the same 63 listings at the same prices.
So it's less about the country than about the kind of connection.
At home
Just add --headful. You don't need a Belgian address. By default the scraper starts the browser without a window, like the other 2scraper scrapers, which is why every example spells the flag out.
On a server
Put a residential proxy in ZIMMO_PROXY and run under xvfb-run. Before it opens a browser, the scraper sends one small test request through the proxy. If the proxy answers 407 (it didn't accept the login) or 402 (the balance ran out), the run ends within a couple of seconds with code 5 instead of grinding through retries for minutes. If you pass a list of proxies with --proxy-file, every address gets checked, and the ones that refuse are dropped for the rest of the run. The Proxy API docs explain how to generate such a list.
Keep an eye on traffic, since proxies are billed by the megabyte. The scraper counts traffic and stops at 10 MB by default (the --proxy-budget-mb flag; 0 removes the cap). In a test on October 28 one page through a German home IP came to about 2.6 MB, so the default covers roughly three pages. For four or more, budget about 3 MB per page. Otherwise the run stops early with code 6 and stop_reason proxy_budget_exceeded.
There's a --block-media flag that skips images, video and fonts. On Zimmo it barely makes a difference. Three pages came to 8.1 MB with it and 7.8 MB without. Most of the weight here is scripts, not pictures.
With 2Captcha Browser API
This is the easiest option for a server, since you don't need your own residential address or display. Put the connection address in .env and run without --headful:
bash
# .env
ZIMMO_CDP_ENDPOINT=ws://{login}-zone-scraping_browser-country-be-pid-{profileId}:{password}@cb.2captcha.com:9222
bash
python3 playwright_scraper.py --url "https://www.zimmo.be/nl/gent-9000/te-koop/" --pages 3
Use the same profile id (pid) from run to run. The profile keeps its cookies, and with them Cloudflare's trust. Since version 1.2.1 the scraper holds one connection for all pages. It used to reconnect for every page and got an HTTP 500 refusal on roughly every second one (measured October 7).
If connecting returns HTTP 401 deny_no_user, the profile's credentials aren't being accepted anymore. The run exits with code 5 and points you at ZIMMO_CDP_ENDPOINT. The code is fine. Get a fresh connection address as described in the Browser API docs. Selenium can't connect to a password-protected remote browser, so use Playwright or Puppeteer for this.
Captchas and Scraper API
Captcha solving is built into the scraper, but on Zimmo you'll rarely need it. With a home IP and a browser with a window, no challenge appeared at all. What Zimmo shows other visitors is a Cloudflare Managed Challenge: a challenge page with a hidden Turnstile field and no sitekey in the HTML. 2Captcha does solve Cloudflare challenge pages. You inject a script before the page loads, intercept turnstile.render to get the sitekey, action, cData and chlPageData, send them as a Turnstile task, then call the page's callback with the token and use the userAgent returned with it. The Cloudflare Turnstile docs describe this step by step. The current zimmo-scraper doesn't implement that interception yet. It only looks for a sitekey in the page's HTML, finds none, marks the page as blocked without spending anything and points you to the Browser API. The Browser API's built-in auto-solve was tested against this challenge, and so was the Scraper API, with and without a Browser API session. Each got through on some runs and failed on others with exactly the same setup, so budget for retries. The scraper also ships a reCAPTCHA v3 solver, but reCAPTCHA hasn't been seen on Zimmo. Whatever the challenge, a page buys at most one paid solve.
2Captcha Scraper API isn't running smoothly on Zimmo at the moment. On September 23 it returned the page at $0.0005 per request. On October 28, though, it twice returned Zimmo's own "0 resultaten" page for the same Ghent search, while the Browser API read 63 listings that day. A Brussels request timed out altogether. That's why the scraper doesn't treat a Scraper API page without listings as an empty search and exits with code 5 instead.
Output files and exit codes
After a run you'll have <out>.json and/or <out>.csv, plus <out>.meta.json next to them. That file records how the run ended (complete, partial or empty) and why (stop_reason), which pages failed, how many rows were collected, which search it covered (selection) and whether it read the results to the end (listing_exhausted). Runs through a proxy also log the traffic used there. Such runs also write <out>.latest_attempt.meta.json whatever happens, even with no rows.
If a run finds nothing, it writes nothing, and yesterday's file stays where it was. If you really want an empty file, there's --allow-empty. Files are replaced atomically, and the CSV escapes cells that look like Excel formulas.
| Code | What happened | What to do |
|---|---|---|
| 0 | Everything collected | Data written. |
| 1 | Crash | A bug in the scraper; look at the traceback. |
| 2 | Bad command | For example, a link with page in it, an --out folder you can't write to, a malformed proxy, --concurrency together with --cdp-endpoint. |
| 3 | Blocked | Cloudflare didn't let you in. Add --headful, a residential proxy or the Browser API. |
| 4 | No listings | The search really has no results. |
| 5 | Pages not obtained | The proxy rejected the login or ran out of balance, the Browser API rejected the profile, a timeout, an error or 404 on page 1, the parser read nothing, or the traffic cap ran out before the first row. |
| 6 | Partly collected | Some pages didn't load or didn't parse, the traffic cap ran out, or you pressed Ctrl-C. The reason is in stop_reason. |
| 130 | Interrupted | Ctrl-C before the first row was collected. |
Following the market
The repository includes diff_runs.py. It compares two complete runs of the same search by sku and shows which listings appeared, which disappeared and where the price changed:
bash
python3 diff_runs.py --old gent_2026-10-01.json --new gent_2026-10-08.json
It won't compare incomplete runs or runs of different searches. You can override that with --allow-selection-mismatch, but you probably shouldn't. There's one more subtlety. If the newer run didn't read the whole search because it ran out of --pages, a missing listing is marked "left selection" rather than removed. New listings may simply have pushed it onto the next page. Only a run that reached the end of the search can tell you a listing was really taken down, so for monitoring, give --pages some headroom.
A sample row
A real row from sample_output.json in the repository: Ghent, for sale, September 23, 2026. We've shortened the photo link.
json
{
"source": "zimmo.be",
"scraped_at": "2026-09-23T14:20:10.757167+00:00",
"url": "https://www.zimmo.be/nl/gent-9000/te-koop/huis/LRZLA",
"sku": "LRZLA",
"title": "Huis te koop",
"brand": null,
"price": 210000.0,
"currency": "EUR",
"original_price": null,
"discount_pct": null,
"image_url": "https://files.zimmo.be/backend-api/…/images/01a0ce69-9587-7761-9b6a-30c604f1d540",
"category": "gent-koop",
"listing_type": "sale",
"property_type": "huis",
"location": "Zwijnaardsesteenweg 685 9000 Gent",
"surface_m2": null,
"bedrooms": 3,
"epc_label": "F",
"epc_value": null
}
This listing doesn't give a living area, so surface_m2 is empty. The sample has 21 rows in total: 12 houses, 6 apartments, a new-build project, a commercial property and a garage.
Crunching the market
Let's start with the median price and price per square metre for each type of home, plus how the energy grades are spread. The script throws out new-build projects, since their price is the cheapest unit. Listings without a price, garages and commercial property go too, or they'd skew the picture for housing.
python
import json
from collections import Counter, defaultdict
from pathlib import Path
from statistics import median
RESIDENTIAL = {"huis", "appartement"} # property types as the Dutch site names them
def snapshot(results_file: str) -> None:
path = Path(results_file)
rows = json.loads(path.read_text(encoding="utf-8"))
meta_path = Path(f"{path.with_suffix('')}.meta.json")
if meta_path.exists():
meta = json.loads(meta_path.read_text(encoding="utf-8"))
print(f"Run status: {meta.get('status')}, rows: {len(rows)}")
homes = [
r for r in rows
if r.get("price")
and r.get("property_type") in RESIDENTIAL
and r.get("title") != "Project"
]
by_type = defaultdict(list)
for r in homes:
by_type[r["property_type"]].append(r)
for ptype, items in by_type.items():
prices = [r["price"] for r in items]
per_m2 = [r["price"] / r["surface_m2"] for r in items if r.get("surface_m2")]
line = f"{ptype:<12} n={len(items):<3} median €{median(prices):,.0f}"
if per_m2:
line += f" median €{median(per_m2):,.0f}/m² (n={len(per_m2)})"
print(line)
grades = Counter(r.get("epc_label") or "none" for r in homes)
print("EPC:", ", ".join(f"{g} {n}" for g, n in grades.most_common()))
if __name__ == "__main__":
snapshot("gent_listings.json")
The script only works out price per metre where an area is given, and it tells you how many listings that was. Run it across several towns, or across weekly exports for one town, and you've got a simple price index. diff_runs.py will then show you what came onto the market and what left it during the week.
Limitations
The scraper doesn't work on Zimmo without a window. Cloudflare refuses headless Chromium even from a home IP, so you need --headful, xvfb or the Browser API. The Docker image is no exception. It starts the browser without a window by default, so use it with --cdp-endpoint or bring your own display.
Not every address works. Datacentres and a US home IP were refused, while Belgian and German ones got through.
The brand, original_price, discount_pct and epc_value fields are always empty right now. New-build prices are a lower bound, so it's best to filter out rows titled "Project".
French searches sometimes end as partial, because the scraper doesn't yet know how the French site says "no results".
On Apple Silicon Macs, pyppeteer downloads an x86 Chromium that crashes straight away without a window (checked October 28). Stick with Playwright there.
fingerprint_client.py ships with the repository, but none of the engines use it yet.
Common questions
Is it legal to scrape Zimmo?
The scraper reads public search pages and never logs in. The rows do contain full street addresses, though, and combined with other data those can count as personal data under the GDPR. Read Zimmo's terms, check the law where you are, and don't flood the site with requests. This isn't legal advice.
Does Zimmo have an API?
There's no public API for listings. Even the page itself doesn't hold the data in a convenient form, which is why the scraper reads the tiles.
Why does my run exit with code 3?
Cloudflare didn't let you in. Most often the browser had no window, and --headful fixes it. Otherwise the run came from a datacentre address, and you need a residential proxy or the Browser API.
Do I have to use a Belgian IP?
No, a German home IP got through as well. A US one was refused on October 13, so a European address is the safer bet.
How much traffic does a run use?
About 2.6 MB per page through a residential proxy (measured October 28). The default 10 MB is enough for about three pages; for more, raise --proxy-budget-mb.
Wrapping up
With Zimmo, the hard part is getting the site to hand over a page at all. Cloudflare wants to see a home address and a browser with a window. At home that's one flag; on a server you'll add a residential proxy and xvfb, or use 2Captcha Browser API. The rest is easier. The scraper recognises fields by their icons, so it works the same on both language versions, and it tells you plainly whether it read the search to the end. Just remember to drop new-build projects, only work out price per metre where there's an area, and compare weeks with diff_runs.py.
Getting started: clone the repository and run it at home with --headful. For a server, sign up for 2Captcha and add residential proxies or 2Captcha Browser API.
Source code
- Repository: github.com/2scraper/zimmo-scraper (MIT)
- All scrapers: github.com/2scraper
Documentation
- Quick start: API key, first request, first result.
- Browser API docs: CDP endpoint and profile options.
- Proxy API: generating residential proxy lists.
- Scraper API: fetching pages without a browser.
- Cloudflare Turnstile: solving Turnstile widgets and Cloudflare challenge pages.
- Error codes and request limits.
Related guides
- How to run the 2scraper open-source scrapers: setup, exit codes and access modes for every repository.
- How to scrape Avito: classifieds, real estate included, behind a firewall with GeeTest.
- How to scrape SHEIN: embedded page JSON and a check with image puzzles.
- How to scrape Google Play: per-country ratings and full review histories.
- How to scrape Transfermarkt: AWS WAF and pagination traps.