# Batdongsan Scraper - Vietnam Property Data (`sian.agency/batdongsan-property-scraper`) Actor

Scrape Batdongsan.com.vn listings across Vietnam: price in VND and USD, area, price per m², bedrooms, district, agent, verified badge and posted date. Sale and rent. JSON, CSV or Excel.

- **URL**: https://apify.com/sian.agency/batdongsan-property-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** Real estate, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.32 / 1,000 property searches

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?

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

## Batdongsan Scraper — Vietnam Property Data, Prices & Agents 🚀

[![Store-SIÁN Agency](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Store-99.co Singapore](https://img.shields.io/badge/Store-99.co%20Singapore-1AE392)](https://apify.com/sian.agency/99co-property-scraper?fpr=sian) [![Store-SUUMO Japan](https://img.shields.io/badge/Store-SUUMO%20Japan-1AE392)](https://apify.com/sian.agency/suumo-property-scraper?fpr=sian) [![Store-Dabang Korea](https://img.shields.io/badge/Store-Dabang%20Korea-1AE392)](https://apify.com/sian.agency/dabang-property-scraper?fpr=sian)

#### 🇻🇳 Every asking price on Vietnam's biggest property portal, as a number you can sort

##### For analysts and agencies who are tired of reading "4,99 tỷ" out of a browser tab

### 🔎 What is the Batdongsan Scraper — and when should you use it?

The **Batdongsan Scraper** turns Vietnam property listings, prices and agents from Batdongsan.com.vn into clean, structured rows you can filter, export and feed straight into a spreadsheet, database or AI agent. No account, no portal API key, no browser automation to maintain.

**Use it when you need:** asking prices in dong and in dollars, floor area in square metres, price per square metre, bedrooms, bathrooms, district and ward. Every row also carries the advert summary, its photos, the account that posted it with its Batdongsan id and public profile, the verified badge, the advert's promotion tier and the exact date it went up. Property for sale or for rent, in any Vietnamese province, across fifteen categories from apartments and private houses to land, warehouses, offices and boarding rooms.

**Use something else when:** the property is outside Vietnam. Use [99.co Property Scraper](https://apify.com/sian.agency/99co-property-scraper?fpr=sian) for Singapore, with agent profiles and market KPIs. Use [SUUMO Scraper](https://apify.com/sian.agency/suumo-property-scraper?fpr=sian) for Japan, for sale and to rent. Use [Dabang Scraper](https://apify.com/sian.agency/dabang-property-scraper?fpr=sian) for South Korea, including jeonse and wolse rentals. Batdongsan is owned by PropertyGuru Group, but it does not run on the group's platform: propertyguru.com.sg, propertyguru.com.my and ddproperty.com share one deployment and Batdongsan is a separate stack with its own URL scheme, so nothing here reads those sites. This actor returns what a Batdongsan results page shows. Per-listing GPS coordinates, the full advert text, the whole photo set and the specification table live only on each listing's own page and are not returned. For a district, a street, a project or a bedroom count, build the search on Batdongsan and paste the address into `searchUrls`.

### 🤖 Use with AI agents

Already connected to the [Apify MCP server](https://mcp.apify.com)? Just ask for this Actor by name: sian.agency/batdongsan-property-scraper

**Your agent can pay for its own runs.** This Actor is eligible for [agentic payments](https://docs.apify.com/platform/actors/publishing/monetize), so an agent can discover it, run it and settle the bill over [x402](https://www.x402.org/) (USDC on Base) or [Skyfire](https://www.skyfire.xyz/) — without an Apify account or API token of its own. Billing is the same either way: per successful row, never for errors.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
I want to research the Vietnamese property market using the Apify Actor `sian.agency/batdongsan-property-scraper`.

Use it when I need: asking prices in dong and in dollars, floor area in square metres, price per square metre, bedrooms, bathrooms, district and ward. Every row also carries the advert summary, its photos, the account that posted it with its Batdongsan id and public profile, the verified badge, the advert's promotion tier and the exact date it went up. Property for sale or for rent, in any Vietnamese province, across fifteen categories from apartments and private houses to land, warehouses, offices and boarding rooms.

Don't use it when: the property is outside Vietnam — use 99co-property-scraper or suumo-property-scraper or dabang-property-scraper instead.

How to call it: set `listingType` to `ban` for sale or `cho-thue` for rent, pick a `propertyType` (`all`, `apartment`, `mini-apartment`, `house`, `street-house`, `villa`, `shophouse`, `land`, `project-land`, `warehouse`, `condotel`, `farm-resort`, `office`, `room` or `other`), and give `provinces` a list of Batdongsan's own slugs such as `tp-hcm`, `ha-noi`, `da-nang` or `binh-duong`. Narrow further with `priceBand` or `areaBand`, which are the bands Batdongsan itself publishes, and cap the run with `maxResults`. To reproduce a search exactly, paste its address into `searchUrls` and every other field is ignored.

Start with this input:
{
  "operation": "search",
  "listingType": "ban",
  "propertyType": "apartment",
  "provinces": [
    "tp-hcm"
  ],
  "priceBand": "gia-tu-2-ty-den-3-ty",
  "maxResults": 100
}

Ask me which province or city, whether you want listings for sale or for rent, and roughly what price range, then run the Actor and summarise the results as a table.
```

**Things you can ask your agent for:**

- *Pull apartments for sale in Ho Chi Minh City between 2 and 3 billion dong and rank the districts by median price per square metre.*
- *Run the same Hanoi district for sale and for rent, then work out the gross rental yield.*
- *List the agents carrying the most stock in Da Nang, with their Batdongsan profile links.*

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at [apify.com/sian.agency/batdongsan-property-scraper.md](https://apify.com/sian.agency/batdongsan-property-scraper.md).

### 📋 Overview

**Batdongsan.com.vn is where Vietnam looks for property**, and this Actor reads its own search pages, so you see the same inventory a buyer in Ho Chi Minh City sees. Ho Chi Minh City alone advertised 45,692 live for-sale listings when this was last measured.

**What you get:**

- ✅ **Prices as integers, not strings**: "4,99 tỷ" comes back as 4990000000 VND, "15 triệu/tháng" as 15000000 a month. The original text stays on the row so you can always check the parse.
- ⚡ **Dollars alongside dong**: one exchange-rate read per run, and the rate is stamped on every row so a figure can be audited months later.
- 🎯 **Agents on the search page**: name, Batdongsan ID, public profile link and whether the site has certified them as a professional. No extra request, no extra charge.
- 💰 **Pay per listing returned**: a search that matches nothing costs nothing, and neither does a page that failed to arrive.
- 💎 **Vietnamese text kept intact**: Hồ Chí Minh, Bình Thạnh, Trần Hải. Diacritics survive into the dataset, the CSV and the run report.
- ✨ **It tells you when a filter did not apply**: a province Batdongsan does not publish stops the run with the reason, instead of quietly returning the whole country and billing you for it.

### ✨ Features

- 🏠 **Both halves of the market**: for sale (nhà đất bán) and for rent (nhà đất cho thuê).
- 🏢 **Fifteen categories**: apartments, mini apartments, private houses, street-front houses, villas, shophouses, land, project land plots, warehouses, condotels, farms and resorts, offices, boarding rooms, and everything else.
- 🗺️ **Every province**: eleven featured markets in the dropdown, and any other slug Batdongsan publishes works too.
- 🎛️ **The site's own filters**: fourteen price bands and ten area bands, copied from the bands Batdongsan itself publishes, so the count you see on the site is the count you get.
- 🔗 **Paste a URL instead**: build any search on Batdongsan (district, street, project, bedrooms), copy the address bar, and it is followed exactly as written.
- 📐 **Price per square metre**: parsed from the site where it publishes one, on every sale row.
- ✅ **The verified badge and the promotion tier**: see which adverts Batdongsan has checked, and who is paying for visibility.
- 📅 **The exact posted date**, as a date, where the site shows only "2 days ago".
- 📷 **Photos and photo counts** on every row.
- 📄 **An HTML run report** with the money you spent, itemised.

### 🎬 Quick Start

Pick for sale or for rent, choose a category, list one or more provinces, press Start. Rows land in the dataset as they are found, and you can download them as JSON, CSV or Excel the moment the run ends.

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~batdongsan-property-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"operation":"search","listingType":"ban","provinces":["tp-hcm"],"maxResults":100}'
```

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Choose the market half

For sale or for rent. Rent comes back as a monthly figure with the period named on the row.

#### Step 2: Choose what and where

A property category and one or more province slugs: `tp-hcm`, `ha-noi`, `da-nang`. Add a price band or an area band if you want the site to narrow it for you.

#### Step 3: Press Start

Set a row limit and run it. There is nothing else to configure.

**That's it! In a couple of minutes, you'll have:**

- Every matching listing with prices already converted to numbers
- The agent behind each advert, with a profile link
- A downloadable file in JSON, CSV or Excel

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `operation` | string | No | Only `search` today. |
| `listingType` | string | No | `ban` (for sale) or `cho-thue` (for rent). Default `ban`. |
| `propertyType` | string | No | Category key, e.g. `apartment`, `house`, `land`, `office`. Default `all`. |
| `provinces` | array | No | Batdongsan province slugs. Default `["tp-hcm"]`. Empty sweeps all of Vietnam. |
| `maxResults` | integer | No | Row budget across every province. Default 100. |
| `priceBand` | string | No | One of Batdongsan's own price bands. |
| `areaBand` | string | No | One of Batdongsan's own area bands. Used when no price band is set. |
| `searchUrls` | array | No | Batdongsan search URLs, followed exactly as written. Overrides everything above. |

**Example:**

```json
{
  "operation": "search",
  "listingType": "ban",
  "propertyType": "apartment",
  "provinces": ["tp-hcm", "ha-noi"],
  "priceBand": "gia-tu-2-ty-den-3-ty",
  "maxResults": 200
}
```

**Paste a search instead:**

```json
{
  "operation": "search",
  "searchUrls": [
    "https://batdongsan.com.vn/ban-can-ho-chung-cu-tp-hcm/gia-tu-3-ty-den-5-ty",
    "https://batdongsan.com.vn/cho-thue-nha-rieng-ha-noi"
  ],
  "maxResults": 500
}
```

### 📤 Output

Results are saved to the Apify dataset with **37 fields**, including:

| Field | Type | Description |
|-------|------|-------------|
| `listingId` | string | Batdongsan's own advert ID |
| `url` | string | Link to the advert |
| `propertyTitle` | string | Advert headline, Vietnamese diacritics intact |
| `priceText` | string | Price exactly as shown, e.g. `4,99 tỷ` |
| `priceVnd` | integer | The same price as a number |
| `priceUsd` | number | Converted at this run's rate |
| `areaSqm` | number | Floor area in square metres |
| `pricePerSqmVnd` | integer | Price per square metre, where the site publishes it |
| `bedrooms` / `bathrooms` | integer | Room counts |
| `locationText` | string | District and ward |
| `agentName` / `agentId` / `agentProfileUrl` | string | Who posted it |
| `isVerified` | boolean | Batdongsan checked the title deed and photos |
| `listingTier` | string | Promotion level of the advert |
| `postedAt` | string | Exact date the advert went up |
| `imageUrls` | array | Photos from the results tile |

**Example:**

```json
{
  "listingId": "44993538",
  "url": "https://batdongsan.com.vn/ban-nha-rieng-duong-xo-viet-nghe-tinh-phuong-25-66/chinh-chu-ban-378-18-xvnt-5-68-ty-moi-full-noi-that-pr44993538",
  "propertyTitle": "Ngộp bank trước rao 5,9 tỷ giờ còn 4,99 tỷ",
  "priceText": "4,99 tỷ",
  "priceVnd": 4990000000,
  "priceUsd": 189734,
  "isNegotiable": false,
  "areaText": "27,5 m²",
  "areaSqm": 27.5,
  "pricePerSqmText": "181,46 tr/m²",
  "pricePerSqmVnd": 181460000,
  "bedrooms": 4,
  "bathrooms": 3,
  "locationText": "Q. Bình Thạnh (P. Thạnh Mỹ Tây mới)",
  "province": "tp-hcm",
  "listingType": "sale",
  "propertyType": "all",
  "isVerified": true,
  "listingTier": "vip-diamond",
  "agentName": "Nghị Ông Địa",
  "postedAt": "2026-09-06",
  "fxRateVndPerUsd": 26300
}
```

### 💼 Use Cases & Examples

#### 1. Vietnam Asking-Price Tracking

**A market analyst needs price movement by district, weekly, without reading adverts by hand.**

**Input:** A province, a category, optionally a price band.
**Output:** Asking price in VND and USD, area, price per square metre, district, on every row.
**Use:** Run the same search on a schedule and the movement is a subtraction, not a parsing project.

#### 2. Estate Agent & Agency Lead Lists

**An agency wants to know who is carrying stock in a district before they call anyone.**

**Input:** A district-level Batdongsan URL, or a province and a category.
**Output:** The posting account on every advert, with its ID, its public profile and whether Batdongsan has certified it.
**Use:** Sort by advert count to find the agents worth a conversation.

#### 3. Rental Yield and Comparables

**A proptech team needs both halves of a yield calculation on the same fields.**

**Input:** The same district, run twice: once with `listingType: "ban"`, once with `"cho-thue"`.
**Output:** Monthly rent, asking price, area and price per square metre, with the rent period named so nothing is mistaken for a sale price.
**Use:** Gross yield per district, computed from one export.

#### 4. New-Supply Monitoring

**A developer wants today's new stock in a province, every morning.**

**Input:** A province and a daily schedule.
**Output:** Every advert with the exact date it was posted, plus the verified badge.
**Use:** Filter to today's date and you have the day's supply, with no diffing.

#### 5. Feeding a Portal, CRM or Model

**An engineer needs Vietnamese listings in a database without a cleaning step.**

**Input:** Anything above, called over the API.
**Output:** JSON, CSV or Excel with diacritics intact and numeric fields already numeric.
**Use:** Load straight into a warehouse, a pricing model or a client-facing portal.

#### 6. Competitive and Market-Share Research

**A marketer wants to see where advertising money is going in a city.**

**Input:** A city and a category, run across price bands.
**Output:** The promotion tier of every advert, diamond down to plain, alongside the agency.
**Use:** A picture of who is buying visibility, by district and by price bracket.

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/batdongsan-property-scraper').call({
  operation: 'search',
  listingType: 'ban',
  propertyType: 'apartment',
  provinces: ['tp-hcm'],
  maxResults: 100,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/batdongsan-property-scraper').call(
    run_input={
        'operation': 'search',
        'listingType': 'cho-thue',
        'provinces': ['ha-noi'],
        'maxResults': 100,
    }
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item['propertyTitle'], item['priceVnd'])
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~batdongsan-property-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"operation":"search","listingType":"ban","provinces":["tp-hcm"],"maxResults":100}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: Schedule or webhook
2. **HTTP Request**: Call the Actor API
3. **Process**: Handle the JSON rows
4. **Action**: Save to a sheet, alert on a price drop, or push into a CRM

### 📊 Performance & Pricing

#### FREE Tier (Try It Now)

- **25 listings** per run, every field, same quality
- No credit card required
- Enough to check the output shape before you commit

#### PAID Tier (Production Ready)

- **Unlimited** listings per run
- Pay per listing returned: a search that matches nothing is not billed
- A small fee when the run starts, and nothing else

💰 **In line with the market**: $1.50 per 1,000 listings at the entry tier, falling with your Apify plan.

🔗 [View current pricing](https://apify.com/sian.agency/batdongsan-property-scraper?fpr=sian)

### ❓ Frequently Asked Questions

**Q: How many listings can I get?**
A: FREE tier: 25 per run. PAID tier: unlimited. Ho Chi Minh City alone advertised 45,692 for-sale listings when this was last measured, and every province carries its own index.

**Q: Do I need an API key, a login or a proxy?**
A: No. Pick a province and press Start. Everything the site needs is handled inside the Actor and is already in the per-result fee.

**Q: Why are there no GPS coordinates or full advert text?**
A: Those live only on each listing's own page, and opening one costs about what a whole 20-row results page costs. Charging honestly for that would put it far above what this market pays, so it was left out rather than shipped at a price nobody should accept.

**Q: Are the Vietnamese characters preserved?**
A: Yes. Titles, districts, wards and agent names come back exactly as Batdongsan publishes them, and the dataset, the CSV export and the run report all keep the diacritics.

**Q: How is "4,99 tỷ" turned into a number?**
A: Vietnamese uses a comma as the decimal mark and names the scale in words. tỷ is a billion, triệu (or tr) a million, nghìn a thousand. So "4,99 tỷ" becomes 4990000000 and "5 triệu/tháng" becomes 5000000 a month. The original string stays on the row.

**Q: What happens on a listing with a negotiable price?**
A: Batdongsan shows "Giá thỏa thuận" instead of a figure. The row keeps that string, leaves the numeric price empty rather than guessing, and sets a negotiable flag so you can filter those rows out in one step.

**Q: Can I search a district or a specific street?**
A: Yes, through `searchUrls`. Build the search on Batdongsan, copy the address bar, and it is followed exactly as written, district, ward, street, project and bedroom filters included.

**Q: What output formats are available?**
A: JSON, CSV and Excel, exported straight from the Apify dataset, plus the API.

### 🐛 Troubleshooting

**A row says Batdongsan does not publish a page for my location**

- The province slug is not one Batdongsan uses. Open a Batdongsan search in a browser and copy the part of the URL after the category: `tp-hcm`, `ha-noi`, `ba-ria-vung-tau`.
- The run stops there on purpose. An unknown slug returns the whole country, and finishing that search would bill you for rows you did not ask for.

**The run stopped and says a category is not available**

- Some categories exist on only one side of the market. Offices and boarding rooms are rent only; land, project land plots, shophouses, condotels and farm or resort land are sale only. The message lists what is available for the side you chose.

**Fewer rows than I expected**

- Check whether a price band and an area band were both set. The site applies one at a time, so the price band wins and the run log says so.
- On the FREE tier the run stops at 25 rows.

**A page did not arrive**

- Batdongsan guards its pages and occasionally turns a request away. Those pages are not charged. Re-run the same search; it usually goes through the second time.

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

Batdongsan.com.vn is a trademark of PropertyGuru Group. This Actor is not affiliated with, endorsed by, or sponsored by Batdongsan.com.vn or PropertyGuru Group.

### 🤝 Support

[![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi)

**Join our active support community**

- For issues or questions, open an issue in the Actor's Issues tab
- Check [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Actor input Schema

## `operation` (type: `string`):

Property Search sweeps Batdongsan's own results pages and returns about 20 listings per request. Choose for sale or for rent, a property category, one or more provinces, and optionally the site's own price and area bands. You can also paste Batdongsan search URLs directly and they are followed exactly as given.

## `listingType` (type: `string`):

Which half of the Batdongsan market to read. Rent prices are per month and are returned as a monthly figure with the period named on the row, so sale and rent rows can never be confused after export. The two halves carry different property categories - offices and boarding rooms exist only for rent, land and condotels only for sale - and an unavailable combination is rejected before anything is charged.

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

Which Batdongsan category to read. Several categories exist on only one side of the market, which the titles say: shophouses, land, project land plots, condotels and farm/resort land are sale-only, while offices and boarding rooms are rent-only. Pick one that does not exist for the chosen listing type and the run stops with the list of categories that do, before anything is charged - it never quietly falls back to all categories and bills you for the wrong rows.

## `provinces` (type: `array`):

Batdongsan's own province slugs, one search per entry. The eleven the site itself features are tp-hcm, ha-noi, da-nang, hai-phong, binh-duong, dong-nai, ba-ria-vung-tau, long-an, khanh-hoa, quang-ninh, hung-yen and quang-nam. Any other slug the site publishes works too - it is put into the URL exactly as typed. Leave the list empty to sweep the whole country. Three provinces return roughly three times the rows, and a slug the site does not publish is reported on its own row as a location that…

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

Stop after this many listings across every province in the list. A results page carries 20 listings, so the run finishes the page that crosses your limit and then stops. Free-plan runs are capped lower; the run log and the report both say so when the cap bites.

## `priceBand` (type: `string`):

Batdongsan's own price bands, taken from the bands the site publishes on its results pages rather than invented, so the filter is applied by the site itself and the count you see is the count you get. These are sale prices; on the rent side the same bands read as monthly rent. Price and area bands cannot both be applied in one search - if you set both, the price band wins and the run log says so.

## `areaBand` (type: `string`):

Batdongsan's own floor-area bands, again copied from the bands the site publishes. Used only when no price band is set, because the site's URL scheme accepts one band at a time.

## `searchUrls` (type: `array`):

Paste Batdongsan search URLs and they are fetched exactly as written, filters and all - build the search you want on the site, copy the address bar, and every option above is ignored. Useful for the district, street, project and bedroom filters that have no field here. Pagination is still followed, so one URL can return thousands of rows.

## Actor input object example

```json
{
  "operation": "search",
  "listingType": "ban",
  "propertyType": "all",
  "provinces": [
    "tp-hcm",
    "ha-noi"
  ],
  "maxResults": 100,
  "priceBand": "",
  "areaBand": "",
  "searchUrls": []
}
```

# Actor output Schema

## `batdongsanComVnListings` (type: `string`):

Every listing this run returned.

## `scrapingSummary` (type: `string`):

HTML summary showing successful and failed results with key metrics

# 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 = {
    "operation": "search",
    "listingType": "ban",
    "propertyType": "all",
    "provinces": [
        "tp-hcm",
        "ha-noi"
    ],
    "maxResults": 100,
    "priceBand": "",
    "areaBand": "",
    "searchUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/batdongsan-property-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 = {
    "operation": "search",
    "listingType": "ban",
    "propertyType": "all",
    "provinces": [
        "tp-hcm",
        "ha-noi",
    ],
    "maxResults": 100,
    "priceBand": "",
    "areaBand": "",
    "searchUrls": [],
}

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/batdongsan-property-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 '{
  "operation": "search",
  "listingType": "ban",
  "propertyType": "all",
  "provinces": [
    "tp-hcm",
    "ha-noi"
  ],
  "maxResults": 100,
  "priceBand": "",
  "areaBand": "",
  "searchUrls": []
}' |
apify call sian.agency/batdongsan-property-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sian.agency/batdongsan-property-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/w8sGAp15zI11aIGot/builds/Zgh1k3D7K77gl2vkl/openapi.json