# Batdongsan Price History API Documentation

<p><strong>Batdongsan Price History API</strong> 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.</p><p>Good to know:</p><ul><li>Prices in the chart are shown as the site shows them, with a unit such as <code>tr/m²</code> (million dong per square meter).</li><li>Unknown ids return 404 and are not billed.</li></ul>

- **Documentation:** [https://scrappa.co/docs/batdongsan-api/batdongsan_price_history](https://scrappa.co/docs/batdongsan-api/batdongsan_price_history)
- **API group:** Batdongsan API
- **Endpoint:** `GET https://scrappa.co/api/batdongsan/price-history`

## 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 |
| --- | --- | --- | --- |
| `id` | string | Yes | Numeric listing id from search. |

## Example response

```json
{
    "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

| 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. |
| 404 | Not Found | The listing does not exist or has no price history. 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)