Place v4

Place phiên bản dùng cho tìm kiếm địa chỉ sau sáp nhập¶

Place v4 trả về chi tiết một địa điểm (số nhà, đường, phường, tỉnh, lat/lng) theo ref_id lấy từ Autocomplete v4 hoặc Geocode v4. Đây là bước lấy tọa độ — hai API kia không trả lat/lng. Mỗi lượt gọi tính một transaction.

Playground¶

Thử ngay trên Playground

Place v4 chạy sau khi chọn một gợi ý: gõ địa chỉ vào Autocomplete, chọn kết quả, Playground gọi Place v4 bằng ref_id để lấy toạ độ. Mở Playground

Tích hợp AI Agent MỚI

Tải bộ tài liệu đã tối ưu cho AI agent: Search & Geocoding Agent Doc · Schema máy đọc: OpenAPI 3.1

Hoặc dùng thử bằng Postman.

URL¶

https://maps.vietmap.vn/api/place/v4?apikey={your-apikey}&refid={refid}

Method¶

GET

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
refid	string	có	Mã `refid` lấy nguyên xi từ kết quả Autocomplete hoặc Geocode. Giữ cả tiền tố (`auto:`, `geocode:`) — tiền tố quyết định định dạng phản hồi	auto:RAkPcicmZ3d-NQ...

Ví dụ¶

Thử luồng Autocomplete → Place trên Playground

Đầu vào:

 https://maps.vietmap.vn/api/place/v4?apikey={your-apikey}&refid=auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU

Phản hồi:

Lưu ý: Cấu trúc phản hồi tự động khớp với định dạng của API đã sinh ra refid. Nếu refid lấy từ phản hồi định dạng mới thì phản hồi cũng theo định dạng mới, và ngược lại.

{
    "display": "197 Đường Trần Phú,Phường Chợ Quán,Thành Phố Hồ Chí Minh",
    "name": "",
    "hs_num": "197",
    "street": "Đường Trần Phú",
    "address": "197 Đường Trần Phú",
    "city_id": 12,
    "city": "Thành Phố Hồ Chí Minh",
    "district_id": 0,
    "district": "",
    "ward_id": 18700,
    "ward": "Phường Chợ Quán",
    "lat": 10.759222947000069,
    "lng": 106.67590269100003
}

Mô tả phản hồi¶

Trường	Kiểu	Mô tả
display	string	Tên hiển thị chứa đầy đủ thông tin của địa chỉ
name	string	Tên POI. Rỗng nếu kết quả là địa chỉ số nhà, không phải POI
hs_num	string	Số nhà hoặc số tòa nhà
street	string	Tên đường
address	string	Số nhà + tên đường (`hs_num` + `street`)
city_id	int	Mã định danh của tỉnh/thành phố
city	string	Tên tỉnh/thành phố
district_id	int	Mã định danh của quận/huyện. Hiện luôn là `0` với định dạng hiển thị mới. Với định dạng cũ thì đây là mã quận/huyện.
district	string	Tên quận/huyện. Hiện luôn là chuỗi rỗng với định dạng hiển thị mới. Với định dạng cũ thì đây là tên quận/huyện.
ward_id	int	Mã định danh của phường/xã
ward	string	Tên phường/xã
lat	number	Vĩ độ của địa chỉ
lng	number	Kinh độ của địa chỉ

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 và kiểm tra API đã được bật cho key ở Quản lý API Key.

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ở Place v4 trên Playground