# Static Map API

Source: https://maps.vietmap.vn/docs/map-api/static-map-version/static-map/

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.

!!! tip "AI Agent Integration :sparkles: NEW"
    Download the optimized doc for AI agent integration: **<a href="/docs/assets/agents/map-display.txt" download="map-display.txt">Map Display Agent Doc</a>** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**

### 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

```bash
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`.

![Static Map Example](https://maps.vietmap.vn/docs/assets/static-map.webp)
## 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` |