API Bản đồ tĩnh¶
API Bản đồ tĩnh tạo ảnh bản đồ số từ tọa độ địa lý cùng các tham số tùy chỉnh, dùng dữ liệu bản đồ Việt Nam của VIETMAP. Endpoint này hay được dùng để hiển thị ảnh chụp vị trí trong tính năng chia sẻ tuyến đường, xem trước vị trí, hoặc nhúng ảnh bản đồ mà không cần tới thành phần bản đồ tương tác.
URL¶
Method¶
POST
Tham số¶
Tất cả tham số gửi ở phần thân request dưới dạng multipart/form-data.
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
lat |
number |
có | - | Vĩ độ của điểm giữa bản đồ. |
lng |
number |
có | - | Kinh độ của điểm giữa bản đồ. |
apikey |
string |
có | - | API Key VIETMAP hợp lệ để xác thực. |
zoom |
number |
không | 15 |
Mức zoom, từ 0 (nhìn cả thế giới) đến 20 (nhìn rõ từng tòa nhà). |
size |
string |
không | "600x400" |
Kích thước ảnh xuất ra, tính theo pixel. Định dạng: "RỘNGxCAO" (ví dụ "800x600"). |
address |
string |
không | (Tự động) | Chữ địa chỉ tự đặt để hiện trên bản đồ. Bỏ trống thì hệ thống tự reverse geocode để lấy địa chỉ. |
markerUrl |
string |
không | Ghim mặc định | URL trỏ tới ảnh biểu tượng marker riêng. |
markerFile |
file |
không | - | File ảnh marker tự tải lên. Nếu gửi cả hai thì file này được ưu tiên hơn markerUrl. |
Ví dụ¶
Request¶
curl --location 'https://maps.vietmap.vn/api/maps/statics/tm' \
--form 'lat="10.759157"' \
--form 'lng="106.675859"' \
--form 'apikey="YOUR_API_KEY_HERE"' \
--form 'zoom="17"' \
--form 'address="197 Trần Phú, phường Chợ Quán, thành phố Hồ Chí Minh"'
Phản hồi¶
API trả về ảnh PNG dạng dữ liệu nhị phân, kèm các header sau:
- Content-Type:
image/png - Body: Dữ liệu ảnh nhị phân (định dạng PNG)
Mã trạng thái phản hồi¶
| Mã | Mô tả | Content-Type |
|---|---|---|
| 200 | Thành công. Trả về ảnh bản đồ dạng nhị phân. | image/png |
| 400 | Bad Request: Thiếu tham số hoặc tham số sai (ví dụ lat, lng, sai định dạng size). |
application/json |
| 413 | Payload Too Large: File markerFile vượt quá dung lượng cho phép (tối đa 10MB). |
application/json |
| 429 | Rate Limit Exceeded: Gọi quá nhiều lượt trong khoảng thời gian cho phép. | application/json |
| 500 | Internal Server Error: Có lỗi xảy ra trong lúc dựng ảnh bản đồ. | application/json |
