Pour afficher une carte de la Tunisie dans une application web, trois bibliothèques libres reviennent dans presque toutes les discussions : Leaflet, MapLibre GL et OpenLayers. Les deux premières sont souvent présentées comme les choix modernes et faciles, la troisième comme l'outil des géomaticiens. Ce raccourci n'est pas faux, mais il fait passer à côté de la vraie question : qu'est-ce que votre carte devra faire dans deux ans ? Cet article ne vous explique pas comment écrire le code ligne par ligne (le tutoriel pas à pas avec tout le code est sur dev.to). Il vous aide à savoir si OpenLayers est le bon choix pour votre projet, et ce que cela implique avec les tuiles TMaps.
Trois bibliothèques, trois philosophies
Leaflet mise sur la simplicité. Il affiche des tuiles, des marqueurs, des polygones, et il le fait très bien avec peu de code. Pour une page de contact, un annuaire d'agences ou une carte d'annonces, c'est souvent suffisant, et on en parle dans ajouter une map de la Tunisie sur son site web.
MapLibre GL est construit autour des tuiles vectorielles. La carte est dessinée par le navigateur, ce qui permet de changer de style à la volée, d'incliner la vue ou de passer en mode sombre. C'est la voie naturelle pour une application grand public soignée, une plateforme touristique ou un produit où la carte fait partie de l'identité visuelle. Les différences entre les deux formats de tuiles sont détaillées dans tuiles vectorielles ou raster.
OpenLayers vient d'un autre monde. Il a été pensé pour manipuler de la donnée géographique sérieuse : plusieurs systèmes de coordonnées, des services cartographiques normalisés, des formats variés, l'édition de géométries. Il est plus volumineux et plus verbeux que Leaflet, et sa documentation demande un peu de patience. En échange, il ne vous lâche pas le jour où le projet se complique.
Les situations où OpenLayers s'impose
Le premier signal, ce sont les projections. Le GPS, les téléphones et les API web parlent en WGS84, mais une partie des données publiques tunisiennes circule dans d'autres systèmes, à commencer par la projection Carthage utilisée par le cadastre et de nombreux topographes. Nous en parlons dans localisation GPS en Tunisie. Si votre application doit afficher des parcelles, des réseaux ou des limites fournies par un partenaire institutionnel, OpenLayers sait reprojeter ces couches à la volée, là où Leaflet demande des extensions et où MapLibre reste attaché au Web Mercator.
Le deuxième signal, ce sont les services WMS et WFS. Beaucoup d'administrations et de bureaux d'études publient leurs couches via un serveur cartographique comme GeoServer. Une direction régionale de l'agriculture qui veut superposer ses zones de production sur un fond de rues, un bureau d'études qui livre un tracé de réseau d'assainissement à une municipalité, une société de distribution qui croise ses compteurs avec le découpage par délégation : tout cela se branche naturellement dans OpenLayers.
Le troisième, c'est l'édition. Dessiner un périmètre, déplacer les sommets d'un polygone, accrocher un tracé sur une géométrie existante, valider une saisie terrain : OpenLayers a ces outils en standard. Pour un outil métier interne, ce n'est pas un luxe.
À l'inverse, si votre besoin se résume à « montrer où se trouve le magasin de Sousse », OpenLayers est une arme trop lourde. Prenez Leaflet et passez à autre chose.
Les tuiles TMaps dans OpenLayers
Bonne nouvelle, la partie TMaps est la plus simple du projet. Les tuiles raster suivent le schéma XYZ standard, avec un zoom de 0 à 18, ce qui correspond exactement à la source XYZ d'OpenLayers. L'intégration tient en quelques lignes :
new ol.source.XYZ({
url: 'https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=VOTRE_CLE',
maxZoom: 18,
});
La clé, qui commence par ak_, se crée sur la console TMaps, avec la liste des domaines autorisés à l'utiliser. Il n'y a pas de joker : chaque sous-domaine, y compris celui de l'intranet ou de la préproduction, doit être déclaré. Pour une administration qui héberge ses outils sur plusieurs adresses, faites la liste dès le départ. Le fond de rues lui-même couvre tout le pays, et la page couverture cartographique détaille ce qui est disponible région par région.
Une erreur revient chez presque tous ceux qui découvrent OpenLayers : la projection de la vue. Par défaut, la carte travaille en Web Mercator, alors que vos coordonnées GPS sont en longitude et latitude. Il faut les convertir, et respecter l'ordre longitude puis latitude. Sinon, Sousse se retrouve dans le golfe de Guinée, tout près du point de coordonnées zéro.
Un exemple qui parle aux équipes métier : la vue partageable
Dans un outil interne, une fonction rend des services disproportionnés par rapport à son coût : pouvoir copier l'adresse de la page et l'envoyer à un collègue pour qu'il voie exactement la même portion de carte. « Regarde le carrefour à l'entrée de Midoun » devient un lien, plutôt qu'une capture d'écran ou cinq minutes au téléphone.
Le principe est simple. La position de la carte (zoom, latitude, longitude) est écrite dans la fin de l'URL à chaque déplacement, et relue à l'ouverture de la page. Comme l'adresse est remplacée plutôt qu'empilée dans l'historique, le bouton Retour du navigateur continue de se comporter normalement. Un lien comme celui-ci ouvre la démo directement sur Djerba :
Pour un service de maintenance qui envoie des équipes sur le terrain, pour un bureau d'études qui échange avec son client, pour une cellule de suivi qui signale un incident, c'est le genre de détail qui fait adopter un outil. Et rien n'empêche d'aller plus loin en ajoutant dans l'URL la couche affichée ou l'objet sélectionné.
Les points à vérifier avant de vous lancer
Comptez la consommation. Chaque tuile chargée est un appel, et un outil métier ouvert toute la journée par une équipe consomme davantage qu'une page de contact. Les formules sont sur la page tarifs. Les tuiles étant envoyées avec des en-têtes de cache longs, un agent qui revient sur sa zone habituelle profite du cache de son navigateur.
Pensez à l'attribution. Gardez la mention TMaps visible sur la carte, comme dans la démo : OpenLayers l'affiche dans son contrôle d'attribution.
Et si la carte reste vide, l'onglet Réseau du navigateur donne la réponse : un code 401 désigne une clé absente ou révoquée, un 403 un domaine non autorisé ou une page servie en HTTP au lieu de HTTPS.
Pour essayer
La démo complète tourne sur examples.tmaps.tn/02-raster-openlayers, et toutes les autres sur examples.tmaps.tn. Le code source est public, sous licence MIT, sur github.com/tmaps-tn/tmaps-snippets. La documentation des tuiles raster donne tous les paramètres, et la page cartes montre les fonds disponibles. Si votre application doit aussi transformer des adresses en coordonnées, ou l'inverse, le géocodage TMaps s'ajoute sans changer de bibliothèque.
