# Batdongsan Listing API Documentation
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.
- **Documentation:** [https://scrappa.co/docs/batdongsan-api/batdongsan_listing](https://scrappa.co/docs/batdongsan-api/batdongsan_listing)
- **API group:** Batdongsan API
- **Endpoint:** `GET https://scrappa.co/api/batdongsan/listing`
## Authentication
Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.
## Parameters
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Numeric listing id from search or similar. |
## Example response
```json
{
"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
| Status | Error | Description |
| --- | --- | --- |
| 422 | 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. |
| 404 | Not Found | The listing does not exist or has expired. This response is not billed. |
| 503 | Upstream Unavailable | Batdongsan could not be reached or returned data that does not match the request. Retry shortly. This response is not billed. |
## More Scrappa resources
- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)