Com APIbatdongsan.com.vn ↗
Access Vietnam real estate listings, project data, and news from batdongsan.com.vn via 5 structured API endpoints covering sale, rent, and property details.
What is the Com API?
The batdongsan.com.vn API exposes 5 endpoints covering Vietnam's largest real estate portal, returning structured data on property listings for sale and rent, full listing details, development projects, and market news. The get_listing_detail endpoint delivers per-property specs, masked agent contact info, image URLs, and location breadcrumbs down to ward level — data that typically requires navigating individual listing pages manually.
curl -X GET 'https://api.parse.bot/scraper/17f5b902-ea62-41aa-bc40-7b6e52965d8b/search_listings_for_sale?page=1&keyword=Vinhomes&location=ha-noi' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace batdongsan-com-vn-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Batdongsan.com.vn real estate API — search, drill-down, browse."""
from parse_apis.batdongsan_com_vn_api import Batdongsan, ListingNotFound
client = Batdongsan()
# Search for sale listings in Hanoi, capped at 5 results.
for listing in client.listingsummaries.search_for_sale(location="ha-noi", limit=5):
print(listing.title, listing.price, listing.area)
# Drill into the first rental listing for full details.
rental = client.listingsummaries.search_for_rent(location="tp-hcm", limit=1).first()
if rental:
detail = rental.details()
print(detail.title, detail.price, detail.area)
print(detail.agent.name, detail.agent.phone_masked)
for key, val in detail.specs.items():
print(f" {key}: {val}")
# Browse development projects.
for project in client.projects.list(limit=3):
print(project.title, project.address)
# Get latest news articles.
for article in client.articles.list(limit=3):
print(article.title, article.summary)
# Typed error handling: catch a listing-not-found.
try:
bad = client.listingsummaries.search_for_sale(keyword="nonexistent_xyzzy_99", limit=1).first()
if bad:
bad.details()
except ListingNotFound as exc:
print(f"Listing gone: {exc.url}")
print("exercised: search_for_sale / search_for_rent / details / projects.list / articles.list")
Search for real estate listings for sale on batdongsan.com.vn. Returns paginated results with listing summaries including price, area, and location. Results are ordered by recency. Each page returns up to 30 listings.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| keyword | string | Search keyword to filter listings (e.g. 'Vinhomes'). Omitting returns all listings. |
| location | string | Location slug for filtering by city/province (e.g. 'ha-noi', 'tp-hcm', 'da-nang'). Omitting returns listings nationwide. |
{
"type": "object",
"fields": {
"url": "string, the URL that was fetched",
"page": "integer, current page number",
"listings": "array of listing objects with id, title, url, price, area, price_per_m2, location, published_at",
"total_count_on_page": "integer, number of listings returned on this page"
},
"sample": {
"data": {
"url": "https://batdongsan.com.vn/nha-dat-ban-ha-noi",
"page": 1,
"listings": [
{
"id": "45893496",
"url": "https://batdongsan.com.vn/ban-can-ho-chung-cu-duong-nguyen-trai-phuong-thuong-dinh-hanoi-seasons-garden/ban-goc-truc-08-va-15a-3pn-view-ep-nhat-du-an-dt-97-135m-gia-chi-tu-15-ty-lh-pr45893496",
"area": "115 m²",
"price": "Giá thỏa thuận",
"title": "Bán căn góc trục 08 và 15A căn 3PN view đẹp nhất dự án",
"location": "·Q. Thanh Xuân",
"price_per_m2": null,
"published_at": "Đăng hôm nay"
}
],
"total_count_on_page": 30
},
"status": "success"
}
}About the Com API
Listing Search and Filtering
The search_listings_for_sale and search_listings_for_rent endpoints accept three optional parameters: page for pagination, keyword for text-based filtering (e.g. 'Vinhomes'), and location for province or city slugs such as 'tp-hcm' or 'ha-noi'. Each page response includes an array of listing objects with id, title, url, price, area, price_per_m2, location, and published_at, plus a total_count_on_page integer. Omitting both keyword and location returns nationwide results across all property types.
Property Detail Data
get_listing_detail takes a full listing URL — typically sourced from search results — and returns an expanded record. The specs field is a key-value object mapping Vietnamese-language specification labels (bedrooms, legal status, floor area, etc.) to their values, so the available keys vary by property type. The agent object includes name and phone_masked, reflecting the contact display as it appears on the listing. The location object provides breadcrumbs, city, district, and ward for precise geographic placement.
Projects and News
list_projects returns paginated development project entries with title, url, and address. This endpoint does not require any filters — pagination via page is the only available parameter. get_news returns the latest real estate news articles from the portal with title, url, and an optional summary field that may be null depending on the article format. Both endpoints are useful for monitoring market activity and new supply without querying individual listings.
The Com API is a managed, monitored endpoint for batdongsan.com.vn — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when batdongsan.com.vn changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official batdongsan.com.vn API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate nationwide property-for-sale inventory filtered by city slug for a Vietnam real estate comparison tool.
- Track rental listing price trends in Ho Chi Minh City using
price_per_m2from paginatedsearch_listings_for_rentresults. - Build a property detail enrichment pipeline that resolves listing URLs from search results through
get_listing_detailto extract bedroom counts and legal status from thespecsobject. - Monitor new development projects entering the market by polling
list_projectsfor newtitleandaddressrecords. - Power a Vietnam real estate news feed using
get_newsarticle titles and summaries. - Map property locations at ward level using the
breadcrumbsandwardfields fromget_listing_detail. - Build a lead-generation tool that surfaces masked agent contact details alongside listing specs for investor outreach.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does batdongsan.com.vn offer an official developer API?+
What does `get_listing_detail` return that the search endpoints don't?+
id, title, price, area, price_per_m2, location, and published_at. get_listing_detail adds the full description text, an images array, a specs object with property-specific attributes (bedrooms, legal status, etc.), an agent object with name and phone_masked, and a structured location object with breadcrumbs, city, district, and ward.Can I filter listings by property type, price range, or area size?+
keyword and location slug only. Price range, area size, and property type filters are not currently exposed. You can fork this API on Parse and revise it to add those filter parameters.Is project detail data available, or only the project list?+
list_projects returns title, url, and address per project. Detailed project pages — unit counts, developer info, pricing, or completion status — are not currently covered by a dedicated endpoint. You can fork this API on Parse and revise it to add a get_project_detail endpoint using the project URLs from the list.How current are the listings returned by the search endpoints?+
published_at field so you can assess recency yourself. The API reflects the live state of batdongsan.com.vn at the time of the request; it does not cache historical snapshots, so repeated calls to the same page may return different listings as the portal's inventory changes.