# Reverse v4

Source: https://maps.vietmap.vn/docs/vi/map-api/reverse-version/reverse-v4/

[![Reverse]][Reverse]
 [Reverse]: https://maps.vietmap.vn/docs/assets/reverse-jpg.webp
 
Reverse v4 đổi tọa độ (`lat`, `lng`) thành địa chỉ gần nhất kèm đơn vị hành chính. Response có thể theo định dạng hành chính cũ (3 cấp), mới (2 cấp sau sáp nhập) hoặc cả hai — chọn bằng `display_type`.

### Playground
!!! tip "Thử ngay trên Playground"
    Gọi thử Reverse v4 với dữ liệu thật, không cần viết code: **[Mở Playground](https://tools.vietmap.vn/playground/reverse)** · hoặc xem trên [Live Map](https://tools.vietmap.vn/live/)

!!! tip "Tích hợp AI Agent :sparkles: MỚI"
    Tải bộ tài liệu đã tối ưu cho AI agent (Search + Reverse): **<a href="/docs/assets/agents/search-geocoding.txt" download="search-geocoding.txt">Search & Geocoding Agent Doc</a>** · Schema máy đọc: **[OpenAPI 3.1](/docs/openapi.json)**

Hoặc dùng thử bằng [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).

### URL
```url
https://maps.vietmap.vn/api/reverse/v4?apikey={your-apikey}&lat={latitude}&lng={longitude}&display_type={display_type}
```

### Method
**GET**

### Chuyển từ v3 lên v4
- Đổi path `/api/reverse/v3` → `/api/reverse/v4`. `lat`, `lng` giữ nguyên.
- Muốn response giống hệt v3: gửi `display_type=2`. Không gửi hoặc `display_type=1` thì trả định dạng mới 2 cấp.
- Muốn có cả hai định dạng trong một response: `display_type=4`, `5` hoặc `6` — xem [Các giá trị display_type](#cac-gia-tri-display_type).
- Mỗi object trong response có thêm `data_old` và `data_new`; là `null` trừ khi `display_type` là 5 hoặc 6.

Tài liệu bản cũ: [Reverse v3](https://maps.vietmap.vn/docs/vi/map-api/reverse-version/reverse-ver3.0/).

### Tham số

|Tham số|Kiểu|Bắt buộc|Mô tả|Ví dụ|
|--- |--- |--- |--- |--- :|
|apikey|string|có|API key VIETMAP cấp cho tài khoản của bạn. Đăng ký tại [đây](https://maps.vietmap.vn/console-v2/register)||
|lat|number|có|Vĩ độ của vị trí cần tra. Dải hợp lệ ở Việt Nam khoảng `8`–`23`|10.759221|
|lng|number|có|Kinh độ của vị trí cần tra. Dải hợp lệ ở Việt Nam khoảng `102`–`110`|106.675901|
|display_type|number|không|Định dạng kết quả trả về. Chi tiết xem [Các giá trị display_type](#cac-gia-tri-display_type)|1|

#### Các giá trị display_type

| Giá trị | Tên                  | Mô tả                                                                                             |
|------:|------------------------|---------------------------------------------------------------------------------------------------------|
| 1     | Trả định dạng mới       | Định dạng hành chính mới sau sáp nhập (2 cấp: phường/xã, tỉnh/thành).                                                |
| 2     | Trả định dạng cũ       | Định dạng hành chính cũ (3 cấp: phường/xã, quận/huyện, tỉnh/thành).                                            |
| 4     | Hai phần tử (mới + cũ)        | Trả cả hai định dạng thành hai phần tử trong danh sách (một theo định dạng mới, một theo định dạng cũ).              |
| 5     | Mới, kèm cũ trong `data_old`     | Object ngoài cùng theo định dạng mới, bản định dạng cũ nằm trong `data_old`.                  |
| 6     | Cũ, kèm mới trong `data_new`     | Object ngoài cùng theo định dạng cũ, bản định dạng mới nằm trong `data_new`.                  |

### Ví dụ


**Đầu vào**
```ts
https://maps.vietmap.vn/api/reverse/v4?apikey={your-apikey}&lat=10.759221&lng=106.675901&display_type=6
```

[:material-play-circle: Chạy ví dụ này trên Playground](https://tools.vietmap.vn/playground/reverse?lat=10.759221&lng=106.675901&version=v4&display_type=6){ .md-button .md-button--primary }

**Phản hồi**

=== "Cũ, kèm mới trong `data_new`<br>`display_type=6`"

    ```json
    [
        {
            "lat": 10.759221,
            "lng": 106.675901,
            "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A075B1A116417D3DC9208103550F5D80930474606",
            "distance": 2.5788156956946213E-06,
            "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 656652,
                    "name": "4",
                    "prefix": "Phường",
                    "full_name": "Phường 4"
                },
                {
                    "type": 1,
                    "id": 1292,
                    "name": "5",
                    "prefix": "Quận",
                    "full_name": "Quận 5"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_old": null,
            "data_new": {
                "lat": 10.759221,
                "lng": 106.675901,
                "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A075B1A116417D3DC9208103550F5D80922545F1007",
                "distance": 2.5788156956946213E-06,
                "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
                "name": "197 Trần Phú",
                "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
                "boundaries": [
                    {
                        "type": 2,
                        "id": 18700,
                        "name": "Chợ Quán",
                        "prefix": "Phường",
                        "full_name": "Phường Chợ Quán"
                    },
                    {
                        "type": 0,
                        "id": 12,
                        "name": "Hồ Chí Minh",
                        "prefix": "Thành Phố",
                        "full_name": "Thành Phố Hồ Chí Minh"
                    }
                ],
                "categories": [],
                "entry_points": [],
                "data_old": null,
                "data_new": null
            }
        }
    ]
    ```

=== "Mới, kèm cũ trong `data_old`<br>`display_type=5`"

    ```json
    [
        {
            "lat": 10.759221,
            "lng": 106.675901,
            "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E7E570E4101",
            "distance": 0,
            "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 18700,
                    "name": "Chợ Quán",
                    "prefix": "Phường",
                    "full_name": "Phường Chợ Quán"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_old": {
                "lat": 10.759221,
                "lng": 106.675901,
                "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E6C441757",
                "distance": 0,
                "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
                "name": "197 Trần Phú",
                "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
                "boundaries": [
                    {
                        "type": 2,
                        "id": 656652,
                        "name": "4",
                        "prefix": "Phường",
                        "full_name": "Phường 4"
                    },
                    {
                        "type": 1,
                        "id": 1292,
                        "name": "5",
                        "prefix": "Quận",
                        "full_name": "Quận 5"
                    },
                    {
                        "type": 0,
                        "id": 12,
                        "name": "Hồ Chí Minh",
                        "prefix": "Thành Phố",
                        "full_name": "Thành Phố Hồ Chí Minh"
                    }
                ],
                "categories": [],
                "entry_points": [],
                "data_old": null,
                "data_new": null
            },
            "data_new": null
        }
    ]
    ```

=== "Hai phần tử (mới + cũ)<br>`display_type=4`"

    ```json
    [
        {
            "lat": 10.759221,
            "lng": 106.675901,
            "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E7E570E4101",
            "distance": 0,
            "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 18700,
                    "name": "Chợ Quán",
                    "prefix": "Phường",
                    "full_name": "Phường Chợ Quán"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_old": null,
            "data_new": null
        },
        {
            "lat": 10.759221,
            "lng": 106.675901,
            "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E6C441757",
            "distance": 0,
            "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 656652,
                    "name": "4",
                    "prefix": "Phường",
                    "full_name": "Phường 4"
                },
                {
                    "type": 1,
                    "id": 1292,
                    "name": "5",
                    "prefix": "Quận",
                    "full_name": "Quận 5"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_old": null,
            "data_new": null
        }
    ]
    ```

=== "Trả định dạng cũ<br>`display_type=2`"

    ```json
    [
        {
            "lat": 10.759221,
            "lng": 106.675901,
            "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A01321F09612807211E2B095E6C441757",
            "distance": 0,
            "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 656652,
                    "name": "4",
                    "prefix": "Phường",
                    "full_name": "Phường 4"
                },
                {
                    "type": 1,
                    "id": 1292,
                    "name": "5",
                    "prefix": "Quận",
                    "full_name": "Quận 5"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_old": null,
            "data_new": null
        }
    ]
    ```
=== "Trả định dạng mới<br>`display_type=1`"

    ```json
    [
        {
            "lat": 10.759221,
            "lng": 106.675901,
            "ref_id": "vm:ADDRESS:MM03541B04565B07001C5D035204030202005A1D535A075B1A116417D3DC9208103550F5D80922545F1007",
            "distance": 2.5788156956946213E-06,
            "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 18700,
                    "name": "Chợ Quán",
                    "prefix": "Phường",
                    "full_name": "Phường Chợ Quán"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_old": null,
            "data_new": null
        }
    ]
    ```

### Mô tả phản hồi
Reverse API trả về một `list` chứa thông tin địa điểm ứng với tọa độ bạn gửi lên.

| Trường   | Kiểu    | Mô tả                                                    |
| ----------- | ------- | -------------------------------------------------------------- |
| lat         | double  | Vĩ độ của địa điểm trả về |
| lng         | double  | Kinh độ của địa điểm trả về |
| ref_id      | string  | Mã tham chiếu của địa điểm                                      |
| distance    | double  | Khoảng cách từ địa điểm tới điểm bạn tra, tính bằng `km`    |
| address     | string  | Phần hành chính của địa chỉ: phường/xã, quận/huyện (chỉ ở định dạng cũ), tỉnh/thành. Số nhà, tên đường nằm ở `name`. |
| name        | string  | Tên địa điểm hoặc địa chỉ đường phố cụ thể                                                |
| display     | string  | Tên hiển thị chứa đầy đủ thông tin địa chỉ |
| boundaries  | array   | Đơn vị hành chính, xếp từ cấp nhỏ đến lớn theo `type` — xem bảng bên dưới |
| categories  | array   | Mảng các nhóm mà địa điểm thuộc về            |
| entry_points| array   | Mảng thông tin lối vào của địa điểm            |
| data_old    | object hoặc null | Cùng địa điểm theo định dạng cũ (3 cấp). Chỉ có giá trị khi `display_type=5`, còn lại `null`. |
| data_new    | object hoặc null | Cùng địa điểm theo định dạng mới (2 cấp). Chỉ có giá trị khi `display_type=6`, còn lại `null`. |

Với mảng `boundaries`:

| Trường con | Kiểu    | Mô tả                                    |
| ------------- | ------- | ---------------------------------------------- |
| type          | int     | Cấp hành chính (`0` = tỉnh/thành, `1` = quận/huyện, `2` = phường/xã) |
| id            | int     | Mã định danh của đơn vị hành chính             |
| name          | string  | Tên đơn vị hành chính, chưa kèm tiền tố                           |
| prefix        | string  | Tiền tố cấp hành chính. **Ví dụ:** `Phường`, `Quận`, `Thành Phố` |
| full_name     | string  | Tên đầy đủ gồm cả tiền tố. **Ví dụ:** `Phường Chợ Quán` |

Với mảng `entry_points`:

| Trường con | Kiểu    | Mô tả                                    |
| ------------- | ------- | ---------------------------------------------- |
| ref_id        | string  | Mã tham chiếu của địa điểm (POI)  |
| name          | string  | Tên địa điểm (POI)            |

Cần thông tin chi tiết của lối vào thì bạn dùng [VIETMAP Place API](https://maps.vietmap.vn/docs/vi/map-api/place-v4/)

Với object `data_old` và `data_new`:

| Trường con | Kiểu    | Mô tả                                                    |
| ------------- | ------- | -------------------------------------------------------------- |
| lat           | double  | Vĩ độ của địa điểm trả về |
| lng           | double  | Kinh độ của địa điểm trả về |
| ref_id        | string  | Mã tham chiếu của địa điểm                                  |
| distance      | double  | Khoảng cách từ địa điểm tới điểm bạn tra, tính bằng `km`|
| address       | string  | Địa chỉ đầy đủ                                                   |
| name          | string  | Tên địa điểm hoặc địa chỉ đường phố cụ thể                |
| display       | string  | Tên hiển thị chứa đầy đủ thông tin địa chỉ           |
| boundaries    | array   | Cấu trúc giống mảng `boundaries` ở trên                    |
| categories    | array   | Các nhóm mà địa điểm thuộc về                         |
| entry_points  | array   | Cấu trúc giống mảng `entry_points` ở trên                  |

### Mã lỗi

| HTTP | Ý nghĩa | Thân phản hồi |
| --- | --- | --- |
| `200` | Thành công | JSON như ví dụ ở trên |
| `401` | API key sai hoặc không tồn tại | Rỗng |
| `423` | Hết hạn mức, hoặc API này chưa được mở cho key | Văn bản, ví dụ `Your request is limited` |

Gặp `423` thì xem hạn mức còn lại ở [Theo dõi mức dùng](https://maps.vietmap.vn/docs/vi/map-api/console/monitor-api-key-usage/) và kiểm tra API đã được bật cho key ở [Quản lý API Key](https://maps.vietmap.vn/docs/vi/map-api/console/manage-api-key/).

!!! tip "Gọi thử với dữ liệu của bạn"
    Nhập địa chỉ, toạ độ hoặc tham số của bạn và xem kết quả ngay trên bản đồ, kèm lệnh cURL để sao chép: **[Mở Reverse v4 trên Playground](https://tools.vietmap.vn/playground/reverse)**