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