Bỏ qua

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

https://maps.vietmap.vn/api/maps/statics/tm

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"'
// 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.

Ví dụ bản đồ tĩnh

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.
Hotline
Tổng đài hỗ trợ
089.616.4567
Messenger Chat Facebook zalo Chat Zalo