# Danh sách địa chỉ

* API này dùng để lấy danh sách địa chỉ: thành phố, quận huyện, phường xã.
* Chú ý: Dữ liệu rất ít khi bị thay đổi (chỉ xảy ra khi có thay đổi tên, chia tách hoặc gộp), bạn có thể cache dữ liệu trên hệ thống của bạn để giảm tải việc phải gọi API liên tục, thời gian cache khuyến cáo là 24h.
* API hỗ trợ lấy dữ liệu cho cả địa chỉ hành chính cũ 3 cấp (Tỉnh / Thành phố, Quận / Huyện, Phường / Xã) và địa chỉ hành chính mới 2 cấp (Tỉnh / Thành phố, Phường / Xã)
* **Chú ý**:
  * Hiện toàn bộ các hãng vận chuyển vẫn đang dùng địa chỉ 3 cấp, chỉ 1 số ít hãng đã hỗ trợ 2 cấp.
  * Chưa có hãng nào bắt buộc dùng địa chỉ 2 cấp.
  * Sau khi hỗ trợ địa chỉ 2 cấp, các hãng vận chuyển vẫn hỗ trợ song song cả 2 loại 3 cấp và 2 cấp.
  * **Khuyến cáo** bạn vẫn nên dùng địa chỉ 3 cấp cho tới khi có các thông báo mới tiếp theo.

## Request

* Xem [common request params](/v3/readme.md#request-params).
* Xem [Postman sample](https://www.postman.com/nhanh-vn/pos-open-nhanh-vn/request/9fys38u/shipping-location?tab=body).

```curl
curl --location 'https://pos.open.nhanh.vn/v3.0/shipping/location?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json' \
--data '{
    "filters": {
        "locationVersion": "v1",
        "type": "DISTRICT",
        "parentId": 254
    }
}'
```

### Filters

| Key             | Type                          | Description                                                                                                                                                                                                               |
| --------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| locationVersion | string $$^{{\color{red}\*}}$$ | <p>v1: Địa chỉ 3 cấp (Tỉnh / Thành phố, Quận / Huyện, Phường / Xã)<br>v2: Địa chỉ 2 cấp (Tỉnh / Thành phố, Phường / Xã)</p>                                                                                               |
| type            | string $$^{{\color{red}\*}}$$ | CITY / DISTRICT / WARD (mặc định là CITY)                                                                                                                                                                                 |
| parentId        | int                           | <p>type = DISTRICT thì parentId = id của thành phố cần lấy ra danh sách quận huyện<br>type = WARD thì parentId = id của quận huyện (nếu là địa chỉ 3 cấp, nếu locationVersion=v2 thì là id của thành phố) cần lấy ra.</p> |

## Response

* Xem cấu trúc chung [tại đây](/v3/readme.md#response).

### Failed response

* Xem các mã lỗi chung [tại đây](/v3/readme.md#failed-response).

### Successful response

```json
{
    "code": 1,
    "data": [
        {
            "id": "(int) ID địa chỉ 1",
            "name": "Tên địa chỉ",
            "otherName": "Tên khác của địa chỉ"
        },
        {
            "id": "(int) ID địa chỉ 2",
            "name": "Tên địa chỉ"
        }
    ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.nhanh.vn/v3/shipping/location.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.