Afficher une carte de la Tunisie sur un site, techniquement, se fait en une dizaine de minutes. Le code tient sur une page et on le trouve partout. Ce qui prend plus de temps, et ce qu'on regrette quand on l'a bâclé, ce sont les quelques décisions qui viennent avant : qui crée la clé et pour quels domaines, quel fond de carte afficher, et combien d'appels la carte va consommer une fois le site en ligne. Cet article les passe en revue dans l'ordre où elles se posent. Si vous voulez juste le code, le tutoriel pas à pas avec tout le code est sur dev.to, et le résultat tourne ici : examples.tmaps.tn/01-raster-leaflet.
D'abord, à quoi va servir la carte ?
La réponse change beaucoup de choses, y compris le budget. Une boutique de prêt-à-porter à Sfax qui veut une page « Nous trouver » a besoin d'une carte fixe, centrée sur une adresse, avec un marqueur. Une agence immobilière de La Marsa qui affiche une carte sur chaque annonce aura des centaines de cartes vues par jour, sur des quartiers différents. Une maison d'hôtes à Djerba veut surtout montrer la plage et la route depuis l'aéroport. Un site de livraison, lui, a besoin que le client place son adresse lui-même, ce qui fait entrer le géocodage dans la partie.
Et une municipalité ou un établissement public qui publie ses bureaux et ses horaires ? Ses priorités sont souvent la lisibilité et la langue, plus que les effets visuels.
Notez la réponse quelque part. Elle servira pour le choix du fond, et surtout pour estimer la consommation.
La clé API : qui la crée, et pour quels domaines
Tout passe par une clé créée sur la console TMaps. Elle commence par ak_ et elle sera visible dans le code source de votre page. C'est normal pour une carte affichée dans un navigateur, et ce n'est pas là que se joue la sécurité. Ce qui protège la clé, c'est la liste des domaines autorisés que vous lui associez : une page hébergée ailleurs qui tenterait de l'utiliser se verra refuser les tuiles.
Conseil d'organisation qui évite bien des soucis : faites créer la clé sur un compte de l'entreprise, pas sur l'adresse personnelle du développeur freelance qui monte le site. Le jour où il passe à autre chose, c'est vous qui devez pouvoir révoquer ou renouveler la clé.
Pour les domaines, deux règles reviennent sans cesse dans les demandes d'aide. Il n'y a pas de joker : *.monsite.tn ne fonctionne pas, il faut déclarer www.monsite.tn, boutique.monsite.tn et chaque sous-domaine un par un. Pensez aussi à localhost pour les tests en local, et au domaine de préproduction si votre agence web en utilise un. Enfin, la carte doit être servie en HTTPS. Une page en HTTP simple verra ses tuiles refusées, ce qui arrive encore sur des sites vitrines anciens.
Quel fond de carte et quelle bibliothèque
Pour une première carte, la combinaison la plus simple reste Leaflet avec les tuiles raster de TMaps. Leaflet est léger, gratuit, connu de tous les développeurs web, et une tuile raster est une simple image : aucune configuration de style, rien à comprendre en matière de rendu. Le zoom va de 0 à 18, c'est-à-dire de la vue d'ensemble du pays jusqu'au détail d'une ruelle de la médina.
L'essentiel de l'intégration tient d'ailleurs dans une ligne, l'adresse des tuiles :
https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=VOTRE_CLE
Si votre charte graphique compte, ou si vous voulez un mode sombre, regardez plutôt les tuiles vectorielles avec MapLibre GL. TMaps propose quatre styles (streets, dark, terrain et sunny) que vous pouvez comparer sur la démo des styles vectoriels. L'intégration demande un peu plus de travail, mais la carte se fond mieux dans un site soigné. Les arguments techniques des deux formats sont détaillés dans notre article tuiles vectorielles ou raster, et l'aperçu des fonds est sur la page cartes.
En pratique : une page « Nous trouver » sur un site WordPress, partez sur Leaflet et le raster. Une plateforme immobilière ou touristique qui fait de la carte un élément central de son interface, prenez le temps d'essayer le vectoriel.
Ce que coûte une carte, en appels
C'est une question qui revient souvent, et la réponse est plus concrète qu'on ne le croit. Chez TMaps, chaque tuile chargée compte pour un appel. Or une carte n'est pas une seule image, c'est une mosaïque de tuiles. Une carte raster de 1500 × 963 pixels, à son premier affichage, en charge environ 35. Ensuite, chaque déplacement ou changement de zoom en réclame de nouvelles.
Faisons le calcul pour la boutique de Sfax. Le plan Free inclut 50 000 appels par mois, et l'usage commercial y est autorisé. Avec une carte de cette taille, cela représente un peu plus de 1 400 premiers affichages par mois si personne ne touche à la carte, moins si les visiteurs zooment et se promènent. Pour une page « Nous trouver » consultée quelques dizaines de fois par jour, c'est confortable. Pour l'agence immobilière qui affiche une carte sur chaque annonce, le compte n'est plus le même : le plan Starter, à 79 TND par mois, monte à 200 000 appels. Le détail des formules est sur la page tarifs.
Trois réglages font baisser la note sans dégrader l'expérience. Une carte plus petite affiche moins de tuiles : un bloc de 400 pixels de haut dans une page suffit souvent. Ne chargez la carte que lorsqu'elle devient visible, ou au clic sur « Voir la carte », plutôt que dès l'ouverture de la page. Et limitez le zoom minimum : sur une page de contact, personne n'a besoin de voir la Méditerranée entière.
La mise en ligne, et les deux erreurs à reconnaître
Une fois la page en ligne, ouvrez-la depuis le vrai domaine, pas seulement en local. Si la carte reste grise, l'onglet Réseau des outils du navigateur (F12) vous dira tout de suite pourquoi. Un code 401 signifie que la clé est absente ou révoquée. Un 403 signifie que le domaine de la page ne figure pas dans la liste autorisée, ou que la page est servie en HTTP. Le plus souvent, c'est un sous-domaine oublié.
Autre piège, côté contenu cette fois : l'ordre des coordonnées. Leaflet attend la latitude avant la longitude. En Tunisie, la latitude se situe entre 30 et 37 environ et la longitude entre 7 et 11. Un marqueur qui atterrit en pleine mer, c'est presque toujours une inversion. Pour obtenir les coordonnées exactes d'une adresse, tapez-la dans la démo de recherche d'adresse, qui s'appuie sur le géocodage TMaps.
Et après la première carte
Une fois la carte en place, les besoins arrivent vite. Les questions d'ergonomie, l'affichage sur mobile, le regroupement de nombreux marqueurs et le style qui s'accorde au site sont traités dans ajouter une map de la Tunisie sur son site web. Pour un site marchand, l'étape suivante est souvent le formulaire d'adresse avec placement du point sur la carte : vous pouvez l'essayer sur la démo de formulaire de livraison et lire les cas concrets sur la page livraison et e-commerce.
Tout le code des démos est public, sous licence MIT, sur github.com/tmaps-tn/tmaps-snippets. La documentation couvre le reste, et si vous hésitez encore sur le fournisseur, la page alternative à Google Maps compare les approches.
