--- title: "Nhà Tốt API: JSON data, 7 endpoints, 1 credit per call" description: "Nhà Tốt API for Vietnam property listings to buy or rent, projects, sellers, regions and wards as JSON. Seven endpoints, 1 credit per successful call." url: https://perceptlayer.com/apis/nha-tot --- [APIs](https://perceptlayer.com/apis) / [Real estate](https://perceptlayer.com/verticals/real-estate) / Nhà Tốt 1 credit per call 7 endpoints 19 datapoints # Nhà Tốt API Nhà Tốt API for Vietnam property listings to buy or rent, projects, sellers, regions and wards as JSON. Seven endpoints, 1 credit per successful call. [Get a free API key](https://perceptlayer.com/signup) Run it below Nhà Tốt GET /v1/nha-tot/search?for=rent&category=apartment®ion\_id=13000&min\_price=5000000&max\_price=15000000&bedrooms=2&sort=price\_asc ``` { "success": true, "data": { "items": [ { "id": 134515945, "ad_id": 178572599, "url": "https://www.nhatot.com/134515945.htm", "title": "Cho thuê căn studio", "description": "Cho thuê căn hộ trung tâm Q.Bình Thạnh, căn studio riêng biệt được thiết kế tốt giản, ngăn nắp với 2 màu trắng và đen với đầy đủ công năng: 1 Phòng khách, 1PN + bang công, 1 bếp, 1 toilet, 1 gác lửng. Căn hộ căn góc, với nhiều cửa sổ lấy nắ…", "for": "rent", "status": "active", "category": { "id": 1010, "name": "Căn hộ/Chung cư" }, "price": { "amount": 5000000, "currency": "VND", "label": "5 triệu/tháng", "per_m2_million": 0.15151516, "original_amount": 4900000, "original_label": "4,9 triệu/tháng", "change": 100000, "deposit": 8000000, "is_price_valid": true }, "size": { "area_m2": 33, "unit": "m²" }, "rooms": { "bedrooms": 2, "bathrooms": 1 }, "details": { "legal_document": { "code": 6, "key": "pink_book", "label": "Sổ hồng riêng" }, "apartment_type": { "code": 1, "key": "commercial", "label": "Chung cư thương mại" }, "floor": 4, "furnishing_code": 2, "block": "H4", "unit_number": "502" }, "location": { "region": { "id": 13000, "name": "Tp Hồ Chí Minh", "name_v3": "TP Hồ Chí Minh" }, "district": { "id": 13109, "name": "Quận Bình Thạnh", "code": 109 }, "ward": { "id": 9282, "name": "Phường 26", "name_v3": "Phường Bình Thạnh" }, "street": "Đường số 1", "street_number": "502B Block H4", "latitude": 10.813185, "longitude": 106.708725 }, "project": {}, "media": { "thumbnail": "https://cdn.chotot.com/H3r48cFu1CveTwt8bpI3H5vhMgglNbGmWjgkCqT1vVE/preset:listing/plain/1f618f5b12dc9761997a5cd142c0484a-3000705681312158565.jpg", "images": [ "https://cdn.chotot.com/2hGC9Yia4v5GUTP9Iy8jOEF85sR2cVYEmw2qZKCPUIc/preset:view/plain/1f618f5b12dc9761997a5cd142c0484a-3000705681312158565.jpg", "https://cdn.chotot.com/gv8J_EG65PhlsW-XRbP1leljs-j8OPLZbtxMkFh5_LQ/preset:view/plain/f858b0d0642fe82f061c992bb0b85452-3000705680989767287.jpg", "https://cdn.chotot.com/M8pCyTxsS1ZL4RL0nB6cEmAAt5vDbPJ8_FBpGvFKg08/preset:view/plain/15407cbe7ccde3e7408b56f3cb283e7a-3000705681303317545.jpg" ], "image_count": 5, "has_video": false, "map_image": "https://cdn.chotot.com/admincentre/location/10x813985_106x709522_c_v2.jpg" }, "seller": { "account_id": 45621, "oid": "9f5f993a6303ad278083f58e47d5d5e9", "name": "Thich Đạt Dương", "avatar": "https://cdn.chotot.com/uac2/45621", "is_shop_verified": false, "live_ads": 1, "sold_ads": 31 }, "times": { "listed_at": "2026-10-13T14:38:04Z", "listed_at_epoch_ms": 1791902284000 }, "attributes": [ { "id": "property_legal_document", "label": "Giấy tờ pháp lý", "value": "Sổ hồng riêng" }, { "id": "apartment_type", "label": "Loại hình căn hộ", "value": "Chung cư thương mại" }, { "id": "furnishing_sell", "label": "Tình trạng nội thất", "value": "Nội thất đầy đủ" } ], "extra": { "apartment_feature": 1, "is_sticky": false, "job_tier": 0, "protection_entitlement": false, "pty_jupiter": 0, "sticky_ad_platinum": 0 } }, { "id": 135579595, "ad_id": 179821787, "url": "https://www.nhatot.com/135579595.htm", "title": "SHARE 1 PN thường trong căn 2PN2WC chung cư JAMILA KHANG ĐIỀN", "description": "Vào ở liền\n SHARE 1 PN thường trong căn 2PN2WC chung cư JAMILA KHANG ĐIỀN\nSong Hành, Phường Phú Hữu, Thủ Đức, Thành phố Hồ Chí Minh\nVị trí sát bên Quận 2, thuận tiện di chuyển, Q7, Q2, Q1 chạy thằng đường Song Hành ko lo kẹt xe\nThuê nguyên …", "for": "rent", "status": "active", "category": { "id": 1010, "name": "Căn hộ/Chung cư" }, "price": { "amount": 5000000, "currency": "VND", "label": "5 triệu/tháng", "per_m2_million": 0.06944445, "original_amount": 5000000, "original_label": "5 triệu/tháng", "change": 0, "deposit": 5000000, "is_price_valid": true }, "size": { "area_m2": 72, "unit": "m²" }, "rooms": { "bedrooms": 2, "bathrooms": 2 }, "details": { "legal_document": { "code": 5, "key": "sale_contract", "label": "Hợp đồng mua bán" }, "apartment_type": { "code": 1, "key": "commercial", "label": "Chung cư thương mại" }, "floor": 18, "block": "c", "unit_number": "18.01" }, "location": { "region": { "id": 13000, "name": "Tp Hồ Chí Minh", "name_v3": "TP Hồ Chí Minh" }, "district": { "id": 13119, "name": "Thành phố Thủ Đức", "code": 119 }, "ward": { "id": 9262, "name": "Phường Phú Hữu (Quận 9 cũ)", "name_v3": "Phường Long Trường" }, "street": "Song Hành", "latitude": 10.80134, "longitude": 106.74423 }, "project": { "id": 1327, "oid": "912892746", "name": "Jamila Khang Điền", "type": 1, "transaction_status": 0 }, "media": { "thumbnail": "https://cdn.chotot.com/J1KyhIFCLgcAq1PeKCqTb-atN9Sw0fkzXMqT8kPQDSY/preset:listing/plain/c94a46c44a80bd38b7692cddb07b53ab-3008932159793432852.jpg", "images": [ "https://cdn.chotot.com/CQ7FMbfzF80rmFtm274Y-c0JieSBGobwpCEwFI72DYU/preset:view/plain/c94a46c44a80bd38b7692cddb07b53ab-3008932159793432852.jpg", "https://cdn.chotot.com/RespjvmpsMDGHc9XxR15Tjw0-MsvDoCXB0GoNvkF90Q/preset:view/plain/232d8ec4984009191e7b3deff0fd4eb8-3008932159800695478.jpg", "https://cdn.chotot.com/zCKdU_NclNwj-W6rstViGq8dS7HUnaXNTzcxQf0NXBY/preset:view/plain/9b8da142e0ed394c4f50f4f536483d46-3008932159903842921.jpg" ], "image_count": 5, "has_video": false, "map_image": "https://cdn.chotot.com/admincentre/location/10x802140_106x745030_c_v2.jpg" }, "seller": { "account_id": 30315525, "oid": "ed10062d6e3373e3013c675215f1b5aa", "name": "Thu Hằng", "avatar": "https://cdn.chotot.com/uac2/30315525", "is_shop_verified": false, "live_ads": 1 }, "times": { "listed_at": "2026-10-31T16:16:36Z", "listed_at_epoch_ms": 1793463396994, "first_listed_at": "2026-10-31T16:16:36Z", "first_listed_at_epoch_ms": 1793463396000 }, "attributes": [ { "id": "property_legal_document", "label": "Giấy tờ pháp lý", "value": "Hợp đồng mua bán" }, { "id": "apartment_type", "label": "Loại hình căn hộ", "value": "Chung cư thương mại" }, { "id": "size", "label": "Diện tích sử dụng", "value": "72 m²" } ], "extra": { "is_sticky": false, "job_tier": 0, "protection_entitlement": false, "pty_jupiter": 0, "sticky_ad_platinum": 0 } }, { "id": 131028730, "ad_id": 174489849, "url": "https://www.nhatot.com/131028730.htm", "title": "Cho thuê căn hộ ( 1pn,2pn,3pn). Ngay thủ đức tiện di chuyển Q1,Q2,Q9.", "description": "Thông tin căn hộ.\n\n+ Căn 63m² (1PN+1, 1wc): 5tr Ntcb ( Rèm + tủ bếp trên dưới + máy nước nóng + full thiết bị wc) . Full nội thất : 6tr5\n\n+ Căn 73m² (2pn + 2wc): 6tr2 ( Rèm + tủ bếp trên dưới + máy nước nóng + full thiết bị wc) . Full nội t…", "for": "rent", "status": "active", "category": { "id": 1010, "name": "Căn hộ/Chung cư" }, "price": { "amount": 5000000, "currency": "VND", "label": "5 triệu/tháng", "per_m2_million": 0.07936508, "original_amount": 5000000, "original_label": "5 triệu/tháng", "change": 0, "is_price_valid": true }, "size": { "area_m2": 63, "unit": "m²" }, "rooms": { "bedrooms": 2, "bathrooms": 1 }, "details": { "legal_document": { "code": 6, "key": "pink_book", "label": "Sổ hồng riêng" }, "apartment_type": { "code": 1, "key": "commercial", "label": "Chung cư thương mại" } }, "location": { "region": { "id": 13000, "name": "Tp Hồ Chí Minh", "name_v3": "TP Hồ Chí Minh" }, "district": { "id": 13119, "name": "Thành phố Thủ Đức", "code": 119 }, "ward": { "id": 9260, "name": "Phường Long Trường (Quận 9 cũ)", "name_v3": "Phường Long Trường" }, "street": "Trường Lưu", "latitude": 10.79732, "longitude": 106.82337 }, "project": { "id": 4855, "oid": "1651557106", "name": "MT Eastmark City", "type": 1, "transaction_status": 1 }, "media": { "thumbnail": "https://cdn.chotot.com/Fk5kcoKhLLJ5Cfq72ymjO-DZciV9K-uMe8hlSCiNP8g/preset:listing/plain/e3a43a87c77cf0f4b486d81e25231728-2979870643871273557.jpg", "images": [ "https://cdn.chotot.com/e35fvVQUVGn2erIFE0DqO4ZRDSssLmcsDsutjhqgPuA/preset:view/plain/e3a43a87c77cf0f4b486d81e25231728-2979870643871273557.jpg", "https://cdn.chotot.com/vRRUZ_8QF-YipFcDKPMISVsgMkXAnZWLhHsbMZxV_aY/preset:view/plain/7437412371bf39f88f503f91ab1711c5-2979870643975110489.jpg", "https://cdn.chotot.com/WzmY373O_N1BLUYUsSo8UywggmR0jGftKDkccVwxJuw/preset:view/plain/f1b4f4edbcac1ca565d593e87369ddcd-2979870644160608207.jpg" ], "image_count": 9, "has_video": false, "map_image": "https://cdn.chotot.com/admincentre/location/10x798120_106x824170_c_v2.jpg" }, "seller": { "account_id": 19689747, "oid": "1609dc550c93cde545b5c9f6e5ff1b52", "name": "ho van thọ", "avatar": "https://cdn.chotot.com/uac2/19689747", "is_shop_verified": false, "is_company": true, "rating": 4, "rating_count": 4, "ad_rating": 4, "ad_rating_count": 4, "live_ads": 13, "sold_ads": 48 }, "times": { "listed_at": "2026-11-09T03:22:52Z", "listed_at_epoch_ms": 1794194572137, "first_listed_at": "2026-11-06T13:51:40Z", "first_listed_at_epoch_ms": 1793973100000 }, "attributes": [ { "id": "property_legal_document", "label": "Giấy tờ pháp lý", "value": "Sổ hồng riêng" }, { "id": "apartment_type", "label": "Loại hình căn hộ", "value": "Chung cư thương mại" }, { "id": "size", "label": "Diện tích sử dụng", "value": "63 m²" } ], "extra": { "apartment_feature": 0, "is_sticky": false, "job_tier": 0, "protection_entitlement": true, "pty_jupiter": 0, "sticky_ad_platinum": 0 } } ], "page": 1, "per_page": 20, "total": 2967, "total_pages": 149, "has_more": true }, "meta": { "endpoint_family": "search", "request_id": "req_9ce7bf4cfd6447abaf547edb79cfcfaa", "credits_charged": 1, "credits_remaining": 1838 } } ``` 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 | ad\_id integer | url url | title string | description string | for string | status string | category object | price object | size object | rooms object | details object | location object | project object | media object | seller object | times object | attributes object\[\] | extra object | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | 134515945 | 178572599 | https://www.nhatot.com/134515945.htm | Cho thuê căn studio | Cho thuê căn hộ trung tâm Q.Bình Thạnh, căn studio riêng biệt được thiết kế tốt giản, ngăn nắp với 2 màu trắng và đen với đầy đủ công năng: 1 Phòng khách, 1PN + bang công, 1 bếp, 1 toilet, 1 gác lửng. Căn hộ căn góc, với nhiều cửa sổ lấy nắ… | rent | active | {2 fields} | {9 fields} | {2 fields} | {2 fields} | {6 fields} | {7 fields} | {0 fields} | {5 fields} | {7 fields} | {2 fields} | \[3 items\] | {6 fields} | | 2 | 135579595 | 179821787 | https://www.nhatot.com/135579595.htm | SHARE 1 PN thường trong căn 2PN2WC chung cư JAMILA KHANG ĐIỀN | Vào ở liền SHARE 1 PN thường trong căn 2PN2WC chung cư JAMILA KHANG ĐIỀN Song Hành, Phường Phú Hữu, Thủ Đức, Thành phố Hồ Chí Minh Vị trí sát bên Quận 2, thuận tiện di chuyển, Q7, Q2, Q1 chạy thằng đường Song Hành ko lo kẹt xe Thuê nguyên … | rent | active | {2 fields} | {9 fields} | {2 fields} | {2 fields} | {5 fields} | {6 fields} | {5 fields} | {5 fields} | {6 fields} | {4 fields} | \[3 items\] | {5 fields} | | 3 | 131028730 | 174489849 | https://www.nhatot.com/131028730.htm | Cho thuê căn hộ ( 1pn,2pn,3pn). Ngay thủ đức tiện di chuyển Q1,Q2,Q9. | Thông tin căn hộ. + Căn 63m² (1PN+1, 1wc): 5tr Ntcb ( Rèm + tủ bếp trên dưới + máy nước nóng + full thiết bị wc) . Full nội thất : 6tr5 + Căn 73m² (2pn + 2wc): 6tr2 ( Rèm + tủ bếp trên dưới + máy nước nóng + full thiết bị wc) . Full nội t… | rent | active | {2 fields} | {8 fields} | {2 fields} | {2 fields} | {2 fields} | {6 fields} | {5 fields} | {5 fields} | {12 fields} | {4 fields} | \[3 items\] | {6 fields} | Recorded from our API · 3 items shown · 19 datapoints per item GET /v1/nha-tot/search?for=rent&category=apartment®ion\_id=13000&min\_price=5000000&max\_price=15000000&bedrooms=2&sort=price\_asc 19 datapoints ### Identity - id integer - ad\_id integer - title string - status string - category object ### Contact - url url - seller object ### Location - location object ### Reputation - attributes object\[\] ### Price - price object ### Other - description string - for string - size object - rooms object - details object - project object - media object - times object - extra object Playground ## Run this API cURL shell ``` curl "https://api.perceptlayer.com/v1/nha-tot/search?for=rent&category=apartment®ion_id=13000&min_price=5000000&max_price=15000000&bedrooms=2&sort=price_asc" \ -H "X-API-Key: $API_KEY" ``` Nhà Tốt · 7 endpoints ## Endpoints Every endpoint takes the same key. Open one for its parameters and an example request. | Endpoint | Required parameters | Cost | | --- | --- | --- | | [GET `/v1/nha-tot/autocomplete`](https://perceptlayer.com/apis/nha-tot/autocomplete) | `q` | 1 credit | | [GET `/v1/nha-tot/listing`](https://perceptlayer.com/apis/nha-tot/listing) | `id` | 1 credit | | [GET `/v1/nha-tot/projects`](https://perceptlayer.com/apis/nha-tot/projects) | `q` | 1 credit | | [GET `/v1/nha-tot/regions`](https://perceptlayer.com/apis/nha-tot/regions) | none +1 optional | 1 credit | | [GET `/v1/nha-tot/search`](https://perceptlayer.com/apis/nha-tot/search) | `for` +19 optional | 1 credit | | [GET `/v1/nha-tot/seller`](https://perceptlayer.com/apis/nha-tot/seller) | `oid` | 1 credit | | [GET `/v1/nha-tot/wards`](https://perceptlayer.com/apis/nha-tot/wards) | `district_id` | 1 credit | Overview ## About the Nhà Tốt API ## What you can get The Nhà Tốt API returns Nhà Tốt property data as JSON through 7 endpoints. - **Search:** `search` takes `for` (sale or rent), with `category` (all, apartment, house, commercial, land or room), `region_id`, `district_id`, `ward_id`, `min_price`, `max_price`, `min_area`, `max_area`, `bedrooms`, `bathrooms`, `direction` (east, west, south, north, northeast, southeast, northwest or southwest), `legal_document` (pending\_book, deposit\_contract, sale\_contract or pink\_book), `apartment_type` (commercial, serviced\_mini, duplex, penthouse, collective, officetel or social\_housing), `keyword`, `account_id`, `project_oid`, `sort` (newest or price\_asc), `page` and `per_page`. - **Listings:** `listing` takes an `id`. - **Sellers:** `seller` takes an `oid`. - **Projects:** `projects` takes a `q`. - **Locations:** `regions` takes an optional `region_id`; `wards` takes a `district_id`; `autocomplete` takes a `q`. The recorded `search` for two-bedroom apartments to rent in region 13000 (Ho Chi Minh City), priced 5,000,000 to 15,000,000 and sorted by `price_asc`, returns `items` with `id`, `ad_id`, `url`, `title`, `description`, `for`, `status`, `category`, `price`, `size`, `rooms`, `details`, `location`, `project`, `media`, `seller`, `times` and `attributes`, plus `page`, `per_page`, `total` (2,967), `total_pages` and `has_more`. ## How a call works Search a region: `GET /v1/nha-tot/search?for=rent&category=apartment®ion_id=13000&bedrooms=2&sort=price_asc` with your key in the `X-API-Key` header. Each item's `id` is what `listing` takes, `seller.oid` is what `seller` takes, and `location.district.id` is the `district_id` that `wards` takes. Page with `page` while `has_more` is true. 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 asking rents and sale prices for apartments in Ho Chi Minh City or another region `Use the Nhà Tốt API to track asking rents and sale prices for apartments in Ho Chi Minh City or another region` ### Compare listings by district and ward, using \`regions\` and \`wards\` to map the IDs `` Use the Nhà Tốt API to compare listings by district and ward, using `regions` and `wards` to map the IDs `` ### Filter homes by legal status with \`legal\_document\`, such as pink\_book `` Use the Nhà Tốt API to filter homes by legal status with `legal_document`, such as pink_book `` ### Follow a seller's activity through \`seller\` `` Use the Nhà Tốt API to follow a seller's activity through `seller` `` FAQ ## Questions **Do I need a Nhà Tốt account?** No. You call this Nhà Tốt API with your Perceptlayer key in the \`X-API-Key\` header, with no Nhà Tốt login. **How much does the Nhà Tốt 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. **How do I find a region or ward ID?** Call \`regions\` for region IDs, then \`wards\` with a \`district\_id\`. Each search item also carries its region, district and ward IDs under \`location\`. **Should I build a Nhà Tốt scraper instead?** You can, but a Nhà Tốt scraper is code you maintain: page changes break it, requests get blocked, and Nhà Tốt's terms govern how you collect data. The Nhà Tốt API gives you 7 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 Nhà Tốt 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)