Batdongsan Similar Listings API returns listings that resemble one listing, in the same shape as the search items.
Good to know:
- The site returns an empty list for an unknown id and for a listing without neighbours. Both return 404 and 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.
string
Required
Numeric listing id from search.
1234567890
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": 44304828,
"url": "https://batdongsan.com.vn/ban-nha-biet-thu-lien-ke-pho-giang-vo-vinhomes-the-gallery/hot-em-co-5-lo-goc-ngoai-giao-cap-cao-chiet-khau-32-...",
"vip": {
"id": 5,
"name": "Th\u01b0\u1eddng"
},
"area": 124,
"price": {
"display": "96 t\u1ef7",
"unit_id": 2,
"value_vnd": 96000000000,
"unit_display": "774,19 tr/m\u00b2"
},
"title": "HOT - Em c\u00f3 l\u00f4 g\u00f3c ngo\u1ea1i giao c\u1ea5p cao chi\u1ebft kh\u1ea5u 32%, c\u0103n n\u1ed5i b\u1eadt trong d\u1ef1 \u00e1n (c\u00f3 1 - 0 - 2)",
"author": {
"id": 3682565,
"name": "Thanh Thu\u00fd",
"agent_id": null,
"avatar_url": "https://file4.batdongsan.com.vn/resize/200x200/2026/05/06/20260506122628-a434.jpg",
"profile_url": null,
"is_pro_agent": true,
"phone_masked": "0975440***"
},
"images": [
{
"url": "https://file4.batdongsan.com.vn/2025/10/17/20251017121031-189a_wm.jpg",
"caption": null,
"crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2025/10/17/20251017121031-189a_wm.jpg",
"thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2025/10/17/20251017121031-189a_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": "P. Gia\u0309ng Vo\u0303 (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": "Em Thanh Th\u00fay Vinhomes xin k\u00ednh ch\u00e0o qu\u00fd anh ch\u1ecb nh\u00e0 \u0111\u1ea7u t\u01b0 \u0111\u1ebfn v\u1edbi d\u1ef1 \u00e1n Vinhomes The Gallery Gi\u1ea3ng V\u00f5.\n\nV\u1edbi 10 n\u0103m kinh nghi\u1ec7m b\u00e1n c\u00e1c ...",
"media_count": 12,
"last_up_time": "2026-10-25T07:44:35.067+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"
}
],
"listing_id": 46364654
},
"meta": {
"billable": true,
"endpoint_family": "similar"
},
"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"
}Not Found
The listing does not exist or has no similar listings. This response is not billed.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "similar"
},
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found."
},
"success": false
}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": "similar"
},
"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.