API Bản đồ tĩnh¶
Trả về ảnh PNG bản đồ tại một tọa độ, có marker và nhãn địa chỉ. Dùng khi cần ảnh tĩnh (email, thông báo, link chia sẻ, preview) mà không muốn nhúng SDK bản đồ.
URL¶
Method¶
POST
Tham số¶
Tất cả tham số gửi trong body 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) | Địa chỉ hiển thị trên ảnh. Bỏ trống thì server tự reverse geocode từ lat/lng. |
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¶
Thành công thì body là ảnh PNG (nhị phân), Content-Type: image/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 |
