OLX Real Estate Scraper

Collect public real-estate listings from olx.pl, olx.pt, olx.ro, olx.bg, olx.ua, olx.kz, and olx.in. This independent Actor is not affiliated with OLX.

Only ordinarily accessible public sources are supported. Access challenges stop collection; CAPTCHA solving, authentication bypass and other access-control bypass are not features of this Actor.

The original domain/property/query/location/price/max-listings contract is preserved. European/CIS sources use the public offers API; India joins visible listing cards to public property data embedded in the same HTML. Current public category trees supply the country mappings; keywords retain property scope.

Input

Field	Default	Description
domain	olx.pl	Supported OLX country domain
propertyType	for-sale	Country-specific category filtering: for-sale, for-rent, land, commercial, all
query / location	empty	Keyword search and exact disclosed-geography filter, respectively; existing 200/120-character limits retained
priceMin / priceMax	0	Inclusive asking-price bounds; zero means no bound. Currency comes from the source
maxListings	50	Maximum normal listing rows, 1–200. maxItems remains a compatibility alias
maxPages	10	Maximum public result pages to scan, 1–20, including India Next links
requestTimeoutSecs / requestDelayMs	30 / 0	Public-request timeout and inter-page delay
includeDescription	true	Complete cleaned text supplied by the source. Set false to omit descriptions
includeDiagnostics / deduplicate	true / true	Preserve existing diagnostic and duplicate-handling controls
proxyConfiguration	unset	Existing optional proxy configuration for ordinary public requests; never a permission to bypass a denial

Bounded larger-sample example:

{
  "domain": "olx.pl",
  "propertyType": "all",
  "maxListings": 100,
  "maxPages": 2,
  "requestDelayMs": 1000,
  "includeDescription": true,
  "deduplicate": true,
  "proxyConfiguration": { "useApifyProxy": false }
}

The sample explicitly includes all property types. The default for-sale filter can yield fewer matches from the same pages. Limits are ceilings, not a guarantee that the requested number exists or is accessible.

Country and filter semantics

Public real-estate root IDs are Poland 3, Portugal 16, Romania 3, Bulgaria 368, Ukraine 1 and Kazakhstan 1. Sale/rent matching uses disclosed category ancestry; Romania commercial category 710 additionally uses its explicit alege transaction value. Romania land 709 is classified as sale by its official sale-only category page. Unknown categories fail closed. Ukraine short stays under separate root 3709 are outside this Actor's existing property scope; Kazakhstan short stays inside root 1 are included in rent.

location is an exact post-filter over disclosed city, region or district, with case/Latin-accent normalization. Comma-separated components must all match. It never matches a title or description. maxPages limits the country/category pages scanned, so narrow geographic or price filters can return fewer rows. Asking-price bounds use the source currency, without conversion; unknown prices cannot satisfy an active bound.

Enriched dataset

The default Enriched properties view exposes 32 columns. Property details and source exposes 28 further/detail columns. JSON exports retain every available declared field.

• Full public description, with the former 1,000-character API cap removed
• All exposed photos, without the previous eight-image cap, plus source dimensions/rotation
• Asking price, currency, negotiation flag, source price-per-area and available previous-price metadata
• Generic property area, separate plot area, exact room counts or source minimums, and occupancy labels
• Source furnishings, elevator, pets and parking options, plus separately disclosed additional charges
• City, region, district, displayed coordinates and map-disclosure fields
• Public business-seller company profile fields when disclosed
• Complete typed property parameters, listing/promotion states and source timestamps

Missing fields, undisclosed flags, private contact data and empty collections are not padded. See SOURCE_FIELDS.md for exact paths and caveats.

Important property semantics

• areaM2 remains the existing source display label; areaValue is numeric. The source's generic area can describe land, so it is not automatically living area
• Poland's area parameter is separate plot area
• Source “4 i więcej” means at least four rooms; roomsMinimum: 4 is used rather than an exact four or four bedrooms
• roomCapacity means occupancy, not the room count
• Floor labels can describe a listing floor or house storeys; their localized parameter names and labels remain available
• Parking choices are retained even if the source contains conflicting selections
• additionalRent is the separately labeled additional charge, not the primary asking rent
• Displayed map coordinates can be approximate. Map radius units are not supplied and are not guessed
• Public phone/chat availability flags are not telephone numbers. No phone endpoint, unmasking, account lookup or private-contact retrieval is performed

India enrichment joins visible card order with the same public HTML's listing data and JSON-LD: full disclosed descriptions, all public photo references, raw asking price/currency, geography and typed property parameters. BHK, bathrooms and parking minimums remain distinct from exact counts; square-foot areas are not mislabeled as square metres. Account, verification, permission and phone fields are excluded. No extra detail-page request is needed for these fields.

Pagination and failures

European requests use a fixed API limit up to 50 and follow source-provided same-origin next links. The source may include promoted placements beyond that limit; pagination offsets still follow the source link. Deduplication uses public listing identity unless explicitly disabled.

Only transient responses may be retried. Access-denial and rate-limit statuses are never retried; no alternate route, login, CAPTCHA solving or identity rotation is attempted after a block.

Validated rows are saved as they are collected. If a later source request fails or pagination stalls, those rows remain available, both summaries record the failure, and the Actor exits nonzero. Zero usable listings also fail instead of reporting successful extraction.

Legacy diagnostics retain exactly url, error, errorCode, and scrapedAt. The strict dataset schema now accepts that shape. Diagnostics do not count toward maxListings and are omitted when includeDiagnostics: false, while failure counts remain visible.

Summaries and provenance

OUTPUT remains the compatibility summary. OUTPUT_SUMMARY records status, useful listing/diagnostic counts, request/page/drop/duplicate counts, limits, errors and completion time. Operational fields and proxy configuration are not added to property records.

Existing listing identities, URLs, source/domain/query provenance and timestamps retain their meanings. Public seller account activity/UUID fields are not copied. Masked text in public descriptions is not reconstructed.

Validation scope

On 2026-09-30, two ordinary Poland category-3 requests returned HTTP 200 with 65 records each, including promoted placements: 128 unique listings and two duplicates. The production European runner replayed a bounded 100-row dataset cleanly and the complete captured sample as 128 unique rows. These are fresh source responses plus local runner validation, not a claim that an enriched cloud build was deployed.

Current category trees were verified from ordinary public homepages for Portugal, Romania, Bulgaria, Ukraine and Kazakhstan, and India returned 40 actual property cards with embedded listing data. These source checks do not replace the pending exact-candidate cloud tests for each country. Private phone retrieval and extra detail-site requests were not used.

Development

npm ci
npm run check
npm run validate
npm run validate -- /path/to/a/dataset.json

npm run check runs syntax checks and tests. Dataset validation checks declared nested types, required listing fields, legacy diagnostics, duplicate policy and available local summaries. Use isolated local storage for QA; CRAWLEE_STORAGE_DIR or APIFY_LOCAL_STORAGE_DIR selects it.

test/enriched-multipage-input.json contains the bounded 100-item input. Deterministic local QA also supports exactly one of fixtureFile, fixtureHtml, or fixtureData; these developer-only fixture controls are not added to the public production form. A fixture file must be inside the Actor directory.

Responsible use

Respect the source site's terms, access restrictions, privacy obligations and rate limits. Descriptions and property values are untrusted source content. Use disclosed information for appropriate property research; do not infer sensitive personal attributes or precise private residence details from approximate map points.