# Batdongsan Similar Listings API Documentation

<p><strong>Batdongsan Similar Listings API</strong> returns listings that resemble one listing, in the same shape as the search items.</p><p>Good to know:</p><ul><li>The site returns an empty list for an unknown id and for a listing without neighbours. Both return 404 and are not billed.</li></ul>

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

## 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": {
        "items": [
            {
                "id": 44304828,
                "url": "https://batdongsan.com.vn/ban-nha-biet-thu-lien-ke-pho-giang-vo-vinhomes-the-gallery/hot-em-co-5-lo-goc-ngoai-giao-cap-cao-chiet-khau-32-...",
                "vip": {
                    "id": 5,
                    "name": "Th\u01b0\u1eddng"
                },
                "area": 124,
                "price": {
                    "display": "96 t\u1ef7",
                    "unit_id": 2,
                    "value_vnd": 96000000000,
                    "unit_display": "774,19 tr/m\u00b2"
                },
                "title": "HOT - Em c\u00f3 l\u00f4 g\u00f3c ngo\u1ea1i giao c\u1ea5p cao chi\u1ebft kh\u1ea5u 32%, c\u0103n n\u1ed5i b\u1eadt trong d\u1ef1 \u00e1n (c\u00f3 1 - 0 - 2)",
                "author": {
                    "id": 3682565,
                    "name": "Thanh Thu\u00fd",
                    "agent_id": null,
                    "avatar_url": "https://file4.batdongsan.com.vn/resize/200x200/2026/05/06/20260506122628-a434.jpg",
                    "profile_url": null,
                    "is_pro_agent": true,
                    "phone_masked": "0975440***"
                },
                "images": [
                    {
                        "url": "https://file4.batdongsan.com.vn/2025/10/17/20251017121031-189a_wm.jpg",
                        "caption": null,
                        "crop_url": "https://file4.batdongsan.com.vn/resize/492x273/2025/10/17/20251017121031-189a_wm.jpg",
                        "thumb_url": "https://file4.batdongsan.com.vn/resize/745x510/2025/10/17/20251017121031-189a_wm.jpg"
                    }
                ],
                "address": {
                    "full": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303, Qu\u1eadn Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
                    "short": "P. Gia\u0309ng Vo\u0303 (P. Gi\u1ea3ng V\u00f5 m\u1edbi)",
                    "city_level": "Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
                    "district_level": "Gia\u0309ng Vo\u0303, Ba \u0110\u00ecnh"
                },
                "bedrooms": null,
                "category": {
                    "id": 325,
                    "name": "B\u00e1n nh\u00e0 bi\u1ec7t th\u1ef1, li\u1ec1n k\u1ec1"
                },
                "location": {
                    "address": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5, H\u00e0 N\u1ed9i",
                    "ward_id": 14347,
                    "city_code": "HN",
                    "city_name": "H\u00e0 N\u1ed9i",
                    "street_id": 438,
                    "ward_name": "Ph\u01b0\u1eddng Gi\u1ea3ng V\u00f5",
                    "project_id": 6318,
                    "street_name": "Ph\u1ed1 Gi\u1ea3ng V\u00f5",
                    "project_name": "Vinhomes The Gallery"
                },
                "verified": {
                    "date": null,
                    "is_verified": false
                },
                "bathrooms": null,
                "video_url": null,
                "is_expired": false,
                "description": "Em Thanh Th\u00fay Vinhomes xin k\u00ednh ch\u00e0o qu\u00fd anh ch\u1ecb nh\u00e0 \u0111\u1ea7u t\u01b0 \u0111\u1ebfn v\u1edbi d\u1ef1 \u00e1n Vinhomes The Gallery Gi\u1ea3ng V\u00f5.\n\nV\u1edbi 10 n\u0103m kinh nghi\u1ec7m b\u00e1n c\u00e1c ...",
                "media_count": 12,
                "last_up_time": "2026-10-25T07:44:35.067+00:00",
                "listing_type": "sale",
                "old_location": {
                    "address": "Vinhomes The Gallery, Ph\u1ed1 Gi\u1ea3ng V\u00f5, Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303, Qu\u1eadn Ba \u0110\u00ecnh, H\u00e0 N\u1ed9i",
                    "ward_id": 62,
                    "city_code": "HN",
                    "city_name": "H\u00e0 N\u1ed9i",
                    "street_id": 438,
                    "ward_name": "Ph\u01b0\u1eddng Gia\u0309ng Vo\u0303",
                    "project_id": 6318,
                    "district_id": 2,
                    "street_name": "Ph\u1ed1 Gi\u1ea3ng V\u00f5",
                    "project_name": "Vinhomes The Gallery",
                    "district_name": "Qu\u1eadn Ba \u0110\u00ecnh"
                },
                "posted_label": "H\u00f4m qua"
            }
        ],
        "listing_id": 46364654
    },
    "meta": {
        "billable": true,
        "endpoint_family": "similar"
    },
    "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 similar listings. 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)