Batdongsan Price History API returns the quarterly price chart for the project or area of a listing: minimum, average and maximum price per square meter for each quarter, the most common price, the change over time and how the listing compares with the usual price.
Good to know:
- Prices in the chart are shown as the site shows them, with a unit such as
tr/m²(million dong per square meter). - Unknown ids return 404 and are not billed.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
string
Required
Numeric listing id from search.
1234567890
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"unit": "tr/m\u00b2",
"title": "L\u1ecbch s\u1eed gi\u00e1 b\u00e1n nh\u00e0 bi\u1ec7t th\u1ef1, li\u1ec1n k\u1ec1 t\u1ea1i Vinhomes The Gallery",
"market": {
"common_price_label": "Gi\u00e1 b\u00e1n ph\u1ed5 bi\u1ebfn nh\u1ea5t",
"common_price_value": "722,2 tr/m\u00b2",
"changed_percent_label": "",
"changed_percent_value": "0%",
"common_price_timeline": "Q3/26",
"changed_percent_status": 0,
"changed_percent_timeline": "",
"changed_percent_is_enabled": true,
"percent_distance_from_max_label": "Gi\u00e1 ph\u1ed5 bi\u1ebfn Q3/26 l\u00e0 cao nh\u1ea5t trong 1 n\u0103m qua",
"percent_distance_from_max_value": "0%",
"percent_distance_from_max_status": 0,
"percent_distance_from_max_timeline": "Q3/26",
"percent_distance_from_max_original_max_value": "722,2 tr/m\u00b2"
},
"points": [
{
"avg": 709.1,
"max": 774.2,
"min": 612.9,
"label": "Q1/26",
"avg_display": "709,1 tr/m\u00b2",
"max_display": "774,2 tr/m\u00b2",
"min_display": "612,9 tr/m\u00b2"
},
{
"avg": 722.2,
"max": 849.9,
"min": 673,
"label": "Q2/26",
"avg_display": "722,2 tr/m\u00b2",
"max_display": "849,9 tr/m\u00b2",
"min_display": "673 tr/m\u00b2"
}
],
"locations": [],
"listing_id": 46364654,
"is_project_chart": true,
"current_price_display": "333.33 tr/m\u00b2",
"listing_vs_common_price": {
"percent_distance_of_current_price_label": "Gi\u00e1 tin \u0111ang xem th\u1ea5p h\u01a1n gi\u00e1 ph\u1ed5 bi\u1ebfn",
"percent_distance_of_current_price_value": "53,8%",
"percent_distance_of_current_price_status": -1,
"percent_distance_of_current_price_timeline": "Q3/26"
}
},
"meta": {
"billable": true,
"endpoint_family": "price_history"
},
"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"
}Not Found
The listing does not exist or has no price history. This response is not billed.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "price_history"
},
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found."
},
"success": false
}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": "price_history"
},
"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.