Skip to content

Static Map API

Returns a PNG map image centered on a coordinate, with a marker and an address label. Use it where an interactive map is not needed: share links, notifications, emails, order confirmations.

AI Agent Integration ✨ NEW

Download the optimized doc for AI agent integration: Map Display Agent Doc · Machine-readable schema: OpenAPI 3.1

URL

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

Method

POST

Parameters

All parameters should be sent as multipart/form-data in the request body.

Parameter Type Required Default Description
lat number yes - Latitude coordinate of the map center point.
lng number yes - Longitude coordinate of the map center point.
apikey string yes - Valid VietMap API Key for authentication.
zoom number no 15 Map zoom level ranging from 0 (world view) to 20 (building level).
size string no "600x400" Output image dimensions in pixels. Format: "WIDTHxHEIGHT" (e.g., "800x600").
address string no (Auto) Address text shown under the marker. If omitted, it is reverse-geocoded from lat/lng.
markerUrl string no Default pin URL pointing to a custom marker icon image.
markerFile file no - Marker icon uploaded as a file. Takes precedence over markerUrl if both are sent.

Example

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+. Call from your server so the API key stays private.
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, value): send each field as multipart/form-data, like 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)
Integrate the VIETMAP Static Map API into my project.

Sample request (from the example in the docs):
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

Requirements:
- Call the API from the server. Read the API key from the VIETMAP_API_KEY environment variable and send it as `apikey`; never hard-code it.
- Write one function that sends this request, checks the HTTP status and returns the PNG image as bytes.
- Read the docs below first. Use only parameters and response fields documented there.

Docs:
- https://maps.vietmap.vn/docs/map-api/static-map-version/static-map/index.txt
- https://maps.vietmap.vn/docs/assets/agents/map-display.txt

Response

On success the response body is the PNG image, with Content-Type: image/png.

Static Map Example

Response Status Codes

Code Description Content-Type
200 Success. Returns the map image as binary data. image/png
400 Bad Request: Missing or invalid parameters (e.g., lat, lng, size format). application/json
413 Payload Too Large: The markerFile exceeds the maximum allowed size (10MB limit). application/json
429 Rate Limit Exceeded: Too many requests within the allowed time window. application/json
500 Internal Server Error: An error occurred during map rendering process. application/json
  • Geocode v4 — coordinates for an address before you request the image.
  • Tile Map — an interactive map instead of an image.
Hotline
Tổng đài hỗ trợ
089.616.4567
Messenger Chat Facebook zalo Chat Zalo