Static Map API¶
The Static Map API generates static map images based on geographic coordinates and customizable parameters. This endpoint is commonly used for displaying location snapshots in route sharing features, location previews, or embedded map images without requiring interactive map components.
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) | Custom address text to display on the map. If omitted, the system will automatically perform reverse geocoding to retrieve the address. |
markerUrl |
string |
no | Default pin | URL pointing to a custom marker icon image. |
markerFile |
file |
no | - | Custom marker icon image file upload. Takes precedence over markerUrl if both are provided. |
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¶
The API returns a PNG image as binary data with the following headers:
- Content-Type:
image/png - Body: Binary image data (PNG format)
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 |
