Cartes statiques

Générez une image PNG d'une carte centrée sur un point, avec markers, polylines et polygones — idéal pour emails, vignettes ou rapports PDF.

L’endpoint Static Maps renvoie une image PNG d’une carte TMaps, centrée sur un point ou calée sur une bbox, avec des overlays (markers, polylines, polygones). Parfait pour :

vignettes d’aperçu dans des emails ou exports PDF,
previews d’annonces immobilières / fiches produit,
rapports terrain géolocalisés.

Endpoint

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

Paramètres

Cadrage (un seul groupe au choix)

Param	Type	Requis	Défaut	Description
`center`	string	—	—	Centre de la carte `lat,lng`. À combiner avec `zoom`.
`zoom`	integer	—	—	Niveau de zoom (0 → 18). Requis avec `center`.
`bbox`	string	—	—	Boîte englobante `minLng,minLat,maxLng,maxLat`. La carte ajuste automatiquement le zoom pour englober la bbox.

Image

Param	Type	Requis	Défaut	Description
`size`	string	oui	—	Dimensions au format `WxH` en pixels (ex. `800x600`). Max 1280 × 1280.
`style`	string	—	`streets`	Style cartographique : `streets`, `dark`, `terrain`, `sunny`.
`format`	string	—	`png`	Format de retour. Seul `png` est supporté pour le moment.

Overlays (optionnels, peuvent être répétés)

Param	Type	Requis	Défaut	Description
`marker`	string	—	—	Un marker, format `lat,lng\|color\|label` (ex. `36.8,10.18\|red\|A`). Répétable.
`path`	string	—	—	Polyline encodée Google avec options de style — `weight:4\|color:0x0066ff\|enc:abc...`. Répétable.
`polygon`	string	—	—	Polygone GeoJSON encodé URL ou suite `lat,lng\|lat,lng\|...`. Répétable.

Auth

Param	Type	Requis	Défaut	Description
`api_key`	string	oui	—	Votre clé API TMaps.

Exemple — vignette d’annonce immobilière

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

Exemple — itinéraire avec polyline

// Récupère la polyline depuis l'API Direction
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();

Couleurs et labels des markers

Couleur : nom prédéfini (red, blue, green, orange, purple, black, white) ou code hex sans # (0xff5500).
Label : un caractère unique (lettre A-Z ou chiffre 0-9). Optionnel.

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

Cas d’usage

Emails transactionnels : confirmation de commande avec position du retrait.
Vignettes immobilières : preview de localisation dans les listings.
Exports PDF : rapports de tournée, fiches d’inspection.
Réseaux sociaux : génération automatique d’images Open Graph géolocalisées.

Cache CDN

Les images statiques sont identifiables par leur URL : mettez-les en cache via votre CDN (Cloudflare, BunnyCDN…) pour éviter de re-générer plusieurs fois la même tuile et réduire votre consommation TMaps.

Limites

Taille maximale : 1280 × 1280 pixels.
Maximum 20 markers, 5 paths et 5 polygones par image.
Format de retour : PNG uniquement (JPEG / WebP à venir).

Erreurs

Statut	Cause
`400`	`size` au-delà de la limite, paramètres de cadrage incohérents
`401`	`api_key` manquant ou révoqué
`403`	Domaine non autorisé

Voir Codes d’erreur pour la liste complète.