# OLX.bg Real Estate Scraper (`unfenced-group/olxbg-scraper`) Actor Real estate listings scraper for olxbg - **URL**: https://apify.com/unfenced-group/olxbg-scraper.md - **Developed by:** [Unfenced Group](https://apify.com/unfenced-group) (community) - **Categories:** Real estate - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.20 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ## OLX.bg Scraper ![olxbg-scraper](https://api.apify.com/v2/key-value-stores/lJlifu6C8YQfZMPKE/records/olxbg-scraper) Scrape real estate listings from [OLX.bg](https://www.olx.bg) — Bulgaria's largest classifieds platform — dominant in real estate. Filter by transaction type, Bulgarian region/city, property type, and price range. No API key required. --- ### Why this scraper? #### ⚡ Fast & cost-efficient extraction Pure REST API — no browser, no HTML parsing. Direct JSON responses from OLX.bg's official internal API. #### 🏠 Market coverage 60,000+ Bulgarian property listings across all 28 oblasts and Sofia-grad. #### 💰 Rich structured data 50 fields per listing: price (EUR + BGN), price per m², area, rooms, floor, construction type, heating, furnishing, amenities, GPS coordinates, promotion flags, contact flags, and more. #### 🔍 Flexible filters Filter by transaction (sale/rent), property type, region/city, and price range. Multi-region splitting automatically bypasses the API's 1,000-item-per-query cap. #### 📍 Location & coverage Covers all Bulgarian oblasts: Sofia, Plovdiv, Varna, Burgas, and all 28 regions. #### 🔗 Direct URL support Pass any OLX.bg real estate search URL via `startUrls` — region and category are auto-detected. --- ### Input parameters | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | `transaction` | string | `sale` or `rent` | `sale` | | `propertyType` | string | `apartment`, `house`, `land`, `garage`, `office`, `commercial` | `apartment` | | `regions` | array | City/region names, e.g. `["sofia","plovdiv","varna"]` | `[]` (all Bulgaria) | | `maxItems` | integer | Maximum listings to scrape | `100` | | `startUrls` | array | Direct OLX.bg real estate URLs — overrides other filters | — | | `minPrice` | integer | Min price in EUR (client-side filter) | — | | `maxPrice` | integer | Max price in EUR (client-side filter) | — | #### Regions / cities Use common city names or full region slugs: | City name | Region slug | |-----------|-------------| | `sofia` | `oblast-sofiya-grad` | | `plovdiv` | `oblast-plovdiv` | | `varna` | `oblast-varna` | | `burgas` | `oblast-burgas` | | `stara-zagora` | `oblast-stara-zagora` | | `ruse` | `oblast-ruse` | | `pleven` | `oblast-pleven` | All 28 Bulgarian oblasts are supported — use the `oblast-{name}` slug format for any region. --- ### Output schema ```json { "id": "147756215", "url": "https://www.olx.bg/d/ad/...", "transaction": "sale", "propertyType": "apartment", "title": "Продавам 3-стаен апартамент", "priceText": "183456.85 лв. / 93800 €", "priceAmount": 93800, "priceCurrency": "EUR", "negotiable": false, "pricePerM2": 2345, "city": "гр. Варна", "citySlug": "varna", "region": "Област Варна", "district": "Общината", "country": "BG", "latitude": 43.19778, "longitude": 27.89139, "areaM2": 40, "rooms": 1, "apartmentType": "1 - стаен", "floor": 5, "totalFloors": 6, "isNotLastFloor": false, "buildYear": 2010, "constructionType": "Тухла", "heating": "Електричество", "furnishing": "Обзаведен", "hasPassage": false, "amenities": ["asansor", "klimatik", "parking", "saniran"], "images": ["https://frankfurt.apollo.olxcdn.com:443/v1/files/.../image;s=800x600"], "agencyName": null, "sellerName": "Иван", "isBusiness": false, "hasPhone": true, "hasChat": true, "isPromoted": true, "isTopAd": true, "isUrgent": false, "publishDate": "2026-04-23", "publishDateISO": "2026-04-23T14:30:20+03:00", "pushedUpAt": "2026-05-05", "lastRefreshDate": "2026-05-05", "validToDate": "2026-05-23", "isRepost": true, "categoryId": 524, "source": "olx.bg", "scrapedAt": "2026-05-06T10:53:37.677Z", "contentHash": "7b2b6a9783b722bf" } ```` #### New fields vs v1.0 | Field | Description | |-------|-------------| | `pricePerM2` | Price per square metre (from API param `ppsp`) | | `citySlug` | City normalized slug, e.g. `varna` | | `district` | Sub-district name within the city | | `isNotLastFloor` | Whether the apartment is NOT on the top floor | | `heating` | Heating type (Електричество, ТЕЦ, etc.) | | `furnishing` | Furnishing status (Обзаведен, Необзаведен, etc.) | | `hasPassage` | Whether the apartment has a passage/through layout | | `amenities` | Array of feature slugs (asansor, parking, klimatik, etc.) | | `sellerName` | Seller's name | | `isBusiness` | `true` if listed by a business account | | `hasPhone` | Whether a phone number is available | | `hasChat` | Whether chat is available | | `isPromoted` | Highlighted or top-ad listing | | `isTopAd` | Paid top-ad placement | | `isUrgent` | Marked as urgent | | `lastRefreshDate` | Date the listing was last refreshed | | `validToDate` | Listing expiry date | *** ### Examples **Apartments for sale in Sofia:** ```json { "transaction": "sale", "propertyType": "apartment", "regions": ["sofia"], "maxItems": 100 } ``` **Rent apartments in Sofia + Plovdiv, filtered by price:** ```json { "transaction": "rent", "propertyType": "apartment", "regions": ["sofia", "plovdiv"], "minPrice": 400, "maxPrice": 800, "maxItems": 200 } ``` **Houses for sale, all of Bulgaria:** ```json { "transaction": "sale", "propertyType": "house", "maxItems": 500 } ``` **Via direct URL:** ```json { "startUrls": [{ "url": "https://www.olx.bg/nedvizhimi-imoti/prodazhbi/kaschi-vili/oblast-plovdiv/" }], "maxItems": 50 } ``` *** **Daily feed of new listings (run on a schedule):** ```json { "daysOld": 1, "maxItems": 500 } ``` Schedule this input to run once a day in the Apify Scheduler — each run returns only listings added in the last 24 hours, ideal as a daily new-listings alert. ### 💰 Pricing **$1.50 per 1,000 results** — you only pay for successfully retrieved listings. Failed retries are never charged. | Results | Cost | |---------|------| | 100 | ~$0.15 | | 1,000 | ~$1.50 | | 10,000 | ~$15.00 | | 100,000 | ~$150.00 | > Flat-rate real estate data providers typically charge $99–$299/month regardless of usage. > At 10,000 results/month, this scraper costs significantly less with no subscription. *** ### Performance | Run size | Estimated time | |----------|----------------| | 100 listings | ~2–4 min | | 500 listings | ~8–15 min | | 1,000 listings | ~20–30 min | Multi-region runs execute segments sequentially with respectful delays. *** ### Known limitations - **Price currency:** Some listings quote price in BGN only — the EUR equivalent shown uses OLX's own conversion label. - **Contact:** Private seller phone numbers may be masked — full numbers require login. - **Language:** All text fields are returned in Bulgarian Cyrillic. - **API cap:** OLX.bg limits each category+region query to 1,000 results. For high-volume national scrapes, use the `regions` input to split across oblasts (each with its own 1,000 cap). - **Price filter:** OLX.bg's API does not support server-side price filtering — `minPrice`/`maxPrice` are applied client-side after fetching. *** ### Technical details - **Method:** OLX.bg REST API v1 (`/api/v1/offers/`) — no browser, no HTML parsing - **Memory:** 256 MB - **Retry:** Automatic retry on transient errors with exponential backoff - **Deduplication:** Cross-run content hash prevents duplicate listings in repeated runs - **Output fields:** 49 fields *** ### Additional services Need a custom actor, additional filters, scheduled runs, or integration support?.nl]\(mailto:info@unfencedgroup.nl) — we build on request. *** *** ### Need a custom scraper? **[Unfenced Group](https://www.unfencedgroup.nl)** builds Apify actors for any website — for free. If the site you need isn't in our portfolio yet, just ask. We scope, build, and publish it at no cost to you. You only pay for results — we absorb the compute and proxy costs ourselves. Same pay-per-result pricing, same quality, same standards as every actor in this portfolio. **Get in touch:** [www.unfencedgroup.nl](https://www.unfencedgroup.nl) # Actor input Schema ## `transaction` (type: `string`): Whether to scrape listings for sale or for rent. ## `propertyType` (type: `string`): Property type ## `minPrice` (type: `integer`): Filter listings with price at or above this value (EUR). Applied client-side. ## `maxPrice` (type: `integer`): Filter listings with price at or below this value (EUR). Applied client-side. ## `daysOld` (type: `integer`): Only return listings published within the last N days. Leave empty for no recency filter. ## `fetchDetails` (type: `boolean`): If true, opens each listing detail page to extract additional fields (description, floor plan, agent contact). Increases run time and cost. ## `maxItems` (type: `integer`): Max items ## `startUrls` (type: `array`): Optional: pass one or more OLX.bg real estate search URLs directly. Overrides transaction/propertyType/regions if provided. ## `regions` (type: `array`): Filter by Bulgarian region or city. Use city names (e.g. 'sofia', 'plovdiv', 'varna') or region slugs (e.g. 'oblast-plovdiv'). Leave empty for all of Bulgaria. ## Actor input object example ```json { "transaction": "sale", "propertyType": "apartment", "fetchDetails": false, "maxItems": 100, "regions": [] } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = { "maxItems": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("unfenced-group/olxbg-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "maxItems": 100 } # Run the Actor and wait for it to finish run = client.actor("unfenced-group/olxbg-scraper").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 '{ "maxItems": 100 }' | apify call unfenced-group/olxbg-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=unfenced-group/olxbg-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "OLX.bg Real Estate Scraper", "description": "Real estate listings scraper for olxbg", "version": "0.0", "x-build-id": "fkGJeeS26xWyIOQKj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/unfenced-group~olxbg-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-unfenced-group-olxbg-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/unfenced-group~olxbg-scraper/runs": { "post": { "operationId": "runs-sync-unfenced-group-olxbg-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/unfenced-group~olxbg-scraper/run-sync": { "post": { "operationId": "run-sync-unfenced-group-olxbg-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": { "transaction": { "title": "Transaction type", "enum": [ "sale", "rent" ], "type": "string", "description": "Whether to scrape listings for sale or for rent.", "default": "sale" }, "propertyType": { "title": "Property type", "enum": [ "apartment", "house", "land", "garage", "office", "commercial" ], "type": "string", "description": "Property type", "default": "apartment" }, "minPrice": { "title": "Min price (EUR)", "type": "integer", "description": "Filter listings with price at or above this value (EUR). Applied client-side." }, "maxPrice": { "title": "Max price (EUR)", "type": "integer", "description": "Filter listings with price at or below this value (EUR). Applied client-side." }, "daysOld": { "title": "Max listing age (days)", "minimum": 0, "type": "integer", "description": "Only return listings published within the last N days. Leave empty for no recency filter." }, "fetchDetails": { "title": "Fetch listing details", "type": "boolean", "description": "If true, opens each listing detail page to extract additional fields (description, floor plan, agent contact). Increases run time and cost.", "default": false }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Max items", "default": 100 }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Optional: pass one or more OLX.bg real estate search URLs directly. Overrides transaction/propertyType/regions if provided.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "regions": { "title": "Regions / cities", "type": "array", "description": "Filter by Bulgarian region or city. Use city names (e.g. 'sofia', 'plovdiv', 'varna') or region slugs (e.g. 'oblast-plovdiv'). Leave empty for all of Bulgaria.", "default": [], "items": { "type": "string" } } } }, "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 } } } } } } } } } } ```