# Batdongsan Autocomplete API Documentation

<p><strong>Batdongsan Autocomplete API</strong> turns a place name into locations. Each result names the province, district, ward, street and project it covers. The fields <code>location_id</code> and <code>location_type</code> feed the search route directly. The most specific part wins: project, then street, ward, district.</p><p>Good to know:</p><ul><li>Results use the ward system that the search filters honour, so every returned id filters.</li><li>Type the name with or without accents.</li></ul>

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

## 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 |
| --- | --- | --- | --- |
| `query` | string | Yes | Place name, 2 to 100 characters. Example: cau giay. |
| `limit` | integer | No | Number of results, 1 to 25 (default 10). |

## Example response

```json
{
    "data": {
        "query": "cau giay",
        "results": [
            {
                "kind": "place",
                "ward_id": null,
                "latitude": null,
                "city_code": "HN",
                "city_name": "H\u00e0 N\u1ed9i",
                "longitude": null,
                "street_id": null,
                "ward_name": null,
                "project_id": null,
                "suggestion": "Qu\u1eadn C\u1ea7u Gi\u1ea5y, H\u00e0 N\u1ed9i",
                "district_id": 7,
                "location_id": "7",
                "street_name": null,
                "project_name": null,
                "district_name": "C\u1ea7u Gi\u1ea5y",
                "location_type": "district",
                "address_version": 0
            },
            {
                "kind": "place",
                "ward_id": null,
                "latitude": null,
                "city_code": "HN",
                "city_name": "H\u00e0 N\u1ed9i",
                "longitude": null,
                "street_id": 3981,
                "ward_name": null,
                "project_id": null,
                "suggestion": "\u0110\u01b0\u1eddng C\u1ea7u Gi\u1ea5y, Qu\u1eadn \u0110\u1ed1ng \u0110a, H\u00e0 N\u1ed9i",
                "district_id": 3,
                "location_id": "3981",
                "street_name": "C\u1ea7u Gi\u1ea5y",
                "project_name": null,
                "district_name": "\u0110\u1ed1ng \u0110a",
                "location_type": "street",
                "address_version": 0
            }
        ]
    },
    "meta": {
        "billable": true,
        "endpoint_family": "autocomplete"
    },
    "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. |
| 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)