# Homes.bg Scraper - Bulgarian Real Estate (`studio-amba/homes-bg-scraper`) Actor

Scrape property listings from Homes.bg, a major Bulgarian real estate portal. Apartments, houses, land and plots for sale and rent with price, price per square metre, area, floor, heating, features, photo and agent contact. No login needed.

- **URL**: https://apify.com/studio-amba/homes-bg-scraper.md
- **Developed by:** [Studio Amba](https://apify.com/studio-amba) (community)
- **Categories:** Real estate
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.20 / 1,000 result scrapeds

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/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

## Homes.bg Scraper

Scrape property listings from Homes.bg, a large Bulgarian real estate portal. The portal's sitemaps list about 46,000 apartments for sale, 13,000 apartments for rent, 10,000 houses for sale, 13,000 plots and 3,000 pieces of agricultural land. Each listing comes back as one structured row: price, price per square metre, area, rooms, floor, heating, construction, features, description, photo and the agent's contact details.

### Why use this actor?

- Price in euro with price per square metre on each listing
- Apartments, houses, agricultural land and plots, for sale, and apartments and houses for rent
- Newest listings first, because the actor reads the portal's own sitemap ordered by last change
- Filter by city or neighbourhood, for example Sofia, Plovdiv, Varna or Burgas
- Agency name, agent name, agent phone number and agency website
- Floor, total floors, heating, furnishing, construction and condition
- Extras such as lift, parking, air conditioning and security
- Every attribute the listing shows is also returned in an `attributes` object, so nothing on the page is lost
- Runs on plain HTTP, no login and no browser, so a run of 100 listings finishes in about a minute

### How to scrape Homes.bg data

1. Open the actor on Apify and press Try for free.
2. Choose For sale or For rent.
3. Choose a property type.
4. Type a city in Latin letters if you want only one city, for example `sofiya`. Leave it empty for all of Bulgaria.
5. Set Max results. The default is 50, the maximum is 5000 per run.
6. Press Start. The listings appear in the Output tab and can be exported as JSON, CSV, Excel or through the API.

Example input for apartments for sale in Sofia:

```json
{
  "transactionType": "sale",
  "propertyType": "apartment",
  "city": "sofiya",
  "maxResults": 100
}
```

Example input for houses for rent across Bulgaria:

```json
{
  "transactionType": "rent",
  "propertyType": "house",
  "maxResults": 200
}
```

### Input

| Field | Type | Description |
|---|---|---|
| `transactionType` | string | `sale` or `rent`. Default `sale`. |
| `propertyType` | string | `apartment`, `house`, `land` (agricultural land) or `plot`. Default `apartment`. Land and plots are listed for sale only. |
| `city` | string | City or area in Latin letters as it appears in the listing address, for example `sofiya`, `plovdiv`, `varna`. Several values can be separated with commas. Empty means all of Bulgaria. |
| `maxResults` | integer | Maximum listings per run, 1 to 5000. Default 50. |
| `proxyConfiguration` | object | Apify proxy settings. The automatic pool is the default. |

### Output

Each row has these fields. A field the listing does not state is `null`.

| Field | Description |
|---|---|
| `listingId` | Portal listing id, for example `as1710298` |
| `url` | Listing page |
| `title` | Listing title in Bulgarian |
| `transactionType`, `propertyType` | Sale or rent, and the property type you searched |
| `propertyTypeSlug` | Property type as the portal names it in the address |
| `rooms`, `roomType` | Number of rooms and the portal's room word (`dvustaen` is a two-room flat) |
| `city`, `neighbourhood`, `location` | City, neighbourhood and the full location line |
| `price`, `currency`, `priceUnit` | Price as a number, currency, and `total` or `per_month` |
| `pricePerSqm` | Price per square metre as shown by the portal |
| `area` | Area in square metres |
| `furnishing`, `floor`, `totalFloors` | Furnishing, floor and number of floors in the building |
| `heating`, `construction`, `condition` | Heating type, construction type and condition |
| `referenceNumber` | Agency reference number, when the description states one |
| `description` | Full listing text in Bulgarian |
| `features` | Extras such as lift, parking and air conditioning |
| `imageUrl`, `imageUrls` | Main photo |
| `agentName`, `agentPhone` | Agent contact |
| `agencyName`, `agencyWebsite` | Agency |
| `views` | View count shown on the listing |
| `lastModified` | Last change date from the portal's sitemap |
| `attributes` | Every attribute row of the listing as shown on the page |
| `scrapedAt` | Timestamp of the scrape |

#### Sample output

```json
{
  "listingId": "as1711111",
  "title": "Тристаен апартамент за продажба, 78m²",
  "transactionType": "sale",
  "propertyType": "apartment",
  "rooms": 3,
  "city": "София",
  "neighbourhood": "жк. Лозенец",
  "price": 339000,
  "currency": "EUR",
  "priceUnit": "total",
  "pricePerSqm": 4346,
  "area": 78,
  "furnishing": "Обзаведен",
  "floor": "1-ви",
  "totalFloors": "4",
  "heating": "Електричество",
  "construction": "Тухла",
  "features": ["Паркомясто", "Климатик"],
  "agencyName": "iHOME Real Estate"
}
```

### Cost and performance

The actor is billed per result. Each listing opens one detail page, so the run time grows in step with Max results. The portal's sitemap files hold up to 1,000 listings each and are read in order, newest first. The usage cost of a run only settles after the run has SUCCEEDED.

### Limitations

- The city filter matches the Latin spelling in the listing address, so `sofiya` finds Sofia and `plovdiv` finds Plovdiv. Spellings follow the portal's own address format.
- A city filter reads sitemap files in order until it has enough matches, so a small city with few listings makes the run read many files.
- Only the main photo is returned. The portal loads the rest of the gallery with a script.
- Listings without a stated price ("price on request") have `price` set to `null`.
- Commercial property and offices are not part of this actor.
- Text fields are in Bulgarian.

### Related Scrapers

- [Imot.bg Scraper](https://apify.com/studio-amba/imot-bg-scraper): Bulgarian real estate portal
- [Reality.iDNES.cz Scraper](https://apify.com/studio-amba/reality-idnes-scraper): Czech real estate portal
- [Otodom Scraper](https://apify.com/studio-amba/otodom-scraper): Poland's largest real estate portal

### Support

Found an issue or need a field added? Open an issue on the actor's Apify Store page.

Automated runs test this actor against the live site and verify the output is complete. When the website changes, the scraper usually gets repaired the same day.

If this actor works for you, a review on its Store page helps other people find it.

# Actor input Schema

## `transactionType` (type: `string`):

Properties for sale or for rent.

## `propertyType` (type: `string`):

Type of property. Houses are listed for sale and rent. Land and plots are listed for sale only.

## `city` (type: `string`):

Optional. City or area in Latin letters as it appears in the listing address, for example sofiya, plovdiv, varna, burgas. Separate several with commas. Leave empty for all of Bulgaria.

## `maxResults` (type: `integer`):

Maximum number of listings to return. Newest listings come first. Capped at 5000 per run.

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

The site answers plain requests. The automatic Apify proxy is the default.

## Actor input object example

```json
{
  "transactionType": "sale",
  "propertyType": "apartment",
  "city": "sofiya",
  "maxResults": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "transactionType": "sale",
    "propertyType": "apartment",
    "city": "sofiya",
    "maxResults": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("studio-amba/homes-bg-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 = {
    "transactionType": "sale",
    "propertyType": "apartment",
    "city": "sofiya",
    "maxResults": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("studio-amba/homes-bg-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 '{
  "transactionType": "sale",
  "propertyType": "apartment",
  "city": "sofiya",
  "maxResults": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call studio-amba/homes-bg-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,studio-amba/homes-bg-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/XulcwTG8HEArhj25K/builds/qDmKGYhO2qZGB417n/openapi.json
