Static maps

Generate a PNG image of a map centered on a point, with markers, polylines and polygons — perfect for emails, thumbnails or PDF reports.

The Static Maps endpoint returns a PNG image of a TMaps map, centered on a point or fitted to a bbox, with overlays (markers, polylines, polygons). Perfect for:

preview thumbnails in emails or PDF exports,
real estate / product page previews,
geolocated field reports.

Endpoint

GET https://api.tmaps.tn/maps/static?center=lat,lng&zoom=...&size=WxH&api_key=YOUR_API_KEY

Parameters

Framing (pick one group)

Param	Type	Requis	Défaut	Description
`center`	string	—	—	Map center `lat,lng`. Combine with `zoom`.
`zoom`	integer	—	—	Zoom level (0 → 18). Required with `center`.
`bbox`	string	—	—	Bounding box `minLng,minLat,maxLng,maxLat`. The map auto-adjusts zoom to fit the bbox.

Image

Param	Type	Requis	Défaut	Description
`size`	string	oui	—	Dimensions in `WxH` pixels (e.g. `800x600`). Max 1280 × 1280.
`style`	string	—	`streets`	Map style: `streets`, `dark`, `terrain`, `sunny`.
`format`	string	—	`png`	Response format. Only `png` is supported for now.

Overlays (optional, repeatable)

Param	Type	Requis	Défaut	Description
`marker`	string	—	—	A marker, formatted `lat,lng\|color\|label` (e.g. `36.8,10.18\|red\|A`). Repeatable.
`path`	string	—	—	Google encoded polyline with style options — `weight:4\|color:0x0066ff\|enc:abc...`. Repeatable.
`polygon`	string	—	—	URL-encoded GeoJSON polygon or `lat,lng\|lat,lng\|...` sequence. Repeatable.

Auth

Param	Type	Requis	Défaut	Description
`api_key`	string	oui	—	Your TMaps API key.

Example — real estate listing thumbnail

https://api.tmaps.tn/maps/static
?center=36.8528,10.3261
&zoom=15
&size=800x500
&style=streets
&marker=36.8528,10.3261|red|H
&api_key=YOUR_API_KEY

Example — route with polyline

// Pull the polyline from the Direction API
const direction = await fetch(
'https://api.tmaps.tn/routing/direction?from=36.8002,10.1815&to=36.8528,10.3261&api_key=YOUR_API_KEY'
).then((r) => r.json());

const url = new URL('https://api.tmaps.tn/maps/static');
url.searchParams.set('size', '1024x600');
url.searchParams.set('style', 'streets');
url.searchParams.append('marker', '36.8002,10.1815|blue|A');
url.searchParams.append('marker', '36.8528,10.3261|red|B');
url.searchParams.append('path', `weight:5|color:0x0066ff|enc:${direction.geometry}`);
url.searchParams.set('api_key', 'YOUR_API_KEY');

document.querySelector('#trip-thumbnail').src = url.toString();

Marker colors and labels

Color: predefined name (red, blue, green, orange, purple, black, white) or hex code without # (0xff5500).
Label: a single character (letter A-Z or digit 0-9). Optional.

&marker=36.8002,10.1815|red|A
&marker=36.8528,10.3261|0x0066ff|B
&marker=36.8094,10.1400|green

Use cases

Transactional emails: order confirmation with pickup location.
Real estate thumbnails: listing previews.
PDF exports: tour reports, inspection sheets.
Social media: auto-generated geolocated Open Graph images.

CDN cache

Static images are uniquely identified by their URL: cache them via your CDN (Cloudflare, BunnyCDN…) to avoid regenerating the same tile and reduce your TMaps usage.

Limits

Max size: 1280 × 1280 pixels.
Max 20 markers, 5 paths and 5 polygons per image.
Response format: PNG only (JPEG / WebP coming).

Errors

Status	Cause
`400`	`size` over the limit, inconsistent framing parameters
`401`	Missing or revoked `api_key`
`403`	Domain not authorized

See Error codes for the full list.