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¶
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¶
// 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.

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 |
Related APIs¶
- Geocode v4 — coordinates for an address before you request the image.
- Tile Map — an interactive map instead of an image.