Reverse v4
Reverse v4 API đổi tọa độ địa lý (vĩ độ và kinh độ) thành địa chỉ và thông tin địa điểm đọc được. Bạn dùng API này để thử và nắm khả năng của dịch vụ reverse geocoding trước khi tích hợp đầy đủ.
Playground¶
Bạn có thể thử Reverse v4 trên Live Map hoặc Playground.
Tích hợp AI Agent 
MỚI
Tải bộ tài liệu đã tối ưu cho AI agent (Search + Reverse): Search & Geocoding Agent Doc
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 (tóm tắt)¶
- Endpoint đổi từ
/api/reverse/v3sang/api/reverse/v4; thêmdisplay_typeđể chọn định dạng trả về (1=mới, 2=cũ, 4=danh sách hai phần tử, ⅚=lồng trong cùng object). - Request vẫn dùng
latvàlng, cách hoạt động tương thích như cũ. Điểm mới ở v4 là phản hồi theo mô hình hành chính 2 cấp sau sáp nhập. - Phản hồi v4 có thể kèm
data_old/data_newchứa định dạng còn lại. - Muốn payload tương thích v3 thì gọi v4 với
display_type=2; muốn so sánh song song hoặc gộp trong một phần tử thì dùngdisplay_type=4,5hoặc6.
Xem tài liệu bản cũ: Reverse v3.
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 | |
| 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 | 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 | Trả hai object | 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 | Trả cả Mới & Cũ | Object ngoài cùng theo định dạng mới, bản định dạng cũ nằm trong data_old. |
| 6 | Trả cả Cũ & Mới | 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
Phản hồi[
{
"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
}
}
]
[
{
"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
}
]
[
{
"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
}
]
[
{
"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
}
]
[
{
"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 vị trí cần tra. Dải hợp lệ ở Việt Nam khoảng 8–23 |
| lng | double | Kinh độ của vị trí cần tra. Dải hợp lệ ở Việt Nam khoảng 102–110 |
| 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 đủ gồm phường/xã, quận/huyện và tỉnh/thành |
| 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 | Mảng các đơn vị hành chính của địa chỉ, xếp từ cấp nhỏ đến cấp lớn (ward, district, city) |
| 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 | Object địa điểm theo định dạng hành chính cũ (3 cấp). Có ở các display_type dạng gộp (ví dụ 5), còn lại là null. |
| data_new | object hoặc null | Object địa điểm theo định dạng hành chính mới sau sáp nhập (2 cấp). Có ở các display_type dạng gộp (ví dụ 6), còn lại là 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 | Full name of the boundary (e.g., "Phường Chợ Quán" for ward) |
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
Với object data_old và data_new:
| Trường con | Kiểu | Mô tả |
|---|---|---|
| lat | double | Vĩ độ của vị trí cần tra. Dải hợp lệ ở Việt Nam khoảng 8–23 |
| lng | double | Kinh độ của vị trí cần tra. Dải hợp lệ ở Việt Nam khoảng 102–110 |
| 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 |
