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 đồ.
Tích hợp AI Agent MỚI
Tải bộ tài liệu đã tối ưu cho AI agent: Map Display Agent Doc · Schema máy đọc: OpenAPI 3.1
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¶
// Node.js 18+. Gọi từ server để không lộ API key.
import { writeFile } from "node:fs/promises";
const form = new FormData();
form.append("lat", "10.759157");
form.append("lng", "106.675859");
form.append("apikey", "YOUR_API_KEY");
form.append("zoom", "17");
form.append("address", "197 Trần Phú, phường Chợ Quán, thành phố Hồ Chí Minh");
const res = await fetch("https://maps.vietmap.vn/api/maps/statics/tm", {
method: "POST",
body: form,
});
await writeFile("static-map.png", Buffer.from(await res.arrayBuffer()));
import requests
# (None, giá trị): gửi từng trường dạng multipart/form-data, giống curl --form
fields = {
"lat": (None, "10.759157"),
"lng": (None, "106.675859"),
"apikey": (None, "YOUR_API_KEY"),
"zoom": (None, "17"),
"address": (None, "197 Trần Phú, phường Chợ Quán, thành phố Hồ Chí Minh"),
}
resp = requests.post("https://maps.vietmap.vn/api/maps/statics/tm", files=fields, timeout=30)
resp.raise_for_status()
with open("static-map.png", "wb") as f:
f.write(resp.content)
Tích hợp VIETMAP Static Map API vào dự án của tôi.
Request mẫu (theo ví dụ trong tài liệu):
POST https://maps.vietmap.vn/api/maps/statics/tm
Body (multipart/form-data):
lat=10.759157
lng=106.675859
zoom=17
address=197 Trần Phú, phường Chợ Quán, thành phố Hồ Chí Minh
Yêu cầu:
- Gọi API từ server. Đọc API key từ biến môi trường VIETMAP_API_KEY và truyền qua `apikey`, không ghi cứng trong code.
- Viết một hàm gửi request này, kiểm tra mã HTTP và trả về ảnh PNG dạng bytes.
- Đọc tài liệu bên dưới trước. Chỉ dùng tham số và trường dữ liệu có trong tài liệu.
Tài liệu:
- https://maps.vietmap.vn/docs/vi/map-api/static-map-version/static-map/index.txt
- https://maps.vietmap.vn/docs/assets/agents/map-display.txt
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 |
API liên quan¶
- Geocode v4 — lấy toạ độ của địa chỉ trước khi gọi ảnh.
- Tilemap — bản đồ tương tác thay cho ảnh tĩnh.