Batdongsan Listing API returns one listing by its numeric id. On top of the search fields it adds the exact coordinates, the full address in both ward systems, floors, house and balcony direction, frontage and road width, legal status, interior, utilities, rental terms, tags, all photos and videos, the start, end and last update dates and the track record of the publisher.
Good to know:
- Take the id from the search or similar route. Expired or unknown ids return 404 and are not billed.
- Values the seller did not state are
null. - Phone and email stay masked as the site shows them.
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 or similar.
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": {
"id": 46364654,
"url": "https://batdongsan.com.vn/ban-nha-biet-thu-lien-ke-pho-giang-vo-phuong-giang-vo-prj-vinhomes-the-gallery/chiet-khau-len-en-40-mo-ban-quy-...",
"vip": {
"id": 0,
"name": "VIP Kim C\u01b0\u01a1ng"
},
"area": 120,
"tags": [
{
"alias": "ban-nha-biet-thu-lien-ke-phuong-giang-vo-ba-dinh",
"title": "B\u00e1n nh\u00e0 bi\u1ec7t th\u1ef1 li\u1ec1n k\u1ec1 Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5 Ba \u0110\u00ecnh"
},
{
"alias": "ban-nha-biet-thu-lien-ke-pho-giang-vo-ba-dinh",
"title": "B\u00e1n nh\u00e0 bi\u1ec7t th\u1ef1 li\u1ec1n k\u1ec1 Ph\u1ed1 Gi\u1ea3ng V\u00f5 Ba \u0110\u00ecnh"
}
],
"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***"
},
"floors": null,
"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"
}
],
"videos": [],
"address": {
"full": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5, H\u00e0 N\u1ed9i",
"short": "Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5, H\u00e0 N\u1ed9i m\u1edbi",
"full_old": "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_old": "Qu\u1eadn Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i c\u0169",
"city_level": "Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
"district_level": "Gia\u0309ng Vo\u0303, Ba \u0110\u00ecnh"
},
"project": {
"id": 6318,
"name": "Vinhomes The Gallery"
},
"bedrooms": null,
"category": {
"id": 325,
"name": "B\u00e1n nh\u00e0 bi\u1ec7t th\u1ef1, li\u1ec1n k\u1ec1"
},
"end_date": "2026-11-05T10:47:20.968+00:00",
"interior": null,
"latitude": 21.024970177523,
"legality": "S\u1ed5 \u0111\u1ecf/ S\u1ed5 h\u1ed3ng",
"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,
"direction": null,
"longitude": 105.820316394925,
"utilities": [],
"video_url": null,
"is_expired": false,
"start_date": "2026-10-21T10:47:20.968+00:00",
"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...",
"last_update": "2026-10-25T11:59:03.582+00:00",
"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",
"publish_date": "2026-10-21T11:20:24.553+00:00",
"rental_terms": null,
"road_width_m": null,
"author_details": {
"award_label": null,
"email_masked": "Lath*********@gmail.com",
"listing_count": 21,
"is_certified_agent": true,
"working_duration_years": 1
},
"frontage_width_m": null,
"balcony_direction": null
},
"meta": {
"billable": true,
"endpoint_family": "listing"
},
"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 expired. This response is not billed.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "listing"
},
"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": "listing"
},
"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.