--- title: "Batdongsan.com.vn API: 8 endpoints, 1 credit per call" description: "Batdongsan.com.vn API for Vietnamese property for sale or rent, price history, similar listings, map markers and agents as JSON. 1 credit per successful call." url: https://perceptlayer.com/apis/batdongsan --- [APIs](https://perceptlayer.com/apis) / [Real estate](https://perceptlayer.com/verticals/real-estate) / Batdongsan.com.vn 1 credit per call 8 endpoints 21 datapoints # Batdongsan.com.vn API Batdongsan.com.vn API for Vietnamese property for sale or rent, price history, similar listings, map markers and agents as JSON. 1 credit per successful call. [Get a free API key](https://perceptlayer.com/signup) Run it below Batdongsan.com.vn GET /v1/batdongsan/search?listing\_type=sale&city=HN&min\_area=50&max\_area=60&bedrooms=2&bathrooms=2&sort=price\_asc ``` { "success": true, "data": { "applied_filters": { "listing_type": "sale", "city": "HN", "min_area": "50", "max_area": "60", "bedrooms": "2", "bathrooms": "2", "sort": "price_asc" }, "pagination": { "page": 1, "per_page": 20, "total": 546, "total_pages": 28, "returned": 13, "has_next_page": true }, "items": [ { "id": 46479967, "url": "https://batdongsan.com.vn/ban-can-ho-chung-cu-duong-to-huu-mhd-trung-van/re-nhat-du-an-ban-2-ngu-2wc-tai-gia-1-950-ty-lh-pr46479967", "title": "(Rẻ nhất dự án) Bán căn 2 phòng ngủ 2wc tại MHD Trung Văn giá 1.650 tỷ. LH", "category": { "id": 324, "name": "Bán căn hộ chung cư" }, "listing_type": "sale", "price": { "value_vnd": 1650000000, "display": "1,65 tỷ", "unit_display": "33 tr/m²", "unit_id": 2 }, "area": 50, "bedrooms": 2, "bathrooms": 2, "address": { "full": "MHD Trung Văn, Đường Tố Hữu, Phường Trung Văn, Quận Nam Từ Liêm, Hà Nội", "city_level": "Nam Từ Liêm, Hà Nội", "district_level": "Trung Văn, Nam Từ Liêm", "short": "Q. Nam Từ Liêm (P. Đại Mỗ mới)" }, "location": { "city_code": "HN", "city_name": "Hà Nội", "ward_id": 23563, "ward_name": "Phường Đại Mỗ", "street_id": 3151, "street_name": "Đường Tố Hữu", "project_id": 4699, "project_name": "MHD Trung Văn", "address": "MHD Trung Văn, Đường Tố Hữu, Phường Đại Mỗ, Hà Nội" }, "old_location": { "district_id": 14, "district_name": "Quận Nam Từ Liêm", "city_code": "HN", "city_name": "Hà Nội", "ward_id": 11381, "ward_name": "Phường Trung Văn", "street_id": 3151, "street_name": "Đường Tố Hữu", "project_id": 4699, "project_name": "MHD Trung Văn", "address": "MHD Trung Văn, Đường Tố Hữu, Phường Trung Văn, Quận Nam Từ Liêm, Hà Nội" }, "images": [ { "url": "https://file4.batdongsan.com.vn/2026/10/29/20261029095512-25e7_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/10/29/20261029095512-25e7_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/10/29/20261029095512-25e7_wm.jpg" }, { "url": "https://file4.batdongsan.com.vn/2026/10/29/20261029095512-0167_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/10/29/20261029095512-0167_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/10/29/20261029095512-0167_wm.jpg" }, { "url": "https://file4.batdongsan.com.vn/2026/10/29/20261029095512-3496_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/10/29/20261029095512-3496_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/10/29/20261029095512-3496_wm.jpg" } ], "media_count": 13, "description": "Bán gấp căn 2 phòng ngủ 2wc tại MHD Trung Văn!\n\nTòa A MHD Trung Văn.\n50m | 2PN | 2WC.\nFull nội thất đẹp như ảnh vào ở ngay!\nThời hạn 40 năm tính từ 2026.\nCam kết nhà thật giá thật.\n\nGiá chỉ 1,650 tỷ căn 2 ngủ diện tích đẹp, vị trí thuận lợi…", "vip": { "id": 5, "name": "Thường" }, "verified": { "is_verified": false }, "is_expired": false, "last_up_time": "2026-11-07T20:26:50.885+00:00", "posted_label": "5 ngày trước", "author": { "id": 1813345, "name": "Lê Dương", "avatar_url": "https://file4.batdongsan.com.vn/resize/200x200/2024/06/26/20240626145836-18e9.jpg", "phone_masked": "0971516***", "profile_url": "https://guru.batdongsan.com.vn/pa/923cbf4a118c5b69", "agent_id": "923cbf4a118c5b69", "is_pro_agent": true } }, { "id": 46479261, "url": "https://batdongsan.com.vn/ban-can-ho-chung-cu-phuong-hoang-liet-hh2-linh-dam/hh-am-56m2-1-7-ty-tang-toa-an-toan-pr46479261", "title": "HH2 Linh Đàm - 56m2 - 1,7 tỷ - Tầng, tòa an toàn", "category": { "id": 324, "name": "Bán căn hộ chung cư" }, "listing_type": "sale", "price": { "value_vnd": 1700000000, "display": "1,7 tỷ", "unit_display": "30,36 tr/m²", "unit_id": 2 }, "area": 56, "bedrooms": 2, "bathrooms": 2, "address": { "full": "HH2 Linh Đàm, Phường Hoàng Liệt, Quận Hoàng Mai, Hà Nội", "city_level": "Hoàng Mai, Hà Nội", "district_level": "Hoàng Liệt, Hoàng Mai", "short": "Q. Hoàng Mai (P. Hoàng Liệt mới)" }, "location": { "city_code": "HN", "city_name": "Hà Nội", "ward_id": 4363, "ward_name": "Phường Hoàng Liệt", "project_id": 2319, "project_name": "HH2 Linh Đàm", "address": "HH2 Linh Đàm, Phường Hoàng Liệt, Hà Nội" }, "old_location": { "district_id": 8, "district_name": "Quận Hoàng Mai", "city_code": "HN", "city_name": "Hà Nội", "ward_id": 9484, "ward_name": "Phường Hoàng Liệt", "project_id": 2319, "project_name": "HH2 Linh Đàm", "address": "HH2 Linh Đàm, Phường Hoàng Liệt, Quận Hoàng Mai, Hà Nội" }, "images": [ { "url": "https://file4.batdongsan.com.vn/2026/10/29/20261029083548-519e_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/10/29/20261029083548-519e_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/10/29/20261029083548-519e_wm.jpg" }, { "url": "https://file4.batdongsan.com.vn/2026/10/29/20261029083548-dac5_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/10/29/20261029083548-dac5_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/10/29/20261029083548-dac5_wm.jpg" }, { "url": "https://file4.batdongsan.com.vn/2026/10/29/20261029083548-13db_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/10/29/20261029083548-13db_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/10/29/20261029083548-13db_wm.jpg" } ], "media_count": 4, "description": "HH2 Linh Đàm - 56m2 - 1,7 tỷ - Tầng, tòa an toàn\n56m2 - 2PN 2VS\nCửa Bắc, ban công Tây Nam\nGiá 1,7 tỷ\nNhà full đồ 3 ĐH, trần, sàn, máy giặt, tủ lạnh, giường, tủ...\nLiên hệ Hương", "vip": { "id": 5, "name": "Thường" }, "verified": { "is_verified": false }, "is_expired": false, "last_up_time": "2026-10-29T08:36:35.087+00:00", "posted_label": "2 tuần trước", "author": { "id": 4773659, "name": "Thu Hương BĐS", "avatar_url": "https://file4.batdongsan.com.vn/resize/200x200/2026/10/29/20261029081922-a901.jpg", "phone_masked": "0392731***", "profile_url": "https://guru.batdongsan.com.vn/pa/744730857936586b", "agent_id": "744730857936586b", "is_pro_agent": false } }, { "id": 45565972, "url": "https://batdongsan.com.vn/ban-can-ho-chung-cu-xa-dai-thinh-chung-cu-rosa-garden/ban-cc-gia-thoa-thuan-54m2-2pn-2wc-me-linh-ha-noi-pr45565972", "title": "Bán chung cư Rosa Garden HUD Mê Linh Central, 54m2, 2PN, 2WC full đồ cho thuê được 7 triệu/tháng", "category": { "id": 324, "name": "Bán căn hộ chung cư" }, "listing_type": "sale", "price": { "value_vnd": 1950000000, "display": "1,95 tỷ", "unit_display": "36,11 tr/m²", "unit_id": 2 }, "area": 54, "bedrooms": 2, "bathrooms": 2, "address": { "full": "Chung cư Rosa Garden, Xã Đại Thịnh, Huyện Mê Linh, Hà Nội", "city_level": "Mê Linh, Hà Nội", "district_level": "Đại Thịnh, Mê Linh", "short": "H. Mê Linh (X. Quang Minh mới)" }, "location": { "city_code": "HN", "city_name": "Hà Nội", "ward_id": 8971, "ward_name": "Xã Quang Minh", "project_id": 5196, "project_name": "Chung cư Rosa Garden", "address": "Chung cư Rosa Garden, Xã Quang Minh, Hà Nội" }, "old_location": { "district_id": 17, "district_name": "Huyện Mê Linh", "city_code": "HN", "city_name": "Hà Nội", "ward_id": 10167, "ward_name": "Xã Đại Thịnh", "project_id": 5196, "project_name": "Chung cư Rosa Garden", "address": "Chung cư Rosa Garden, Xã Đại Thịnh, Huyện Mê Linh, Hà Nội" }, "images": [ { "url": "https://file4.batdongsan.com.vn/2026/09/22/20260922170634-c016_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/09/22/20260922170634-c016_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/09/22/20260922170634-c016_wm.jpg" }, { "url": "https://file4.batdongsan.com.vn/2026/09/22/20260922170634-32e8_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/09/22/20260922170634-32e8_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/09/22/20260922170634-32e8_wm.jpg" }, { "url": "https://file4.batdongsan.com.vn/2026/09/22/20260922170634-c5b2_wm.jpg", "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2026/09/22/20260922170634-c5b2_wm.jpg", "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2026/09/22/20260922170634-c5b2_wm.jpg" } ], "media_count": 3, "description": "Bán chung cư Rosa Garden HUD Mê Linh Central diện tích 54m2, 2PN, 2WC full đồ cho thuê được 7 triệu/tháng và đối diện dự án Khu đô thị 205 hecta của Sungroup. Với diện tích 54m2, căn hộ này được thiết kế gồm 2 phòng ngủ và 2 phòng tắm, phù …", "vip": { "id": 5, "name": "Thường" }, "verified": { "is_verified": false }, "is_expired": false, "last_up_time": "2026-11-08T13:01:07.12+00:00", "posted_label": "4 ngày trước", "author": { "id": 813620, "name": "Nguyễn Văn Đạt", "avatar_url": "https://file4.batdongsan.com.vn/resize/200x200/2025/05/07/20250507102248-d4f5.jpg", "phone_masked": "0937827***", "profile_url": "https://guru.batdongsan.com.vn/pa/f64a3999b9ff94da", "agent_id": "f64a3999b9ff94da", "is_pro_agent": true } } ] }, "meta": { "filtered_out": 7, "endpoint_family": "search", "request_id": "req_eb2bd3de9cec40779b5530799228ad15", "credits_charged": 1, "credits_remaining": 1891 } } ``` 200 OK JSON X-Credits-Used: 1 Recorded from our API and shortened. Sample data ## What one call returns A recorded run of `search`: the fields and shapes you will get, shortened to 3 items. | # | id integer | url url | title string | category object | listing\_type string | price object | area integer | bedrooms integer | bathrooms integer | address object | location object | old\_location object | images object\[\] | media\_count integer | description string | vip object | verified object | is\_expired boolean | last\_up\_time string | posted\_label string | author object | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | 46479967 | https://batdongsan.com.vn/ban-can-ho-chung-cu-duong-to-huu-mhd-trung-van/re-nhat-du-an-ban-2-ngu-2wc-tai-gia-1-950-ty-lh-pr46479967 | (Rẻ nhất dự án) Bán căn 2 phòng ngủ 2wc tại MHD Trung Văn giá 1.650 tỷ. LH | {2 fields} | sale | {4 fields} | 50 | 2 | 2 | {4 fields} | {9 fields} | {11 fields} | \[3 items\] | 13 | Bán gấp căn 2 phòng ngủ 2wc tại MHD Trung Văn! Tòa A MHD Trung Văn. 50m \| 2PN \| 2WC. Full nội thất đẹp như ảnh vào ở ngay! Thời hạn 40 năm tính từ 2026. Cam kết nhà thật giá thật. Giá chỉ 1,650 tỷ căn 2 ngủ diện tích đẹp, vị trí thuận lợi… | {2 fields} | {1 fields} | false | 2026-11-07T20:26:50.885+00:00 | 5 ngày trước | {7 fields} | | 2 | 46479261 | https://batdongsan.com.vn/ban-can-ho-chung-cu-phuong-hoang-liet-hh2-linh-dam/hh-am-56m2-1-7-ty-tang-toa-an-toan-pr46479261 | HH2 Linh Đàm - 56m2 - 1,7 tỷ - Tầng, tòa an toàn | {2 fields} | sale | {4 fields} | 56 | 2 | 2 | {4 fields} | {7 fields} | {9 fields} | \[3 items\] | 4 | HH2 Linh Đàm - 56m2 - 1,7 tỷ - Tầng, tòa an toàn 56m2 - 2PN 2VS Cửa Bắc, ban công Tây Nam Giá 1,7 tỷ Nhà full đồ 3 ĐH, trần, sàn, máy giặt, tủ lạnh, giường, tủ... Liên hệ Hương | {2 fields} | {1 fields} | false | 2026-10-29T08:36:35.087+00:00 | 2 tuần trước | {7 fields} | | 3 | 45565972 | https://batdongsan.com.vn/ban-can-ho-chung-cu-xa-dai-thinh-chung-cu-rosa-garden/ban-cc-gia-thoa-thuan-54m2-2pn-2wc-me-linh-ha-noi-pr45565972 | Bán chung cư Rosa Garden HUD Mê Linh Central, 54m2, 2PN, 2WC full đồ cho thuê được 7 triệu/tháng | {2 fields} | sale | {4 fields} | 54 | 2 | 2 | {4 fields} | {7 fields} | {9 fields} | \[3 items\] | 3 | Bán chung cư Rosa Garden HUD Mê Linh Central diện tích 54m2, 2PN, 2WC full đồ cho thuê được 7 triệu/tháng và đối diện dự án Khu đô thị 205 hecta của Sungroup. Với diện tích 54m2, căn hộ này được thiết kế gồm 2 phòng ngủ và 2 phòng tắm, phù … | {2 fields} | {1 fields} | false | 2026-11-08T13:01:07.12+00:00 | 4 ngày trước | {7 fields} | Recorded from our API · 3 items shown · 21 datapoints per item GET /v1/batdongsan/search?listing\_type=sale&city=HN&min\_area=50&max\_area=60&bedrooms=2&bathrooms=2&sort=price\_asc 21 datapoints ### Identity - id integer - title string - category object - listing\_type string ### Contact - url url ### Location - area integer - address object - location object - old\_location object ### Reputation - images object\[\] - verified object ### Price - price object ### Other - bedrooms integer - bathrooms integer - media\_count integer - description string - vip object - is\_expired boolean - last\_up\_time string - posted\_label string - author object Playground ## Run this API cURL shell ``` curl "https://api.perceptlayer.com/v1/batdongsan/search?listing_type=sale&city=HN&min_area=50&max_area=60&bedrooms=2&bathrooms=2&sort=price_asc" \ -H "X-API-Key: $API_KEY" ``` Batdongsan.com.vn · 8 endpoints ## Endpoints Every endpoint takes the same key. Open one for its parameters and an example request. | Endpoint | Required parameters | Cost | | --- | --- | --- | | [GET `/v1/batdongsan/agent`](https://perceptlayer.com/apis/batdongsan/agent) | `agent_id` | 1 credit | | [GET `/v1/batdongsan/autocomplete`](https://perceptlayer.com/apis/batdongsan/autocomplete) | `query` +1 optional | 1 credit | | [GET `/v1/batdongsan/listing`](https://perceptlayer.com/apis/batdongsan/listing) | `id` | 1 credit | | [GET `/v1/batdongsan/map-markers`](https://perceptlayer.com/apis/batdongsan/map-markers) | `city` `north_east_lat` `north_east_lng` `south_west_lat` `south_west_lng` +1 optional | 1 credit | | [GET `/v1/batdongsan/price-history`](https://perceptlayer.com/apis/batdongsan/price-history) | `id` | 1 credit | | [GET `/v1/batdongsan/search`](https://perceptlayer.com/apis/batdongsan/search) | `city` +22 optional | 1 credit | | [GET `/v1/batdongsan/similar`](https://perceptlayer.com/apis/batdongsan/similar) | `id` | 1 credit | | [GET `/v1/batdongsan/top-agents`](https://perceptlayer.com/apis/batdongsan/top-agents) | `city` | 1 credit | Overview ## About the Batdongsan.com.vn API ## What you can get The Batdongsan.com.vn API returns Batdongsan.com.vn property data for Vietnam as JSON through 8 endpoints. Searches, map markers and top agents take a `city` code, one of 63, such as HN or SG. - **Search:** `search` takes a `city`, with `listing_type` (sale or rent), `category`, `min_price`, `max_price`, `min_area`, `max_area`, `bedrooms`, `bathrooms`, `frontage_width` and `road_width` (1 to 6), `location_id` and `location_type` (street, district, project or ward), `verified`, `pro_agent`, `legality`, `interior`, `floors`, `direction`, `balcony_direction`, `sort` (default, verified, price\_asc, price\_desc, price\_per\_m2\_asc, price\_per\_m2\_desc, area\_asc or area\_desc), `page` and `per_page`. - **Map:** `map-markers` takes a `city` and a bounding box ( `north_east_lat`, `north_east_lng`, `south_west_lat`, `south_west_lng`), with `listing_type` (sale or rent). - **Listings:** `listing`, `price-history` and `similar` take an `id`. - **Agents:** `agent` takes an `agent_id`; `top-agents` takes a `city`. - **Autocomplete:** `autocomplete` takes a `query`, with `limit`. The recorded `search` ( `listing_type=sale`, `city=HN`, `min_area=50`, `max_area=60`, `bedrooms=2`, `bathrooms=2`, `sort=price_asc`) returns `items`, each with `id`, `url`, `title`, `category`, `listing_type`, `price` ( `value_vnd`, `display`, `unit_display`), `area`, `bedrooms`, `bathrooms`, `address`, `location` (city, ward, street and project), `images`, `description`, `verified`, `last_up_time`, `posted_label` and `author`. Its `pagination` gives `total` (546), `total_pages`, `returned` and `has_next_page`. ## How a call works Search two-bedroom flats for sale in Hanoi: `GET /v1/batdongsan/search?listing_type=sale&city=HN&min_area=50&max_area=60&bedrooms=2&bathrooms=2&sort=price_asc` with your key in the `X-API-Key` header. Each item's `id` goes to `listing`, `price-history` and `similar`, and its `author.agent_id` goes to `agent`. Every successful call costs 1 credit; failed calls cost nothing. Real estate JSON REST MCP ### More real estate APIs [28Hse](https://perceptlayer.com/apis/28hse) [4zida](https://perceptlayer.com/apis/4zida) [591](https://perceptlayer.com/apis/591-house) [99.co](https://perceptlayer.com/apis/99co) [99acres](https://perceptlayer.com/apis/99acres) [Adondevivir](https://perceptlayer.com/apis/adondevivir) [Apartment List](https://perceptlayer.com/apis/apartment-list) [Apartments.com](https://perceptlayer.com/apis/apartments-com) [Aqar](https://perceptlayer.com/apis/aqar) [Aqarmap](https://perceptlayer.com/apis/aqarmap) [Argenprop](https://perceptlayer.com/apis/argenprop) [athome](https://perceptlayer.com/apis/athome) Use cases ### Track apartment prices in đồng and price per square metre in Hanoi and other Vietnamese cities `Use the Batdongsan.com.vn API to track apartment prices in đồng and price per square metre in Hanoi and other Vietnamese cities` ### Follow a listing's asking price over time with \`price-history\` `` Use the Batdongsan.com.vn API to follow a listing's asking price over time with `price-history` `` ### Pull comparables for a listing with \`similar\` `` Use the Batdongsan.com.vn API to pull comparables for a listing with `similar` `` ### Plot listings inside a bounding box with \`map-markers\` `` Use the Batdongsan.com.vn API to plot listings inside a bounding box with `map-markers` `` FAQ ## Questions **Do I need a Batdongsan.com.vn account?** No. You call this Batdongsan.com.vn API with your Perceptlayer key in the \`X-API-Key\` header, with no Batdongsan.com.vn login. **How much does the Batdongsan.com.vn API cost?** Each successful call costs one credit. New accounts get free credits to start, and credit packs bring the price down as you scale. **What format are responses in?** Every endpoint returns JSON, with no HTML parsing on your side. **Can I see how a listing's price has changed?** Yes. Pass the listing's \`id\` to \`price-history\`. **Should I build a Batdongsan.com.vn scraper instead?** You can, but a Batdongsan.com.vn scraper is code you maintain: page changes break it, requests get blocked, and Batdongsan.com.vn's terms govern how you collect data. The Batdongsan.com.vn API gives you 8 endpoints of named JSON fields for 1 credit per successful call, and failed calls cost nothing. A scraper makes sense only for data these endpoints don't return, so check the response in the playground on this page first. ## Try the Batdongsan.com.vn API with 100 free credits No credit card. Failed calls are never billed. [Get a free API key](https://perceptlayer.com/signup) [Read the docs](https://docs.perceptlayer.com)