# Batdongsan Search API Documentation

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:

- **Documentation:** [https://scrappa.co/docs/batdongsan-api/batdongsan_search](https://scrappa.co/docs/batdongsan-api/batdongsan_search) - **API group:** Batdongsan API - **Endpoint:** `GET https://scrappa.co/api/batdongsan/search` ## 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 | | --- | --- | --- | --- | | `city` | string | Yes | 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. | | `listing_type` | string | No | sale (default) or rent. | | `category` | string | No | 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. | | `min_price` | number | No | Minimum price in Vietnamese dong (rent: per month). Example: 2000000000 for 2 billion. | | `max_price` | number | No | Maximum price in Vietnamese dong. | | `min_area` | number | No | Minimum area in square meters. | | `max_area` | number | No | Maximum area in square meters. | | `bedrooms` | string | No | Exact bedroom counts, comma separated. Example: 2 or 2,3. | | `bathrooms` | string | No | Exact bathroom counts, comma separated. | | `legality` | string | No | Ids, comma separated: 1 red book or pink book, 2 sale contract, 3 waiting for the book, 4 other. | | `interior` | string | No | Ids, comma separated: 1 full, 2 basic, 3 none, 4 other. | | `floors` | string | No | Floor counts, comma separated: 1 to 4 match exactly, 5 matches five floors and above. | | `frontage_width` | integer | No | 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. | | `road_width` | integer | No | 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. | | `direction` | string | No | 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. | | `balcony_direction` | string | No | Balcony direction ids, same values as direction. | | `location_id` | string | No | Id from the autocomplete route. Use together with location_type. | | `location_type` | string | No | street, district, project or ward. Use together with location_id. The route returns both ready to use. | | `verified` | boolean | No | true for verified listings only. | | `pro_agent` | boolean | No | true for listings of professional agents only. | | `sort` | string | No | default, verified, price_asc, price_desc, price_per_m2_asc, price_per_m2_desc, area_asc or area_desc. | | `page` | integer | No | One-based page number (default 1). | | `per_page` | integer | No | Results per page, 1 to 100 (default 20). | ## Example response ```json { "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 | 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. | | 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)