# Homedy Real Estate Scraper (`crawlerbros/homedy-real-estate-scraper`) Actor

Scrape homedy.com - a leading Vietnam real estate marketplace. Browse by category (apartment, house, land, office, ...) and province, or fetch full listing detail by URL. Prices, area, description, images.

- **URL**: https://apify.com/crawlerbros/homedy-real-estate-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Real estate, Automation, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Homedy Real Estate Scraper

Scrape [homedy.com](https://homedy.com) — a leading Vietnam real estate marketplace. Browse listings by category (apartment, house, land, office, ...) and province, or fetch full detail for specific listing URLs. No login, no cookies, no residential proxy required.

### What this actor does

- **Three modes:** `search` (browse by category + province, with sort and price/area filters), `byUrl` (fetch specific listings directly), and `project` (fetch a development's own overview — developer, land area, unit count, sale status, on-site amenities — by project URL)
- **11 property/transaction categories:** apartments, houses, villas, land, offices — for sale or for rent
- **Vietnamese price/area parsing:** `"2,6 Tỷ"` and `"59 m2"` are parsed into plain numeric VND and m² fields alongside the original display text
- **Optional detail enrichment:** full description, district, complete image gallery, posted/expiry dates, listing type (sale/rent), property type, house direction, and poster (agent) contact info
- **Empty fields are omitted** — every record only contains fields that were actually extracted

### Modes

#### Search (`mode: "search"`)

Browse listings by `category` (property + transaction type) and `province`. Supports client-side `sortBy` (price/area ascending or descending — homedy.com's own sort control is JavaScript-only and not reachable via a URL parameter, so this actor fetches the category pages and sorts the collected results itself) plus `minPriceBillionVnd`/`maxPriceBillionVnd` and `minAreaM2`/`maxAreaM2` filters.

#### By URL (`mode: "byUrl"`)

Fetch one or more specific listing detail pages directly by URL (`listingUrls`) — always returns the full enriched record (full description, all images, district, posted/expiry dates, listing type).

#### Project (`mode: "project"`)

Fetch one or more homedy.com project (dự án) overview pages directly by URL (`projectUrls`) — a project page describes an entire development (developer, land area, unit count, sale status, active-listings count), not one for-sale/for-rent unit. Project URLs end in `-pj<id>`, e.g. `https://homedy.com/astral-city-pj76427740`.

### Output fields

#### `listing` records (`search` / `byUrl` modes)

| Field | Description |
|---|---|
| `listingId` | Numeric homedy.com listing ID |
| `title` | Listing title |
| `sourceUrl` | Canonical listing page URL |
| `priceText` | Display price as shown on site (e.g. `"2,6 Tỷ"`) |
| `priceVnd` | Parsed price in plain VND (omitted for negotiable-price listings) |
| `areaText` | Display area (e.g. `"59 m2"`) |
| `areaM2` | Parsed area in m² |
| `pricePerM2Text` | Display price per m² |
| `pricePerM2Vnd` | Parsed price per m² in VND |
| `address` | Full display address |
| `province` | Province / city name |
| `district` | District name (detail mode / `enrichDetail`) |
| `description` | Listing description |
| `imageUrl` | Primary listing image |
| `imageUrls[]` | Full image gallery (detail mode / `enrichDetail`) |
| `publishedRelative` | Relative publish time as shown on site, e.g. `"2 ngày trước"` (search mode) |
| `postedDate` | Original posting date, ISO `yyyy-mm-dd` (detail mode / `enrichDetail`) |
| `expiryDate` | Listing expiry date, ISO `yyyy-mm-dd` (detail mode / `enrichDetail`) |
| `listingType` | `"sale"` or `"rent"`, as declared on the listing itself (detail mode / `enrichDetail`) |
| `propertyType` | Property type as declared on the listing, e.g. `"Căn hộ"` (apartment), `"Nhà riêng"` (private house) (detail mode / `enrichDetail`) |
| `houseDirection` | House-facing direction, e.g. `"Đông-Bắc"` (Northeast), when the poster specified one (detail mode / `enrichDetail`) |
| `balconyDirection` | Balcony-facing direction, when the poster specified one (detail mode / `enrichDetail`) |
| `bedroomCount` | Number of bedrooms, when the poster specified one (detail mode / `enrichDetail`) |
| `floorCount` | Number of floors/stories, when the poster specified one (detail mode / `enrichDetail`) |
| `isCornerUnit` | Whether the unit is a corner unit (`true`/`false`), when the poster specified it (detail mode / `enrichDetail`) |
| `furnishing` | Furnishing level, e.g. `"cơ bản"` (basic), when the poster specified one (detail mode / `enrichDetail`) |
| `amenities[]` | In-unit interior/furniture amenities the poster tagged (e.g. `"Bình nóng lạnh"` water heater, `"Tủ bếp"` kitchen cabinets, `"Giường ngủ"` bed), when the listing has an amenities section (detail mode / `enrichDetail`) |
| `legalStatus` | Legal/title-deed status, when the poster filled it in rather than leaving the site's `"--"` placeholder (detail mode / `enrichDetail`) |
| `posterName` | Display name of the agent/owner who posted the listing (detail mode / `enrichDetail`) |
| `posterUrl` | Link to the poster's public homedy.com profile page (detail mode / `enrichDetail`) |
| `posterPhone` | The poster's contact phone number (detail mode / `enrichDetail`) |
| `posterListingsCount` | Total number of active listings posted by that agent/owner (detail mode / `enrichDetail`) |
| `recordType` | Always `"listing"` |
| `scrapedAt` | UTC ISO timestamp |

#### `project` records (`project` mode)

| Field | Description |
|---|---|
| `projectId` | Numeric homedy.com project ID |
| `projectName` | Project/development name |
| `sourceUrl` | Canonical project page URL |
| `address` | Full display address |
| `province` | Province / city name |
| `propertyCategory` | Property type sold in this project, e.g. `"Căn hộ"` (apartment) |
| `priceFromText` / `priceFromVnd` | Starting price, display text and parsed VND |
| `landAreaText` / `landAreaM2` | Total land area, display text and parsed m² |
| `constructionAreaText` | Total construction/floor area (when published) |
| `startDate` / `completionDate` | Construction start / handover timeframe (when published) |
| `buildingCount` | Number of buildings/blocks (when published) |
| `unitCount` | Number of units/products (when published) |
| `unitAreaRangeText` | Range of unit sizes offered, e.g. `"45;90"` (when published) |
| `status` | Sale status, e.g. `"Đang mở bán"` (now selling) |
| `developerName` / `developerUrl` | Developer/investor name and homedy.com profile link |
| `activeListingsCount` / `activeListingsUrl` | Count and link to this project's currently active for-sale/for-rent listings |
| `amenities[]` | On-site amenities the project advertises, e.g. `"Bể bơi ngoài trời"` (outdoor pool), `"Trường mầm non"` (kindergarten), `"Hệ thống PCCC"` (fire-safety system) — grouped categories (facilities, security, education, dining, sports, etc.) flattened into one list |
| `imageUrl` / `imageUrls[]` | Project cover image / gallery |
| `recordType` | Always `"project"` |
| `scrapedAt` | UTC ISO timestamp |

Fields marked "when published" are frequently shown as `"Đang cập nhật"` (updating) on homedy.com itself — the actor omits those rather than emitting a placeholder string.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` / `byUrl` / `project` |
| `category` | string | `ban-nha-dat` | 11 curated property + transaction type combinations (mode=search) |
| `province` | string | `ha-noi` | 15 curated major provinces/cities, or blank for all Vietnam (mode=search) |
| `customProvinceSlug` | string | – | URL slug of any Vietnamese province not in the dropdown, overrides `province` (mode=search) |
| `districtSlug` | string | – | Narrow to one district/ward within the chosen province, e.g. `quan-ba-dinh`, `quan-1` (mode=search, requires `province`/`customProvinceSlug`) |
| `keyword` | string | – | Free-text term submitted to homedy.com's own search box — a relevance boost, not a strict substring filter (mode=search) |
| `sortBy` | string | site order | Price/area ascending or descending, applied client-side (mode=search) |
| `minPriceBillionVnd` / `maxPriceBillionVnd` | number | – | Price range in billion VND (tỷ). For sale listings typical values are `1`-`50`+. For rental categories (`cho-thue-*`), prices are monthly rent in millions VND — use small fractional values (e.g. `0.01` = 10 million VND/month) |
| `minAreaM2` / `maxAreaM2` | number | – | Area range in m² |
| `listingUrls` | array | `[]` | Full homedy.com listing detail URLs, must end in `-es<id>` (mode=byUrl) |
| `projectUrls` | array | `[]` | Full homedy.com project URLs, must end in `-pj<id>` (mode=project) |
| `enrichDetail` | boolean | `false` | Fetch each listing's detail page for full description, district, image gallery (mode=search) |
| `maxItems` | integer | `30` | Hard cap on emitted records (1-500) |
| `proxyConfiguration` | object | Apify Proxy (auto) | homedy.com is reachable directly; proxy only engages automatically on a 403/429 |

#### Example: browse apartments for sale in Hanoi

```json
{
  "mode": "search",
  "category": "ban-can-ho-chung-cu",
  "province": "ha-noi",
  "minPriceBillionVnd": 2,
  "maxPriceBillionVnd": 5
}
```

#### Example: browse rentals in a specific district with full detail

```json
{
  "mode": "search",
  "category": "cho-thue-nha-rieng",
  "province": "tp-ho-chi-minh",
  "districtSlug": "quan-1",
  "enrichDetail": true
}
```

#### Example: fetch specific listings by URL

```json
{
  "mode": "byUrl",
  "listingUrls": ["https://homedy.com/ban-can-ho-chung-cu-vinhomes-es12345678"]
}
```

#### Example: fetch a project overview

```json
{
  "mode": "project",
  "projectUrls": ["https://homedy.com/astral-city-pj76427740"]
}
```

### Use cases

- **Real estate investors** — screen apartments/houses/land by price and area range across a province
- **Market research** — build a comparison dataset of listings by category and location
- **Rental market tracking** — monitor rental price trends in a specific district over time
- **Developer/project research** — pull a development's unit count, sale status, and amenities from its project page
- **Lead generation** — collect poster (agent) contact info for outreach via `enrichDetail`

### Limitations

- homedy.com's sort dropdown is rendered entirely client-side (no working server-side sort query parameter was found after live testing) — `sortBy` is therefore applied locally to the fetched results rather than passed upstream.
- `keyword` is submitted as homedy.com's own `?keyword=` query parameter (verified live: deterministic, same term always returns the same result set). It behaves as a relevance boost rather than a strict substring filter — some returned listings may not literally contain the term in their title/description, matching the site's own search-box behavior.
- `province` ships a curated list of 15 major provinces/cities; use `customProvinceSlug` for the remaining Vietnamese provinces (URL-slug form, e.g. `thua-thien-hue`, `an-giang`).
- `bedroomCount`, `legalStatus`, `balconyDirection`, `floorCount`, `isCornerUnit`, and `furnishing` come from each listing's structured "product attributes" block on the detail page (`enrichDetail` mode) — they're only emitted when the poster actually filled them in; homedy.com's own `"--"` placeholder for unset attributes is treated as empty and omitted rather than passed through literally. Bathroom count was not found as a structured attribute on any sampled listing and is therefore not included.

### FAQ

**Is this affiliated with homedy.com?** No, this is a third-party actor built against homedy.com's public pages; it is not affiliated with or endorsed by homedy.com.

**Do I need a proxy or login?** No — every request runs against homedy.com's public, unauthenticated pages directly. A proxy input is exposed and automatically engaged as a fallback only if a run is ever blocked (403/429), but it isn't required in normal operation.

**Why is `priceVnd` sometimes missing?** Some listings display `"Thỏa thuận"` (negotiable/by agreement) instead of a price — that's real data, not a parsing failure, so no price field is emitted rather than a fake `0` or `null`.

**What's the difference between `search` fields and `enrichDetail` fields?** The browse/category page already contains price, area, price/m², address, description, image, and publish time. Turning on `enrichDetail` adds one extra request per listing to also capture the full description, complete image gallery, and district — useful for smaller batches where completeness matters more than speed.

**How current is the data?** Real-time — every run fetches homedy.com's live pages directly.

**Can I search a province that isn't in the dropdown?** Yes — set `customProvinceSlug` to the URL slug of any Vietnamese province (e.g. `thua-thien-hue`); it overrides `province` when set.

# Actor input Schema

## `mode` (type: `string`):

What to fetch.

## `category` (type: `string`):

Property type + transaction type.

## `province` (type: `string`):

Restrict to one province/city. Leave blank for all of Vietnam. Use `Custom province slug` to target a province not in this curated list.

## `customProvinceSlug` (type: `string`):

URL slug of any Vietnamese province not in the dropdown, e.g. `thua-thien-hue`, `binh-thuan`, `an-giang`. Takes priority over `province` when set.

## `districtSlug` (type: `string`):

URL slug of a district/ward within the chosen province to narrow results further, e.g. `quan-ba-dinh`, `quan-1`, `thanh-pho-thu-duc`, `quan-cau-giay`. Has no effect if `province`/`customProvinceSlug` is not set (homedy.com has no district-only browse URL).

## `listingUrls` (type: `array`):

Full homedy.com listing detail URLs (must end in `-es<id>`).

## `projectUrls` (type: `array`):

Full homedy.com project (dự án) URLs (must end in `-pj<id>`), e.g. `https://homedy.com/astral-city-pj76427740`. Returns the project's own overview (developer, land area, unit count, sale status) rather than a single unit's listing.

## `keyword` (type: `string`):

Free-text term submitted to homedy.com's own search box (e.g. `vinhomes`, `chung cư`, `biệt thự`). Re-ranks/biases browse results toward listings whose title or description match the term — a relevance boost like the site's own search, not a strict substring filter, so some results may still not literally contain the term.

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

Client-side sort applied to collected results (homedy.com's own sort UI is JavaScript-only and not reachable via URL, so this actor sorts the fetched page results itself).

## `minPriceBillionVnd` (type: `number`):

Drop listings cheaper than this, in billion VND (tỷ). E.g. 2 = 2,000,000,000 VND. Listings with no parseable price (e.g. "Thỏa thuận"/negotiable) always pass.

## `maxPriceBillionVnd` (type: `number`):

Drop listings more expensive than this, in billion VND (tỷ).

## `minAreaM2` (type: `number`):

Drop listings smaller than this area in square meters.

## `maxAreaM2` (type: `number`):

Drop listings larger than this area in square meters.

## `enrichDetail` (type: `boolean`):

When on, each listing is enriched with a detail-page fetch adding the full description, district, and complete image gallery. When off (default), only fields visible on the browse page are emitted and the run is much faster.

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

Hard cap on emitted records.

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

homedy.com is reachable directly from Apify's datacenter IPs in testing. The actor tries a direct connection first and only engages this proxy on a 403/429 — leave the default (Apify Proxy, automatic) unless your runs are consistently blocked.

## Actor input object example

```json
{
  "mode": "search",
  "category": "ban-nha-dat",
  "province": "ha-noi",
  "listingUrls": [],
  "projectUrls": [],
  "sortBy": "",
  "enrichDetail": false,
  "maxItems": 30,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `listings` (type: `string`):

Dataset containing all scraped homedy.com listings.

# 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 = {
    "mode": "search",
    "category": "ban-nha-dat",
    "province": "ha-noi",
    "listingUrls": [],
    "projectUrls": [],
    "sortBy": "",
    "enrichDetail": false,
    "maxItems": 30,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/homedy-real-estate-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 = {
    "mode": "search",
    "category": "ban-nha-dat",
    "province": "ha-noi",
    "listingUrls": [],
    "projectUrls": [],
    "sortBy": "",
    "enrichDetail": False,
    "maxItems": 30,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/homedy-real-estate-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 '{
  "mode": "search",
  "category": "ban-nha-dat",
  "province": "ha-noi",
  "listingUrls": [],
  "projectUrls": [],
  "sortBy": "",
  "enrichDetail": false,
  "maxItems": 30,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call crawlerbros/homedy-real-estate-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=crawlerbros/homedy-real-estate-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1AJ57KnkoV3wXhbeq/builds/ExbZkTmnPJjTfZlOl/openapi.json