Batdongsan Search API lists Vietnamese properties for sale and for rent. Pick a province with city, then narrow by category, price in dong, area, bedrooms, bathrooms, legal status, interior, floors, road and frontage width, direction, a location from the autocomplete route, verified or professional agents and sort order. Every item has the price in dong and as the site shows it, the price per square meter, area, rooms, the address in the old and the new ward system, the project and street ids, photos, the description and the publisher with a profile id for the agent route.
Good to know:
- Vietnam only. Prices are in Vietnamese dong. Rent prices are per month.
- Every filter is checked before the lookup. An unknown province, category or id returns 422 and is not billed.
- Items that break a requested filter are dropped and counted in
meta.filtered_out, so a page can hold fewer items thanper_page. bedroomsandbathroomsarenullwhen the seller did not state them. Zero and empty values are never shown as real values.- Phone numbers stay masked. A search past the last page returns an empty list and the real totals.
- Province codes: all 63 provinces, for example HN, SG, DDN, HP, CT, BD, DNA, KH, QNI, LDD, TTH, VT.
- Failed requests are not billed.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
22 optional filters available.
string
Required
Province code. Examples: HN (Hà Nội), SG (Hồ Chí Minh), DDN (Đà Nẵng), HP (Hải Phòng), CT (Cần Thơ), BD (Bình Dương), DNA (Đồng Nai), KH (Khánh Hòa). All 63 provinces work; the full list is under the table.
example
string
Optional
sale (default) or rent.
example
string
Optional
Category ids, comma separated. Sale: 40 project land, 41 house, 163 street-front house, 283 land, 324 apartment, 325 villa and townhouse, 575 shophouse. Rent: 50 office, 51 street-front house, 52 house, 53 warehouse and land, 55 shop and kiosk, 57 room and boarding house, 326 apartment, 576 shophouse, 577 villa and townhouse, 651 mini apartment and serviced apartment. An id of the other listing type is refused.
example
number
Optional
Minimum price in Vietnamese dong (rent: per month). Example: 2000000000 for 2 billion.
10
number
Optional
Maximum price in Vietnamese dong.
10
number
Optional
Minimum area in square meters.
10
number
Optional
Maximum area in square meters.
10
string
Optional
Exact bedroom counts, comma separated. Example: 2 or 2,3.
example
string
Optional
Exact bathroom counts, comma separated.
example
string
Optional
Ids, comma separated: 1 red book or pink book, 2 sale contract, 3 waiting for the book, 4 other.
example
string
Optional
Ids, comma separated: 1 full, 2 basic, 3 none, 4 other.
example
string
Optional
Floor counts, comma separated: 1 to 4 match exactly, 5 matches five floors and above.
example
integer
Optional
One id: 1 under 5 m, 2 5-6 m, 3 6-7 m, 4 7-10 m, 5 10-15 m, 6 over 15 m.
10
integer
Optional
One id: 1 under 5 m, 2 5-6 m, 3 6-8 m, 4 8-10 m, 5 10-12 m, 6 over 12 m.
10
string
Optional
House direction ids, comma separated: 1 East, 2 West, 3 South, 4 North, 5 North-East, 6 North-West, 7 South-West, 8 South-East.
example
string
Optional
Balcony direction ids, same values as direction.
example
string
Optional
Id from the autocomplete route. Use together with location_type.
1234567890
string
Optional
street, district, project or ward. Use together with location_id. The route returns both ready to use.
example
boolean
Optional
true for verified listings only.
true
boolean
Optional
true for listings of professional agents only.
true
string
Optional
default, verified, price_asc, price_desc, price_per_m2_asc, price_per_m2_desc, area_asc or area_desc.
relevance
integer
Optional
One-based page number (default 1).
1
integer
Optional
Results per page, 1 to 100 (default 20).
10
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"items": [
{
"id": 46364654,
"url": "https://batdongsan.com.vn/ban-nha-biet-thu-lien-ke-pho-giang-vo-vinhomes-the-gallery/chiet-khau-len-en-40-mo-ban-quy-can-ep-va-re-nhat-he...",
"vip": {
"id": 0,
"name": "VIP Kim C\u01b0\u01a1ng"
},
"area": 120,
"price": {
"display": "40 t\u1ef7",
"unit_id": 2,
"value_vnd": 40000000000,
"unit_display": "333,33 tr/m\u00b2"
},
"title": "CHI\u1ebeT KH\u1ea4U L\u00caN \u0110\u1ebeN 37%, M\u1ede B\u00c1N QU\u1ef8 C\u0102N \u0110\u1eb8P V\u00c0 R\u1eba NH\u1ea4T, G\u1eccI \u0110\u1ec2 \u0110C T\u01af V\u1ea4N V\u00c0 XEM D\u1ef0 \u00c1N \u1ea0",
"author": {
"id": 4752932,
"name": "Th\u1ebf H\u00f9ng",
"agent_id": "200810374fc3900f",
"avatar_url": "https://file4.batdongsan.com.vn/resize/200x200/2025/10/23/20251023103146-f33a.jpg",
"profile_url": "https://guru.batdongsan.com.vn/pa/200810374fc3900f",
"is_pro_agent": true,
"phone_masked": "0942906***"
},
"images": [
{
"url": "https://file4.batdongsan.com.vn/2026/09/30/20260930171640-5483_wm.jpg",
"caption": null,
"crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/09/30/20260930171640-5483_wm.jpg",
"thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/09/30/20260930171640-5483_wm.jpg"
},
{
"url": "https://file4.batdongsan.com.vn/2026/10/01/20261001165807-1bd2_wm.jpg",
"caption": null,
"crop_url": "https://file4.batdongsan.com.vn/resize/162x120/2026/10/01/20261001165807-1bd2_wm.jpg",
"thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/10/01/20261001165807-1bd2_wm.jpg"
}
],
"address": {
"full": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303, Qu\u1eadn Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
"short": "Q. Ba \u0110\u00ecnh (P. Gi\u1ea3ng V\u00f5 m\u1edbi)",
"city_level": "Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
"district_level": "Gia\u0309ng Vo\u0303, Ba \u0110\u00ecnh"
},
"bedrooms": null,
"category": {
"id": 325,
"name": "B\u00e1n nh\u00e0 bi\u1ec7t th\u1ef1, li\u1ec1n k\u1ec1"
},
"location": {
"address": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5, H\u00e0 N\u1ed9i",
"ward_id": 14347,
"city_code": "HN",
"city_name": "H\u00e0 N\u1ed9i",
"street_id": 438,
"ward_name": "Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5",
"project_id": 6318,
"street_name": "Ph\u1ed1 Gi\u1ea3ng V\u00f5",
"project_name": "Vinhomes The Gallery"
},
"verified": {
"date": null,
"is_verified": false
},
"bathrooms": null,
"video_url": null,
"is_expired": false,
"description": "Qu\u00fd kh\u00e1ch h\u00e0ng li\u00ean h\u1ec7 \u0111\u1ec3 \u0111\u01b0\u1ee3c t\u01b0 v\u1ea5n ch\u1ecdn c\u0103n \u0111\u1eb9p theo nhu c\u1ea7u v\u00e0 xem th\u1ef1c t\u1ebf d\u1ef1 \u00e1n.\nGi\u00e1m \u0110\u1ed1c Ph\u1ee5 tr\u00e1ch b\u00e1n h\u00e0ng d\u1ef1 \u00e1n.\nLi\u00ean h\u1ec7: \n\nTH\u00d4NG...",
"media_count": 13,
"last_up_time": "2026-10-25T11:59:03.582+00:00",
"listing_type": "sale",
"old_location": {
"address": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303, Qu\u1eadn Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
"ward_id": 62,
"city_code": "HN",
"city_name": "H\u00e0 N\u1ed9i",
"street_id": 438,
"ward_name": "Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303",
"project_id": 6318,
"district_id": 2,
"street_name": "Ph\u1ed1 Gi\u1ea3ng V\u00f5",
"project_name": "Vinhomes The Gallery",
"district_name": "Qu\u1eadn Ba \u0110\u00ecnh"
},
"posted_label": "H\u00f4m qua"
},
{
"id": 45675713,
"url": "https://batdongsan.com.vn/ban-nha-biet-thu-lien-ke-pho-giang-vo-vinhomes-the-gallery/mo-ban-quy-chiet-khau-khung-cac-can-goc-mat-chung-cu...",
"vip": {
"id": 0,
"name": "VIP Kim C\u01b0\u01a1ng"
},
"area": 82.5,
"price": {
"display": "55 t\u1ef7",
"unit_id": 2,
"value_vnd": 55000000000,
"unit_display": "666,67 tr/m\u00b2"
},
"title": "QU\u1ef8 C\u0102N \u0110\u1ec2 \u1ede, KINH DOANH GI\u1ea2NG V\u00d5 82,5M2 - 145M2 LI\u1ec0N K\u1ec0 TINH HOA, GI\u00c1 T\u1eea 55 T\u1ef6 - 100 T\u1ef6(PH\u1ed0 \u0110I B\u1ed8)",
"author": {
"id": 3656622,
"name": "H\u00e0 Th\u1ebf Anh",
"agent_id": "bc53ed083d1e8017",
"avatar_url": "https://file4.batdongsan.com.vn/resize/200x200/2024/10/26/20241026120651-22fb.jpg",
"profile_url": "https://guru.batdongsan.com.vn/pa/bc53ed083d1e8017",
"is_pro_agent": true,
"phone_masked": "0912347***"
},
"images": [
{
"url": "https://file4.batdongsan.com.vn/2026/05/06/20260506093218-41d2_wm.jpg",
"caption": null,
"crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/05/06/20260506093218-41d2_wm.jpg",
"thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/05/06/20260506093218-41d2_wm.jpg"
},
{
"url": "https://file4.batdongsan.com.vn/2026/05/06/20260506093218-6cbd_wm.jpg",
"caption": null,
"crop_url": "https://file4.batdongsan.com.vn/resize/162x120/2026/05/06/20260506093218-6cbd_wm.jpg",
"thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/05/06/20260506093218-6cbd_wm.jpg"
}
],
"address": {
"full": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303, Qu\u1eadn Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
"short": "Q. Ba \u0110\u00ecnh (P. Gi\u1ea3ng V\u00f5 m\u1edbi)",
"city_level": "Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
"district_level": "Gia\u0309ng Vo\u0303, Ba \u0110\u00ecnh"
},
"bedrooms": null,
"category": {
"id": 325,
"name": "B\u00e1n nh\u00e0 bi\u1ec7t th\u1ef1, li\u1ec1n k\u1ec1"
},
"location": {
"address": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5, H\u00e0 N\u1ed9i",
"ward_id": 14347,
"city_code": "HN",
"city_name": "H\u00e0 N\u1ed9i",
"street_id": 438,
"ward_name": "Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5",
"project_id": 6318,
"street_name": "Ph\u1ed1 Gi\u1ea3ng V\u00f5",
"project_name": "Vinhomes The Gallery"
},
"verified": {
"date": null,
"is_verified": false
},
"bathrooms": null,
"video_url": null,
"is_expired": false,
"description": "K\u00ednh ch\u00e0o qu\u00fd anh ch\u1ecb nh\u00e0 \u0111\u1ea7u t\u01b0 Vinhomes The Gallery 148 Gi\u1ea3ng V\u00f5.\nEm Th\u1ebf Anh v\u1edbi 10 n\u0103m kinh nghi\u1ec7m ch\u1ecdn c\u00e1c s\u1ea3n ph\u1ea9m \u0111\u1ea7u t\u01b0 c\u1ee7a Vinhom...",
"media_count": 13,
"last_up_time": "2026-10-25T11:53:14.145+00:00",
"listing_type": "sale",
"old_location": {
"address": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303, Qu\u1eadn Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
"ward_id": 62,
"city_code": "HN",
"city_name": "H\u00e0 N\u1ed9i",
"street_id": 438,
"ward_name": "Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303",
"project_id": 6318,
"district_id": 2,
"street_name": "Ph\u1ed1 Gi\u1ea3ng V\u00f5",
"project_name": "Vinhomes The Gallery",
"district_name": "Qu\u1eadn Ba \u0110\u00ecnh"
},
"posted_label": "H\u00f4m qua"
}
],
"pagination": {
"page": 1,
"total": 44794,
"per_page": 3,
"returned": 2,
"total_pages": 14932,
"has_next_page": true
},
"applied_filters": {
"city": "HN",
"bedrooms": "2",
"listing_type": "sale"
}
},
"meta": {
"billable": true,
"filtered_out": 0,
"endpoint_family": "search"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A value is missing, unknown or out of range. Examples: an unknown province code, a category that does not exist for the listing type, or a reversed range. This response is not billed.
{
"errors": {
"city": [
"The selected city is invalid."
]
},
"message": "The request validation failed"
}Upstream Unavailable
Batdongsan could not be reached or returned data that does not match the request. Retry shortly. This response is not billed.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "Batdongsan could not be reached. Please retry shortly."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.