Batdongsan Map Markers API lists what the site draws on its map inside a box: single listings with a price label and project clusters with the number of listings. Use it for map views and for counts per project.
Good to know:
- The north-east corner must lie north and east of the south-west corner, or the request returns 422.
- Marker types: 2 is a project cluster, 1 and 3 are single listings with
listing_id. - Search the listings of a project with the search route and
location_type=project.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
5 required parameters needed before sending a request.
1 optional filter available.
string
Required
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.
example
number
Required
Latitude of the north-east corner.
10
number
Required
Longitude of the north-east corner.
10
number
Required
Latitude of the south-west corner.
10
number
Required
Longitude of the south-west corner.
10
string
Optional
sale (default) or rent.
example
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"city": "HN",
"bounds": {
"north_east": {
"lat": 21.05,
"lng": 105.87
},
"south_west": {
"lat": 21,
"lng": 105.8
}
},
"markers": [
{
"count": 86,
"latitude": 21.00580596923828,
"longitude": 105.79437255859376,
"listing_id": null,
"project_id": 2191,
"marker_type": 2,
"vip_type_id": null,
"price_display": null
},
{
"count": 49,
"latitude": 21.004484176635746,
"longitude": 105.7986297607422,
"listing_id": null,
"project_id": 612,
"marker_type": 2,
"vip_type_id": null,
"price_display": null
}
],
"listing_type": "sale",
"total_markers": 6
},
"meta": {
"billable": true,
"endpoint_family": "map_markers"
},
"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"
}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": "map_markers"
},
"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.