DEV Community: Tmaps Tunisia

Leaflet Tutorial: Add a Map of Tunisia with TMaps Tiles

Tmaps Tunisia — Sun, 08 Nov 2026 13:07:22 +0000

Delivery app, real estate site, store locator: sooner or later, a project in Tunisia needs a base map. And not just any map. People expect to see their neighbourhood, their street names and the road numbers they actually drive on.

In this post we'll put a map from TMaps, the maps API built for Tunisia, in Leaflet. It takes about ten lines of JavaScript. Then we'll go through the small details that tend to eat an afternoon: the API key, authorized domains, zoom limits and caching.

You can see the finished result here: examples.tmaps.tn/01-raster-leaflet

Or play with it right here, and fork it on CodePen to change the code:

What are raster tiles?

A raster tile is a 256 × 256 PNG image showing a small square of the map. Leaflet asks for the tiles it needs to fill the screen, using the standard XYZ scheme:

https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=YOUR_API_KEY

z is the zoom level (0 to 18), and x and y are the column and row of the tile at that zoom. You never compute them yourself: you give Leaflet the template and it fills in the blanks.

1. Get an API key

Create an account in the TMaps console.
Create an API key. It looks like ak_ followed by 32 hexadecimal characters.
In Authorized Domains, add every domain that will show the map, for example www.mysite.tn, app.mysite.tn, and localhost while you develop.

Two things that catch people out. Wildcards aren't accepted, so *.mysite.tn won't work and you have to list each subdomain. And requests must use HTTPS: plain HTTP gets a 403.

Yes, the key will be visible in your page source. That's normal for a map in the browser. The authorized domains list is what stops someone from copying it onto their own site.

2. The complete example

Save this as index.html, replace YOUR_API_KEY, and serve the folder over HTTP (npx serve . works fine):

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Map of Tunisia</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.css">
  <script src="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.js"></script>
  <style>
    html, body, #map { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const API_KEY = 'YOUR_API_KEY';

    const map = L.map('map').setView([36.8002, 10.1815], 12); // Tunis

    L.tileLayer(`https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=${API_KEY}`, {
      maxZoom: 18,
      attribution: '© <a href="https://www.tmaps.tn">TMaps</a>',
    }).addTo(map);
  </script>
</body>
</html>

That's really all there is to it. Leaflet takes care of panning, zooming, touch gestures and loading tiles.

Zoom in on the Medina and you'll get down to individual streets, with names in French and Arabic:

3. A few details worth getting right

Set `maxZoom: 18`

Tiles stop at zoom 18. If you keep Leaflet's default or go higher, anyone who zooms in past 18 ends up staring at an empty grey grid. Setting maxZoom: 18 keeps the zoom buttons in line with the data.

Say something when tiles fail

With a wrong key or a domain that isn't authorized, tiles fail quietly and you just get a grey map. A one-off tileerror listener saves a lot of head scratching:

L.tileLayer(url, { maxZoom: 18 })
  .once('tileerror', () => {
    console.error('TMaps tiles could not be loaded: check your API key and its authorized domains.');
  })
  .addTo(map);

In the network tab, a 401 means the key is missing or revoked, and a 403 means the domain isn't on the list.

Caching

Tiles come with long Cache-Control headers, so the browser keeps them between visits. On mobile, turn on your map library's disk cache and your users will thank you for the data they save.

High-density screens

There are no Retina (@2x) raster tiles yet. If the map has to stay crisp on high-density screens, or you want to change colours, rotate or tilt it, vector tiles are the better choice. That's the topic of the third post in this series.

The same tiles work everywhere

Because the URL follows the XYZ standard, you can drop it unchanged into OpenLayers, MapLibre GL, or a mobile SDK that supports XYZ layers (MapLibre Native, react-native-maps with UrlTile…). The next post does exactly that with OpenLayers, and adds a view you can share by URL (live demo).

Going further

About TMaps: Tunisia maps, geocoding and routing API
Live demos of every TMaps API: examples.tmaps.tn
Source code, MIT licensed: github.com/tmaps-tn/tmaps-snippets
Try the API without writing code in the TMaps Postman collection
Raster tiles documentation: tmaps.tn/documentation

Questions or feedback? Leave a comment below or write to support@tmaps.tn.

Autocomplétion d'adresse en Tunisie : arabe et arabizi

Tmaps Tunisia — Sun, 08 Nov 2026 13:07:00 +0000

Demandez à dix personnes à Tunis de taper la même adresse, et vous verrez passer trois alphabets :

en français : Rue de Marseille, Tunis
en arabe : نهج مرسيليا
en arabizi, c'est-à-dire le tunisien écrit en lettres latines avec des chiffres pour les sons que le français n'a pas : nahj marseille, zan9et el bacha, 9asr said

Un champ d'adresse qui ne comprend que la première façon d'écrire fait perdre des clients au moment de la commande. Dans cet article, on construit une autocomplétion avec l'API de géocodage TMaps qui gère les trois, et qui affiche correctement les résultats en arabe, de droite à gauche.

À tester en ligne : examples.tmaps.tn/04-geocoding-search. Passez la langue en arabe, ou tapez 9asr said.

Ou testez-la directement ici, et copiez-la sur CodePen (bouton Fork) pour modifier le code :

L'arabizi en 30 secondes

L'arabizi remplace certaines lettres arabes par des chiffres qui leur ressemblent :

Chiffre	Arabe	Son	Exemple	Orthographe française habituelle
`3`	ع	« aïn »	`3in`	Ain
`5`	خ	kh	`5ayreddine`	Khayreddine
`7`	ح	h aspiré	`7ammamet`	Hammamet
`9`	ق	q	`9asr said`	Ksar Said

Ajoutez les mots du dialecte pour les types de voies, nahj (rue), zan9a (impasse), chare3 (avenue) et 7ay (cité), et vous avez la façon dont beaucoup de gens écrivent vraiment leur adresse.

Étape 1 : une autocomplétion de base solide

Au fond, l'autocomplétion appelle GET /geocoding/forward pendant que l'utilisateur tape. Trois détails font toute la différence :

let timer;
let controller;

input.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(search, 300); // on attend que l'utilisateur fasse une pause
});

async function geocode(q, signal) {
  const url = new URL('https://api.tmaps.tn/geocoding/forward');
  url.search = new URLSearchParams({
    q,
    country: 'TN',                 // Tunisie uniquement
    limit: 5,
    lang: languageSelect.value,    // fr, en ou ar
    proximity: '36.8065,10.1815',  // favorise les résultats proches de l'utilisateur
    api_key: API_KEY,
  });
  const res = await fetch(url, { signal });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) throw new Error(`${res.status}: ${data.error ?? res.statusText}`);
  return data.results;
}

Un délai de 300 ms avant d'envoyer, pour faire une requête quand l'utilisateur s'arrête de taper, et pas une par lettre.
Un AbortController : quand une nouvelle recherche démarre, on annule la précédente. Sinon, une vieille réponse un peu lente peut arriver après une plus récente et l'écraser.
Le paramètre proximity : il y a une Rue de Marseille dans beaucoup de villes tunisiennes, et favoriser la position de l'utilisateur (ou le centre de la carte) fait remonter la bonne.

Chaque résultat contient le point dans geometry.location (lat, lng), l'adresse complète dans formatted, un score confidence, et components avec la commune, la délégation et le gouvernorat.

Étape 2 : des résultats en arabe, de droite à gauche

Avec lang=ar, toute l'adresse revient en arabe :

{
  "formatted": "نهج مرسيليا, حبيب ثامر, باب بحر, تونس, تونس",
  "type": "street",
  "confidence": 0.8
}

L'arabe doit s'afficher de droite à gauche. Comme une liste de suggestions mélange souvent les écritures (une adresse en arabe à côté d'un nom de commune en français, un numéro de route en chiffres latins…), ne fixez pas le sens d'écriture en dur. Laissez le navigateur décider pour chaque élément :

const li = document.createElement('li');
li.dir = 'auto'; // le premier caractère fort décide : arabe = droite à gauche, latin = gauche à droite
li.textContent = result.formatted;

<input id="address" type="search" dir="auto">

Mettre aussi dir="auto" sur le champ de saisie fait basculer le curseur et l'alignement dès qu'on commence à taper en arabe. Sans ça, la ponctuation et les chiffres se retrouvent du mauvais côté.

Étape 3 : ce que l'API comprend déjà

Nous avons testé de vraies requêtes tunisiennes sur l'API (lang=fr, country=TN). Voici le premier résultat pour chacune :

Requête	Premier résultat
`نهج مرسيليا`	✅ Rue de Marseille
`nahj marseille`	✅ Rue de Marseille, Tunis
`9asr said`	✅ Ksar Said, Le Bardo
`7ammamet`	✅ Hammamet
`5ayreddine`	✅ Rue Khayreddine
`3in zaghouan`	❌ aucun résultat
`zan9et el bacha`	⚠️ Khaireddine Pacha (pas une impasse)

L'arabe, nahj et les chiffres 7, 9 et 5 fonctionnent donc déjà. Le chiffre 3 et certains mots du dialecte ont besoin d'un coup de pouce, qu'on peut donner directement dans le navigateur.

Étape 4 : normaliser l'arabizi côté navigateur

Une petite fonction réécrit les mots du dialecte et les chiffres de l'arabizi dans l'orthographe utilisée dans les adresses :

// Mots du dialecte tunisien et chiffres de l'arabizi, réécrits comme dans les adresses
const DIALECT = {
  nahj: 'rue', nhej: 'rue', zan9a: 'impasse', zan9et: 'impasse', zanket: 'impasse',
  chare3: 'avenue', chara3: 'avenue', hay: 'cité', '7ay': 'cité',
};
const ARABIZI = { 3: 'a', 5: 'kh', 7: 'h', 9: 'k' };

function normalizeTunisian(text) {
  return text.toLowerCase().split(/\s+/).map((word) => {
    if (DIALECT[word]) return DIALECT[word];
    // On ne touche ni aux nombres (4014) ni aux routes (rn9, c27)
    if (!/[a-z]/.test(word) || /^[a-z]{1,2}\d+$/.test(word)) return word;
    return word.replace(/3a/g, 'a').replace(/[3579]/g, (digit) => ARABIZI[digit]);
  }).join(' ');
}

"3in zaghouan"     → "ain zaghouan"
"nahj 5ayreddine"  → "rue khayreddine"
"zan9et el bacha"  → "impasse el bacha"
"chare3 bourguiba" → "avenue bourguiba"
"Rue 4014"         → "rue 4014"     (inchangé)
"RN9"              → "rn9"          (inchangé)
"نهج مرسيليا"       → "نهج مرسيليا"  (inchangé)

Ne sautez pas les deux protections. Les adresses tunisiennes sont pleines de numéros (Rue 4014) et de codes de routes (RN9, C27), et réécrire ces chiffres casserait des recherches qui marchaient très bien.

Étape 5 : chercher les deux versions en parallèle

La normalisation peut aussi faire moins bien : 9asr said fonctionne déjà tel quel. Plutôt que de remplacer ce que l'utilisateur a tapé, on cherche donc les deux versions et on fusionne les résultats :

async function search() {
  const q = input.value.trim();
  if (q.length < 3) return;

  controller?.abort();
  controller = new AbortController();

  const normalized = normalizeTunisian(q);
  const queries = normalized === q.toLowerCase() ? [q] : [q, normalized];

  const lists = await Promise.all(queries.map((text) => geocode(text, controller.signal)));

  // Résultats normalisés d'abord, puis ceux de la saisie brute, sans doublons
  const seen = new Set();
  const results = lists.reverse().flat()
    .filter((r) => !seen.has(r.formatted) && seen.add(r.formatted))
    .slice(0, 5);

  render(results);
}

Un texte en français ou en arabe ressort de normalizeTunisian sans changement : il ne coûte donc qu'une seule requête. Seule une saisie en arabizi ou en dialecte déclenche la deuxième.

La différence se voit tout de suite : 3in zaghouan passe de zéro résultat à la Rue Ain Zaghouane et aux villages « Ain » autour de Zaghouan.

Et 9asr said tombe bien sur Ksar Said, au Bardo :

Étape 6 : ne pas faire confiance à tous les résultats

Pour une adresse de livraison, une mauvaise adresse coûte plus cher que pas d'adresse du tout. Le score confidence aide à décider :

à partir de 0,85, enregistrez les coordonnées ;
en dessous, gardez la suggestion mais demandez au client de vérifier le pin sur la carte.

La démo du formulaire de commande montre tout le parcours : le client choisit une suggestion, la commune, la délégation et le gouvernorat se remplissent tout seuls, puis il peut déplacer le pin, et l'adresse est affinée par géocodage inverse.

Les limites actuelles

Pour être transparents sur ce que cette approche ne règle pas encore :

Certains noms de ville tapés en arabe peuvent renvoyer un autre lieu au nom proche. Si vos utilisateurs tapent les villes en arabe, gardez proximity et affichez la commune et le gouvernorat dans chaque suggestion, pour qu'ils puissent choisir le bon lieu.
Quand plusieurs lieux portent le même nom dans des régions différentes (il y a plus d'une El Aouina), le classement dépend beaucoup de proximity. Envoyez la vraie position de l'utilisateur dès que vous l'avez.

En résumé

Un délai avant d'envoyer, l'annulation des requêtes dépassées, et proximity pour orienter les résultats.
lang=ar pour des résultats en arabe, et dir="auto" partout où vous les affichez.
Normaliser le dialecte et l'arabizi dans le navigateur, sans toucher aux numéros ni aux routes.
Chercher en parallèle la saisie brute et la version normalisée, puis fusionner sans doublons.
N'enregistrer les coordonnées que si confidence est suffisant.

Pour aller plus loin

TMaps pour la livraison et l'e-commerce : www.tmaps.tn
La démo en ligne : examples.tmaps.tn/04-geocoding-search
La démo du formulaire de commande : examples.tmaps.tn/12-checkout-address-form
Le code source, sous licence MIT : github.com/tmaps-tn/tmaps-snippets
La collection Postman : postman.com/tmaps-tn/tmaps-api
La documentation du géocodage : tmaps.tn/documentation

Et vous, comment écrivez-vous vos adresses ? Partagez votre requête tunisienne la plus compliquée en commentaire, ou écrivez-nous à support@tmott13

Carte de la Tunisie avec OpenLayers et les tuiles TMaps

Tmaps Tunisia — Fri, 06 Nov 2026 10:38:48 +0000

Dès qu'une carte doit faire plus qu'afficher quelques marqueurs (projections, couches WMS, édition de formes, vrai travail SIG), c'est souvent vers OpenLayers qu'on se tourne. Dans cet article, on branche les tuiles raster de TMaps dans OpenLayers, on évite le piège classique de la projection, et on ajoute une petite fonction que les utilisateurs adorent : une URL qui se souvient de l'endroit où l'on se trouve sur la carte.

La démo en ligne : examples.tmaps.tn/02-raster-openlayers

Ou testez-la directement ici, et copiez-la sur CodePen (bouton Fork) pour modifier le code :

Avant de commencer

Il vous faut une clé API créée sur la console TMaps, avec votre domaine (et localhost pour le développement) dans ses Authorized Domains. Les jokers ne sont pas acceptés, donc ajoutez chaque sous-domaine un par un.

1. La couche de tuiles

Les tuiles raster de TMaps suivent le schéma XYZ. La source est donc un simple ol.source.XYZ :

const source = new ol.source.XYZ({
  url: 'https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=VOTRE_CLE_API',
  maxZoom: 18,
  attributions: '© <a href="https://www.tmaps.tn">TMaps</a>',
});

Chaque tuile est une image PNG de 256 × 256 pixels, et le zoom va de 0 à 18.

2. La projection, le piège classique

C'est l'erreur qui envoie les marqueurs au milieu de la mer. Par défaut, OpenLayers travaille en Web Mercator (EPSG:3857), alors que les coordonnées GPS sont en longitude et latitude (EPSG:4326). Il faut donc les convertir avec ol.proj.fromLonLat, en faisant attention à l'ordre : la longitude vient en premier.

const map = new ol.Map({
  target: 'map',
  layers: [new ol.layer.Tile({ source })],
  view: new ol.View({
    center: ol.proj.fromLonLat([10.637, 35.828]), // Sousse, en [lng, lat]
    zoom: 14,
    maxZoom: 18,
  }),
});

3. Garder la vue dans l'URL

Un jour ou l'autre, quelqu'un voudra envoyer « cet endroit précis » à un collègue. Le plus simple est de garder la vue dans le hash de l'URL, sous la forme #zoom,lat,lng : on le met à jour à chaque déplacement de la carte, et on le relit au chargement de la page.

À la lecture, avec Tunis par défaut :

const [zoom = 12, lat = 36.8002, lng = 10.1815] = location.hash
  .slice(1)
  .split(',')
  .filter(Boolean)
  .map(Number);

À l'écriture, après chaque déplacement. history.replaceState change l'adresse sans ajouter une entrée dans l'historique à chaque glissement, donc le bouton Retour continue de fonctionner normalement :

map.on('moveend', () => {
  const view = map.getView();
  const [lon, la] = ol.proj.toLonLat(view.getCenter());
  history.replaceState(null, '', `#${view.getZoom().toFixed(2)},${la.toFixed(6)},${lon.toFixed(6)}`);
});

Avec ça, un lien comme celui-ci ouvre directement la carte sur Djerba :

https://examples.tmaps.tn/02-raster-openlayers/#11,33.80,10.88

4. L'exemple complet

<!doctype html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Carte de la Tunisie à partager</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10.4.0/ol.css">
  <script src="https://cdn.jsdelivr.net/npm/ol@10.4.0/dist/ol.js"></script>
  <style>
    html, body, #map { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const API_KEY = 'VOTRE_CLE_API';

    // Vue initiale lue dans l'URL : #zoom,lat,lng
    const [zoom = 12, lat = 36.8002, lng = 10.1815] = location.hash
      .slice(1).split(',').filter(Boolean).map(Number);

    const source = new ol.source.XYZ({
      url: `https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=${API_KEY}`,
      maxZoom: 18,
      attributions: '© <a href="https://www.tmaps.tn">TMaps</a>',
    });
    source.once('tileloaderror', () =>
      console.error('Tuiles TMaps indisponibles : vérifiez votre clé API et ses domaines autorisés.'));

    const map = new ol.Map({
      target: 'map',
      layers: [new ol.layer.Tile({ source })],
      view: new ol.View({ center: ol.proj.fromLonLat([lng, lat]), zoom, maxZoom: 18 }),
    });

    // Partage de la vue actuelle via l'URL
    map.on('moveend', () => {
      const view = map.getView();
      const [lon, la] = ol.proj.toLonLat(view.getCenter());
      history.replaceState(null, '', `#${view.getZoom().toFixed(2)},${la.toFixed(6)},${lon.toFixed(6)}`);
    });
  </script>
</body>
</html>

Quelques conseils

Si la carte reste vide, ouvrez l'onglet Réseau du navigateur. Un 401 signifie que la clé est absente ou révoquée. Un 403 signifie que le domaine de la page n'est pas dans les domaines autorisés de la clé, ou que la requête est partie en HTTP simple.

Les tuiles sont envoyées avec des en-têtes de cache longs : revenir sur la carte est donc très rapide.

Vous utilisez un bundler ? Le même code fonctionne avec import { Map, View } from 'ol', TileLayer depuis ol/layer/Tile, XYZ depuis ol/source/XYZ et fromLonLat depuis ol/proj.

Pour aller plus loin

TMaps, une alternative à Google Maps pour la Tunisie : www.tmaps.tn
Toutes les démos en ligne : examples.tmaps.tn
Le code source, sous licence MIT : github.com/tmaps-tn/tmaps-snippets
La collection Postman : postman.com/tmaps-tn/tmaps-api
La documentation des tuiles raster : tmaps.tn/documentation

Dans le prochain article : les tuiles vectorielles avec MapLibre GL, quatre styles, le mode sombre et une vue en 3D.

OpenLayers XYZ Tiles with TMaps: Shareable Map of Tunisia

Tmaps Tunisia — Fri, 06 Nov 2026 10:38:01 +0000

When a map has to do more than show a few markers (projections, WMS layers, editing shapes, real GIS work), OpenLayers is usually the library people reach for. In this post we'll plug TMaps raster tiles into it, sidestep the classic projection trap, and add a small feature users really like: a URL that remembers where you are on the map.

Live demo: examples.tmaps.tn/02-raster-openlayers

Or play with it right here, and fork it on CodePen to change the code:

Before you start

You'll need a TMaps API key from the TMaps console, with your domain (and localhost for development) in its Authorized Domains. Wildcards don't work there, so list each subdomain. The first post of this series walks through this step if you haven't done it yet.

1. The tile layer

TMaps raster tiles follow the XYZ scheme, so the source is a plain ol.source.XYZ:

const source = new ol.source.XYZ({
  url: 'https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=YOUR_API_KEY',
  maxZoom: 18,
  attributions: '© <a href="https://www.tmaps.tn">TMaps</a>',
});

Each tile is a 256 × 256 PNG, and zoom goes from 0 to 18.

2. Get the projection right

This is the one that sends markers into the sea. By default OpenLayers works in Web Mercator (EPSG:3857), while GPS coordinates are longitude and latitude in EPSG:4326. Convert them with ol.proj.fromLonLat, and watch the order, because longitude comes first:

const map = new ol.Map({
  target: 'map',
  layers: [new ol.layer.Tile({ source })],
  view: new ol.View({
    center: ol.proj.fromLonLat([10.637, 35.828]), // Sousse, as [lng, lat]
    zoom: 14,
    maxZoom: 18,
  }),
});

3. Keep the view in the URL

Sooner or later someone wants to send "this exact spot" to a colleague. The simplest way is to keep the view in the URL hash as #zoom,lat,lng: update it whenever the map moves, and read it back when the page loads.

Reading it on load, with Tunis as the fallback:

const [zoom = 12, lat = 36.8002, lng = 10.1815] = location.hash
  .slice(1)
  .split(',')
  .filter(Boolean)
  .map(Number);

Writing it after every move. history.replaceState changes the address bar without adding one history entry per drag, so the back button still behaves:

map.on('moveend', () => {
  const view = map.getView();
  const [lon, la] = ol.proj.toLonLat(view.getCenter());
  history.replaceState(null, '', `#${view.getZoom().toFixed(2)},${la.toFixed(6)},${lon.toFixed(6)}`);
});

With that in place, a link like this one opens straight on Djerba:

https://examples.tmaps.tn/02-raster-openlayers/#11,33.80,10.88

4. The complete example

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Shareable map of Tunisia</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10.4.0/ol.css">
  <script src="https://cdn.jsdelivr.net/npm/ol@10.4.0/dist/ol.js"></script>
  <style>
    html, body, #map { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const API_KEY = 'YOUR_API_KEY';

    // Initial view from the URL: #zoom,lat,lng
    const [zoom = 12, lat = 36.8002, lng = 10.1815] = location.hash
      .slice(1).split(',').filter(Boolean).map(Number);

    const source = new ol.source.XYZ({
      url: `https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=${API_KEY}`,
      maxZoom: 18,
      attributions: '© <a href="https://www.tmaps.tn">TMaps</a>',
    });
    source.once('tileloaderror', () =>
      console.error('TMaps tiles could not be loaded: check your API key and its authorized domains.'));

    const map = new ol.Map({
      target: 'map',
      layers: [new ol.layer.Tile({ source })],
      view: new ol.View({ center: ol.proj.fromLonLat([lng, lat]), zoom, maxZoom: 18 }),
    });

    // Share the current view through the URL
    map.on('moveend', () => {
      const view = map.getView();
      const [lon, la] = ol.proj.toLonLat(view.getCenter());
      history.replaceState(null, '', `#${view.getZoom().toFixed(2)},${la.toFixed(6)},${lon.toFixed(6)}`);
    });
  </script>
</body>
</html>

A few tips

If the map stays empty, open the network tab. A 401 means the key is missing or revoked. A 403 means the page's domain isn't in the key's authorized domains, or the request went out over plain HTTP.

Tiles are sent with long cache headers, so coming back to the map is fast.

Using a bundler? The same code works with import { Map, View } from 'ol', TileLayer from ol/layer/Tile, XYZ from ol/source/XYZ and fromLonLat from ol/proj.

Going further

TMaps, a Google Maps alternative for Tunisia: www.tmaps.tn
Live demos: examples.tmaps.tn
Source code, MIT licensed: github.com/tmaps-tn/tmaps-snippets
Postman collection: postman.com/tmaps-tn/tmaps-api
Raster tiles documentation: tmaps.tn/documentation

Next up in the series: vector tiles with MapLibre GL, with four styles, dark mode and a 3D tilt.

Carte de la Tunisie sur votre site web en 10 minutes

Tmaps Tunisia — Mon, 02 Nov 2026 11:07:11 +0000

Vous avez une boutique, un restaurant, une agence ou un cabinet, et vous aimeriez que vos clients voient où vous trouver directement sur votre site ? Ou vous développez une application qui a besoin d'une carte de la Tunisie à jour, avec les vrais noms de rues ?

Dans ce tutoriel, on part d'une page vide pour arriver, en une dizaine de minutes, à une carte interactive avec un marqueur sur votre adresse. Pas de framework, rien à installer : un seul fichier HTML suffit.

Le résultat est visible ici : examples.tmaps.tn/01-raster-leaflet

Ou testez-la directement ici, et copiez-la sur CodePen (bouton Fork) pour modifier le code :

Les outils

On utilise Leaflet, la bibliothèque de cartes JavaScript la plus répandue, légère et gratuite. Pour le fond de carte, on prend TMaps : il couvre le monde entier, avec beaucoup plus de détails sur la Tunisie (rues, quartiers, routes nationales et régionales).

De 0 à 3 minutes : créer une clé API

Créez un compte sur la console TMaps.
Dans API Keys, cliquez sur Create API Key. Vous obtenez une clé qui commence par ak_.
Dans Authorized Domains, ajoutez les domaines où la carte va s'afficher, par exemple www.monsite.tn, et localhost pour vos tests sur votre ordinateur.

Deux pièges à éviter. Les jokers ne sont pas acceptés : *.monsite.tn ne marche pas, il faut ajouter chaque sous-domaine (www.monsite.tn, boutique.monsite.tn…). Et les requêtes doivent passer en HTTPS, le HTTP simple est refusé.

Votre clé sera visible dans le code de la page. Pas d'inquiétude, c'est normal pour une carte affichée dans le navigateur : c'est la liste des domaines autorisés qui empêche quelqu'un d'autre de l'utiliser sur son propre site.

De 3 à 7 minutes : la carte

Créez un fichier index.html, collez ce code et remplacez VOTRE_CLE_API par votre clé :

<!doctype html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Où nous trouver</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.css">
  <script src="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.js"></script>
  <style>
    #map { height: 450px; border-radius: 12px; }
  </style>
</head>
<body>
  <h1>Où nous trouver</h1>
  <div id="map"></div>

  <script>
    const API_KEY = 'VOTRE_CLE_API';

    // Centre de la carte [latitude, longitude] et niveau de zoom
    const map = L.map('map').setView([36.8002, 10.1815], 15);

    L.tileLayer(`https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=${API_KEY}`, {
      maxZoom: 18,
      attribution: '© <a href="https://www.tmaps.tn">TMaps</a>',
    }).addTo(map);
  </script>
</body>
</html>

Pour tester, ouvrez la page avec un petit serveur local plutôt qu'en double-cliquant sur le fichier. Dans le dossier du fichier :

npx serve .
# ou
python3 -m http.server 8000

Allez ensuite sur http://localhost:3000 (ou :8000). La carte s'affiche, et vous pouvez zoomer jusqu'au niveau de la rue :

De 7 à 9 minutes : un marqueur sur votre adresse

Ajoutez ces quelques lignes juste après .addTo(map); :

L.marker([36.8002, 10.1815])
  .addTo(map)
  .bindPopup('<b>Ma Boutique</b><br>Avenue Habib Bourguiba, Tunis')
  .openPopup();

Pour connaître les coordonnées de votre adresse, le plus simple est de la taper dans la démo de recherche d'adresse TMaps, qui affiche la latitude et la longitude. Un clic droit sur n'importe quelle carte en ligne fait aussi l'affaire.

Attention à l'ordre : Leaflet attend [latitude, longitude]. En Tunisie, la latitude tourne autour de 30 à 37 et la longitude autour de 7 à 11. Si votre marqueur atterrit dans la mer, vous avez très probablement inversé les deux.

À 10 minutes : la mise en ligne

Envoyez index.html sur votre hébergement, ou copiez le bloc <div id="map"> et les deux <script> dans une page existante (WordPress, site vitrine…). Vérifiez juste que le domaine du site figure bien dans les Authorized Domains de votre clé.

Si la carte reste grise, ouvrez la console du navigateur (F12) et regardez l'onglet Réseau. Un code 401 veut dire que la clé est absente ou révoquée. Un 403 veut dire que le domaine n'est pas autorisé, ou que la page est servie en HTTP au lieu de HTTPS.

Pour aller plus loin

TMaps : API de cartographie et de géocodage pour la Tunisie, une alternative à Google Maps
Une carte vectorielle avec mode sombre, grâce à MapLibre GL : la démo
La recherche d'adresse (géocodage) : la démo
Un formulaire de livraison avec saisie d'adresse et pin sur la carte : la démo
Tout le code source, sous licence MIT : github.com/tmaps-tn/tmaps-snippets
La documentation : tmaps.tn/documentation

Une question ? Laissez un commentaire ou écrivez-nous à support@tmaps.tn.

Carte vectorielle de la Tunisie avec MapLibre et TMaps

Tmaps Tunisia — Mon, 02 Nov 2026 11:06:25 +0000

Les tuiles raster sont des images de la carte. C'est simple et ça marche partout, mais on ne peut pas y toucher. Les tuiles vectorielles, elles, envoient les données de la carte (routes, bâtiments, noms de lieux) et laissent le navigateur la dessiner. Résultat : une carte nette sur tous les écrans, un zoom fluide, la possibilité de la faire pivoter ou de l'incliner, et un changement de style instantané.

Dans cet article, on utilise les tuiles vectorielles de TMaps avec MapLibre GL JS, la bibliothèque open source de cartes en WebGL, et on construit un petit sélecteur de styles.

La démo en ligne : examples.tmaps.tn/03-vector-maplibre-styles

Ou testez-la directement ici, et copiez-la sur CodePen (bouton Fork) pour modifier le code :

Comment fonctionnent les tuiles vectorielles TMaps

Vous ne demandez pas les tuiles vous-même. Chaque style est un document JSON qui suit la Mapbox Style Specification :

https://tiles.tmaps.tn/v-tile/{style}.json?api_key=VOTRE_CLE_API

Ce JSON décrit les sources de tuiles, les polices (glyphs), les icônes (sprites) et la façon de dessiner chaque couche. MapLibre le lit et va chercher tout le reste tout seul. Quatre styles sont disponibles :

Style	Pour quoi faire
`streets`	Carte de référence, rues et points d'intérêt faciles à lire
`dark`	Tableaux de bord et mode nuit
`terrain`	Relief, cours d'eau et topographie
`sunny`	Tourisme et commerce, couleurs plus chaudes

1. Une première carte vectorielle

Il vous faut une clé API créée sur la console TMaps, avec votre domaine (et localhost) dans ses Authorized Domains.

<!doctype html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Carte vectorielle de la Tunisie</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.0/dist/maplibre-gl.css">
  <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.0/dist/maplibre-gl.js"></script>
  <style>
    html, body, #map { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const API_KEY = 'VOTRE_CLE_API';

    const map = new maplibregl.Map({
      container: 'map',
      style: `https://tiles.tmaps.tn/v-tile/streets.json?api_key=${API_KEY}`,
      center: [10.1815, 36.8002], // Tunis, en [lng, lat]
      zoom: 12,
      maxZoom: 18,
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');
  </script>
</body>
</html>

Un point d'attention : MapLibre attend [longitude, latitude], l'inverse de Leaflet qui attend [lat, lng]. C'est la cause la plus fréquente d'une carte qui s'ouvre en plein océan.

2. Changer de style sans recharger la carte

map.setStyle(url) remplace le style mais garde la carte, sa position et ses contrôles. Un sélecteur simple tient en quelques lignes :

const styleUrl = (name) => `https://tiles.tmaps.tn/v-tile/${name}.json?api_key=${API_KEY}`;

for (const name of ['streets', 'dark', 'terrain', 'sunny']) {
  const button = document.createElement('button');
  button.textContent = name;
  button.addEventListener('click', () => map.setStyle(styleUrl(name)));
  document.body.append(button);
}

Voici la même vue de Tunis dans les trois autres styles. D'abord dark, idéal pour un tableau de bord :

Puis terrain :

Et enfin sunny :

Suivre le mode sombre de l'utilisateur

Comme le changement est instantané, on peut tout simplement suivre le thème du système :

const dark = window.matchMedia('(prefers-color-scheme: dark)');
const applyTheme = () => map.setStyle(styleUrl(dark.matches ? 'dark' : 'streets'));

dark.addEventListener('change', applyTheme);
applyTheme();

3. Incliner et faire pivoter

La carte est dessinée en WebGL, on peut donc l'incliner et la faire pivoter, ce qui est impossible avec des tuiles raster :

map.jumpTo({
  center: [10.179, 36.799], // Médina de Tunis
  zoom: 15.5,
  pitch: 60,     // inclinaison, en degrés
  bearing: -25,  // rotation, en degrés
});

Vos utilisateurs peuvent faire la même chose eux-mêmes : clic droit maintenu sur ordinateur, ou deux doigts sur téléphone.

4. Personnaliser un style

Le JSON du style est modifiable. Téléchargez-le, changez les couches (couleurs, polices, noms affichés selon le zoom), puis hébergez votre propre version. Gardez simplement deux règles en tête :

les URL des tuiles dans sources doivent toujours pointer vers tiles.tmaps.tn avec votre api_key, car c'est ce qui authentifie votre consommation ;
vous pouvez modifier librement layers, ainsi que glyphs et sprite si vous hébergez vos propres polices et icônes.

Raster ou vectoriel ?

	Raster	Vectoriel
Bibliothèques	Leaflet, OpenLayers, tout client XYZ	MapLibre GL JS, MapLibre Native
Écrans haute densité	Flou (pas encore de @2x)	Toujours net
Changer de style	Il faut d'autres tuiles	Instantané, dans le navigateur
Rotation et inclinaison	Non	Oui
Appareils anciens	Très léger	Nécessite WebGL

Pour une carte simple intégrée dans une page, les tuiles raster avec Leaflet restent imbattables. Quand la carte est au cœur de votre produit, passez au vectoriel.

Pour aller plus loin

TMaps : API de cartographie pour la Tunisie
Toutes les démos en ligne : examples.tmaps.tn
Le code source, sous licence MIT : github.com/tmaps-tn/tmaps-snippets
La collection Postman : postman.com/tmaps-tn/tmaps-api
La documentation des tuiles vectorielles : tmaps.tn/documentation

Une question ou une remarque ? Laissez un commentaire ou écrivez-nous à support@tmaps.tn.

TMaps API in Postman: Test Geocoding in 2 Minutes

Tmaps Tunisia — Fri, 30 Oct 2026 09:47:39 +0000

Before writing a single line of code against a new API, most of us want to poke at it first and see what comes back. That's what the TMaps Postman collection is for: map tiles, address search, reverse geocoding and nearby places, each with documented parameters, example responses and tests.

Here's how to get your first response in about two minutes, and then how to automate the whole thing.

Step 1: get a key (30 seconds)

Create an API key in the TMaps console. It starts with ak_.

Postman calls the API from a server context, without an Origin header, so the key's authorized domains don't come into play here. Any valid key will do.

Step 2: fork the collection (30 seconds)

Click Run in Postman above, or open the public workspace, and choose Fork Collection. You now have your own copy of the collection in your own workspace.

The workspace README gives a quick overview of what's inside:

Step 3: set your key (30 seconds)

Open your forked collection, go to its Variables tab and add a variable called api_key, with your key as the Current value. If you prefer environments, you can also fork the TMaps environment from the public workspace and set api_key there.

That's the only setting. The collection adds the key to every request as an api_key query parameter. It's configured once in the collection's Authorization tab and every request inherits it. TMaps doesn't use an Authorization header.

Keep the key in Current value: it stays on your machine and isn't shared with your workspace.

Step 4: send your first request (30 seconds)

Open Geocoding, then Forward geocoding, and hit Send.

Each request comes with its own documentation: what it does, what it returns, and a link to the matching live demo.

The Params tab lists every parameter with a description. The optional ones (proximity, bbox, type) are already there, just unchecked. Tick them to try them out.

In the response you'll find the point in geometry.location, a formatted address, a confidence score and the Tunisian administrative breakdown (commune, delegation, governorate). No key yet? Open the saved example to see a real response:

Chaining requests

The test script of Forward geocoding saves the first result's coordinates in the lat and lng collection variables:

const results = pm.response.json().results ?? [];
if (results.length) {
  const { lat, lng } = results[0].geometry?.location ?? results[0];
  pm.collectionVariables.set('lat', lat);
  pm.collectionVariables.set('lng', lng);
}

So Reverse geocoding and Nearby search work straight away on the address you just found. No copying coordinates around by hand.

Every request also has a few tests (status code, response shape, results sorted by distance…). After sending, you'll see them in the Tests tab of the response.

Bonus: run it from the command line with Newman

The same collection runs outside Postman with Newman. The files live in the GitHub repository:

git clone https://github.com/tmaps-tn/tmaps-snippets.git
cd tmaps-snippets

npx newman run postman/TMaps-API.postman_collection.json \
  -e postman/TMaps.postman_environment.json \
  --env-var "api_key=$TMAPS_API_KEY"

Here's what a run looks like:

❏ Geocoding
↳ Forward geocoding
  GET https://api.tmaps.tn/geocoding/forward?q=Avenue Habib Bourguiba, Tunis&country=TN&limit=5&lang=fr&api_key=YOUR_API_KEY [200 OK, 3.64kB, 217ms]
  ✓  Status is 200
  ✓  Returns at least one result

↳ Reverse geocoding
  GET https://api.tmaps.tn/geocoding/reverse?lat=36.80060045491796&lng=10.191012134812192&lang=fr&api_key=YOUR_API_KEY [200 OK, 1.09kB, 29ms]
  ✓  Status is 200
  ✓  Returns an address

↳ Nearby search
  GET https://api.tmaps.tn/geocoding/nearby?lat=36.80060045491796&lng=10.191012134812192&radius=1000&categories=restaurant&limit=10&api_key=YOUR_API_KEY [200 OK, 2.38kB, 28ms]
  ✓  Status is 200
  ✓  Results are sorted by distance

│              assertions │                10 │                 0 │

In GitHub Actions

Store your key as a repository secret named TMAPS_API_KEY, then add a step:

- name: Check the TMaps API
  run: |
    npx newman run postman/TMaps-API.postman_collection.json \
      -e postman/TMaps.postman_environment.json \
      --env-var "api_key=${{ secrets.TMAPS_API_KEY }}"

Now your pipeline fails as soon as an endpoint your app relies on stops answering the way it should.

One word of caution: Newman prints full request URLs, key included. Don't run it with a real key in public CI logs, or mask the output first.

What's in the collection

Folder	Request	Endpoint
Maps	Raster tile (PNG)	`GET https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}`
Maps	Vector style (MapLibre)	`GET https://tiles.tmaps.tn/v-tile/{style}.json`
Geocoding	Forward geocoding	`GET https://api.tmaps.tn/geocoding/forward`
Geocoding	Reverse geocoding	`GET https://api.tmaps.tn/geocoding/reverse`
Geocoding	Nearby search	`GET https://api.tmaps.tn/geocoding/nearby`

Going further

Geocoding API for Tunisia: www.tmaps.tn/en/geocoding
Public Postman workspace: postman.com/tmaps-tn/tmaps-api
Live demos in the browser: examples.tmaps.tn
Source code, MIT licensed: github.com/tmaps-tn/tmaps-snippets
Documentation: tmaps.tn/documentation

Questions or feedback? Leave a comment or write to support@tmaps.tn.

Tester l'API TMaps dans Postman en 2 minutes

Tmaps Tunisia — Fri, 30 Oct 2026 09:47:30 +0000

Avant d'écrire la moindre ligne de code avec une nouvelle API, on a tous envie de la tester un peu pour voir ce qu'elle renvoie. C'est exactement le rôle de la collection Postman de TMaps : tuiles de carte, recherche d'adresse, géocodage inverse et lieux à proximité, chacun avec ses paramètres documentés, des exemples de réponse et des tests.

Voici comment obtenir votre première réponse en deux minutes environ, puis comment automatiser le tout.

Étape 1 : créer une clé (30 secondes)

Créez une clé API sur la console TMaps. Elle commence par ak_.

Postman appelle l'API depuis un contexte serveur, sans en-tête Origin : les domaines autorisés de la clé ne jouent donc aucun rôle ici. N'importe quelle clé valide fera l'affaire.

Étape 2 : copier la collection (30 secondes)

Cliquez sur Run in Postman ci-dessus, ou ouvrez l'espace de travail public, puis choisissez Fork Collection. Vous avez maintenant votre propre copie de la collection, dans votre espace de travail.

Le README de l'espace de travail résume ce qu'il contient :

Étape 3 : renseigner votre clé (30 secondes)

Ouvrez votre copie de la collection, allez dans l'onglet Variables et ajoutez une variable api_key, avec votre clé comme Current value. Si vous préférez les environnements, vous pouvez aussi copier l'environnement TMaps depuis l'espace de travail public et y renseigner api_key.

C'est le seul réglage. La collection ajoute la clé à chaque requête sous forme de paramètre api_key dans l'URL. Elle est configurée une seule fois, dans l'onglet Authorization de la collection, et toutes les requêtes en héritent. TMaps n'utilise pas d'en-tête Authorization.

Gardez bien la clé dans Current value : elle reste sur votre machine et n'est pas partagée avec votre espace de travail.

Étape 4 : envoyer votre première requête (30 secondes)

Ouvrez Geocoding, puis Forward geocoding, et cliquez sur Send.

Chaque requête a sa propre documentation : ce qu'elle fait, ce qu'elle renvoie, et un lien vers la démo en ligne correspondante.

L'onglet Params liste tous les paramètres avec leur description. Les paramètres facultatifs (proximity, bbox, type) sont déjà là, simplement décochés. Cochez-les pour les essayer.

Dans la réponse, vous trouverez le point dans geometry.location, l'adresse complète dans formatted, un score confidence et le découpage administratif tunisien (commune, delegation, governorate). Pas encore de clé ? Ouvrez l'exemple enregistré pour voir une vraie réponse :

Enchaîner les requêtes

Le script de test de Forward geocoding enregistre les coordonnées du premier résultat dans les variables lat et lng de la collection :

const results = pm.response.json().results ?? [];
if (results.length) {
  const { lat, lng } = results[0].geometry?.location ?? results[0];
  pm.collectionVariables.set('lat', lat);
  pm.collectionVariables.set('lng', lng);
}

Reverse geocoding et Nearby search fonctionnent donc tout de suite sur l'adresse que vous venez de trouver, sans recopier les coordonnées à la main.

Chaque requête a aussi quelques tests (code de statut, forme de la réponse, résultats triés par distance…). Après l'envoi, vous les retrouvez dans l'onglet Tests de la réponse.

Bonus : lancer la collection en ligne de commande avec Newman

La même collection fonctionne en dehors de Postman grâce à Newman. Les fichiers sont dans le dépôt GitHub :

git clone https://github.com/tmaps-tn/tmaps-snippets.git
cd tmaps-snippets

npx newman run postman/TMaps-API.postman_collection.json \
  -e postman/TMaps.postman_environment.json \
  --env-var "api_key=$TMAPS_API_KEY"

Voici à quoi ressemble une exécution :

❏ Geocoding
↳ Forward geocoding
  GET https://api.tmaps.tn/geocoding/forward?q=Avenue Habib Bourguiba, Tunis&country=TN&limit=5&lang=fr&api_key=VOTRE_CLE_API [200 OK, 3.64kB, 217ms]
  ✓  Status is 200
  ✓  Returns at least one result

↳ Reverse geocoding
  GET https://api.tmaps.tn/geocoding/reverse?lat=36.80060045491796&lng=10.191012134812192&lang=fr&api_key=VOTRE_CLE_API [200 OK, 1.09kB, 29ms]
  ✓  Status is 200
  ✓  Returns an address

↳ Nearby search
  GET https://api.tmaps.tn/geocoding/nearby?lat=36.80060045491796&lng=10.191012134812192&radius=1000&categories=restaurant&limit=10&api_key=VOTRE_CLE_API [200 OK, 2.38kB, 28ms]
  ✓  Status is 200
  ✓  Results are sorted by distance

│              assertions │                10 │                 0 │

Dans GitHub Actions

Enregistrez votre clé comme secret du dépôt sous le nom TMAPS_API_KEY, puis ajoutez une étape :

- name: Check the TMaps API
  run: |
    npx newman run postman/TMaps-API.postman_collection.json \
      -e postman/TMaps.postman_environment.json \
      --env-var "api_key=${{ secrets.TMAPS_API_KEY }}"

Votre pipeline échoue désormais dès qu'un endpoint dont votre application dépend ne répond plus comme prévu.

Petite mise en garde : Newman affiche les URL complètes des requêtes, clé comprise. Ne l'utilisez pas avec une vraie clé dans des logs de CI publics, ou masquez la sortie avant.

Ce que contient la collection

Dossier	Requête	Endpoint
Maps	Raster tile (PNG)	`GET https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}`
Maps	Vector style (MapLibre)	`GET https://tiles.tmaps.tn/v-tile/{style}.json`
Geocoding	Forward geocoding	`GET https://api.tmaps.tn/geocoding/forward`
Geocoding	Reverse geocoding	`GET https://api.tmaps.tn/geocoding/reverse`
Geocoding	Nearby search	`GET https://api.tmaps.tn/geocoding/nearby`

Pour aller plus loin

L'API de géocodage pour la Tunisie : www.tmaps.tn/geocoding
L'espace de travail Postman public : postman.com/tmaps-tn/tmaps-api
Les démos dans le navigateur : examples.tmaps.tn
Le code source, sous licence MIT : github.com/tmaps-tn/tmaps-snippets
La documentation : tmaps.tn/documentation

Une question ou une remarque ? Laissez un commentaire ou écrivez-nous à support@tmaps.tn.

Google Maps Alternative for Tunisia: TMaps Compared

Tmaps Tunisia — Mon, 26 Oct 2026 13:42:17 +0000

If you build an app for the Tunisian market, Google Maps is the default choice. Everyone knows it, it covers everything, and you've probably used it before. Then the first invoice arrives, in US dollars, charged to an international card, and you start wondering whether there's an alternative built for Tunisia.

We built TMaps to answer that question. But instead of a sales pitch, this post compares the two the way a developer would: the code, the billing model, real prices on three scenarios, and the cases where Google is still the better pick.

We'll stick to the two most common needs: showing a map and finding an address (geocoding). Routing deserves its own comparison.

1. The code: what does a migration look like?

Showing a map

With Google Maps, you load Google's JavaScript SDK:

<div id="map" style="height: 400px"></div>
<script>
  function initMap() {
    new google.maps.Map(document.getElementById('map'), {
      center: { lat: 36.8002, lng: 10.1815 }, // Tunis
      zoom: 12,
    });
  }
</script>
<script async src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_KEY&callback=initMap"></script>

With TMaps, you pick an open-source library (Leaflet here) and point it at the TMaps tiles:

<div id="map" style="height: 400px"></div>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.css">
<script src="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.js"></script>
<script>
  const map = L.map('map').setView([36.8002, 10.1815], 12); // Tunis
  L.tileLayer('https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=YOUR_TMAPS_KEY', {
    maxZoom: 18,
    attribution: '© TMaps',
  }).addTo(map);
</script>

The real difference isn't the line count. With Google, your code depends on Google's SDK. With TMaps, it depends on Leaflet, OpenLayers or MapLibre, which are open source: if you ever switch tile providers, you don't rewrite your map, you change a URL.

Finding an address

On the Google side, you call the Geocoding API:

const url = new URL('https://maps.googleapis.com/maps/api/geocode/json');
url.search = new URLSearchParams({ address: 'Rue de Marseille, Tunis', region: 'tn', language: 'fr', key: GOOGLE_KEY });
const { results } = await fetch(url).then((r) => r.json());
const { lat, lng } = results[0].geometry.location;

On the TMaps side:

const url = new URL('https://api.tmaps.tn/geocoding/forward');
url.search = new URLSearchParams({ q: 'Rue de Marseille, Tunis', country: 'TN', lang: 'fr', api_key: TMAPS_KEY });
const { results } = await fetch(url).then((r) => r.json());
const { lat, lng } = results[0].geometry.location;

Good news if you're migrating: the coordinates live in the same place, geometry.location. Where they really differ is the address breakdown:

Google returns a generic address_components array where each item has types (locality, administrative_area_level_1…). Mapping those types to Tunisian administrative levels is up to you.
TMaps returns fields named after the Tunisian administrative structure:

"components": {
  "street": "Rue de Marseille",
  "commune": "Habib Thameur",
  "delegation": "Bab El Bhar",
  "governorate": "Tunis",
  "country": "TN"
}

If your delivery form asks for the delegation and the governorate, that's mapping code you don't have to write.

2. Billing: two different units

This is the part you really need to understand before comparing prices.

Google bills a map per load: when a page displays the map, that's one billable event, no matter how many tiles it loads afterwards. Geocoding is billed per request. Each product has a monthly free cap: 10,000 map loads and 10,000 geocoding requests. Beyond that, you pay per thousand, in US dollars.

TMaps counts every successful request as one call: a map tile or a geocoding request. Plans are monthly bundles priced in Tunisian dinars (TND), with a number of calls included. Past your quota, every extra 1,000 calls costs 0.5 TND, and the service is never cut off. The Free plan includes 50,000 calls a month, commercial use included.

So a TMaps map uses several calls per display. We measured it on our demos, with a 1500 × 963 pixel map:

with raster tiles (Leaflet), the first display loads 35 tiles;
with vector tiles (MapLibre), it loads 12.

Tiles already in the browser cache aren't requested again, but to stay on the safe side, we count every display as a first visit.

3. Prices on three scenarios

Sources: the Google Maps Platform price list (updated October 21, 2026) and the TMaps pricing page. To compare, we use about 3 TND per US dollar (Central Bank of Tunisia rate on October 8, 2026). Google prices exclude taxes and international payment fees.

Scenario 1: a small showcase site

3,000 map displays and 1,000 address searches per month, commercial use.

Google: $0. Everything fits in the free caps.
TMaps: 0 TND (Free plan, commercial use allowed). With vector tiles, 3,000 displays × 12 tiles + 1,000 geocoding requests is about 37,000 calls, under the plan's 50,000.

A tie, then. The difference shows up as traffic grows: the TMaps Free plan covers about 4,000 vector map displays a month (or 1,400 with raster tiles), while Google stays free up to 10,000 map loads. In between, Google costs nothing and TMaps moves to the Starter plan at 79 TND a month. No point pretending otherwise.

Scenario 2: a delivery app

200,000 geocoding requests per month (entering and checking customer addresses), not much map display.

Google: $850/month, about 2,550 TND. The first 10,000 are free, then 90,000 at $5 per thousand and 100,000 at $4 per thousand.
TMaps: 79 TND/month (Starter plan, 200,000 calls included).

This is where the gap is widest: geocoding is a big line item on a Google invoice, and it's part of the bundle with TMaps.

Scenario 3: an e-commerce site

30,000 map displays and 20,000 address searches per month.

Google: $190/month, about 570 TND. 20,000 paid map loads at $7 per thousand, plus 10,000 paid geocoding requests at $5 per thousand.
TMaps with vector tiles (MapLibre): 229 TND/month (Growth plan). 30,000 × 12 tiles + 20,000 geocoding requests is about 380,000 calls, under the plan's 750,000.
TMaps with raster tiles (Leaflet): 599 TND/month (Business plan). At 35 tiles per display, you reach about 1,070,000 calls.

This one shows how much the technical choice matters: with vector tiles, TMaps costs about 2.5 times less than Google; with raster tiles, it ends up slightly more expensive. If your site shows a lot of maps, go vector.

Scenario	Google	TMaps
Small showcase site (3,000 maps a month)	$0	0 TND
Mid-size site (8,000 maps a month)	$0	79 TND
Delivery app	≈ 2,550 TND ($850)	79 TND
E-commerce, vector maps	≈ 570 TND ($190)	229 TND
E-commerce, raster maps	≈ 570 TND ($190)	599 TND

4. What the price list doesn't show

The street reference. This is probably the biggest difference, and no price list shows it. The TMaps database holds more than 120,000 roads, with a verified name for 72% of road segments on average. According to our coverage measurement, published and recomputed every week on the map coverage page (in French), TMaps shows on average twice as many named roads as Google Maps across Tunisia's 24 governorates, especially in suburban areas and new neighbourhoods. Streets are named in French and Arabic, including the informal local names people actually use.

For a delivery app, that's very concrete: a street with no name is an address your customer can't type, and a driver who has to call to ask for directions. This is our own measurement, not an independent audit, so check it on your area: the side-by-side pages show Google on the left and TMaps on the right, for example in Ben Arous.

Currency. Google bills in US dollars, through a billing account and an international payment method, so every move of the dinar changes your invoice. TMaps bills in dinars, with no exchange-rate exposure.

Overages. With TMaps, a traffic spike never takes the service down: it's billed at the overage rate on the next invoice. With Google, pay-as-you-go has no ceiling by default, so set quotas and budget alerts.

Arabic and Arabizi. Tunisian addresses get typed in French, in Arabic script and in Arabizi (nahj, 9asr said). Another post in this series shows how to build an address search that handles all three, and you can try it in the address search demo: type 9asr said.

Support. A team based in Tunis, working Tunisian hours, on one side; the support desk of a global platform on the other.

5. When to stay on Google Maps

An honest comparison also has to say when not to switch:

Your traffic fits in Google's free caps but not in the TMaps Free plan (roughly 4,000 to 10,000 maps a month): with Google, you won't pay anything.
Your app covers several countries, and Tunisia is just one market among others.
You rely on services TMaps doesn't offer: Street View, Google's global places database with reviews and photos, or mobile SDKs your team already knows.

On the other hand, TMaps makes sense when Tunisia is your main market, when your customers live in new or suburban neighbourhoods where named streets make the difference, when you geocode a lot of addresses, when you want a fixed invoice in dinars, or when you'd rather build your map on open-source libraries.

See for yourself

Compare both maps in Ben Arous, Sfax or Nabeul
Road coverage, governorate by governorate: map coverage (in French)
Try the API without writing code in the Postman collection
Live demos and their code: examples.tmaps.tn

Prices quoted here are from October 2026 and can change: always check the official price lists before you decide. Questions about a migration? Leave a comment or write to support@tmaps.tn.

Migrer de Google Maps vers TMaps en Tunisie

Tmaps Tunisia — Mon, 26 Oct 2026 10:33:40 +0000

Vous avez une application tunisienne qui tourne sur Google Maps et vous envisagez de passer à TMaps. Bonne nouvelle : pour les deux usages les plus courants, afficher une carte et transformer une adresse en coordonnées, la migration tient en quelques fichiers. Cet article passe en revue ce qui change dans le code, ce qui ne change pas, et le piège de facturation à connaître avant de mettre en production.

Ce guide ne parle pas d'itinéraires : on se limite à la carte et au géocodage.

Étape 1 : remplacer le SDK Google par Leaflet

Côté Google, une carte typique ressemble à ceci :

<div id="map" style="height: 400px"></div>
<script>
  function initMap() {
    const map = new google.maps.Map(document.getElementById('map'), {
      center: { lat: 36.8002, lng: 10.1815 },
      zoom: 12,
    });
    new google.maps.Marker({ position: { lat: 36.8002, lng: 10.1815 }, map });
  }
</script>
<script async src="https://maps.googleapis.com/maps/api/js?key=VOTRE_CLE_GOOGLE&callback=initMap"></script>

TMaps ne fournit pas de SDK propriétaire. On garde une bibliothèque open source et on lui donne l'URL des tuiles TMaps. Avec Leaflet, l'équivalent s'écrit :

<div id="map" style="height: 400px"></div>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.css">
<script src="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.js"></script>
<script>
  const map = L.map('map').setView([36.8002, 10.1815], 12);
  L.tileLayer('https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=VOTRE_CLE_TMAPS', {
    maxZoom: 18,
    attribution: '© TMaps',
  }).addTo(map);
  L.marker([36.8002, 10.1815]).addTo(map);
</script>

Quelques correspondances utiles pendant la réécriture :

Google Maps JS	Leaflet
`new google.maps.Map(el, { center, zoom })`	`L.map(el).setView([lat, lng], zoom)`
`new google.maps.Marker({ position, map })`	`L.marker([lat, lng]).addTo(map)`
`{ lat: 36.8, lng: 10.18 }`	`[36.8, 10.18]`
chargement asynchrone et `callback=initMap`	script classique, la carte existe tout de suite

Plus de callback global, plus de clé Google dans le HTML. Et surtout, votre code ne dépend plus d'un fournisseur : changer de source de tuiles un jour reviendra à modifier une URL.

Étape 2 : passer au vectoriel (vraiment)

Le raster avec Leaflet est la façon la plus directe de remplacer Google, mais ce n'est pas celle que nous conseillons pour la production. Avec MapLibre GL JS et les tuiles vectorielles, la migration reste aussi courte :

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.tmaps.tn/v-tile/streets.json?api_key=VOTRE_CLE_TMAPS',
  center: [10.1815, 36.8002], // attention : [lng, lat]
  zoom: 12,
});
new maplibregl.Marker().setLngLat([10.1815, 36.8002]).addTo(map);

Piège classique en venant de Google : MapLibre attend [longitude, latitude]. Si votre carte s'ouvre au milieu de l'océan, c'est presque toujours ça.

La raison de ce conseil tient à la facturation, détaillée plus bas.

Étape 3 : migrer le géocodage

Ici, le changement est minime. Avant :

const url = new URL('https://maps.googleapis.com/maps/api/geocode/json');
url.search = new URLSearchParams({ address: 'Rue de Marseille, Tunis', region: 'tn', language: 'fr', key: GOOGLE_KEY });
const { results } = await fetch(url).then((r) => r.json());
const { lat, lng } = results[0].geometry.location;

Après :

const url = new URL('https://api.tmaps.tn/geocoding/forward');
url.search = new URLSearchParams({ q: 'Rue de Marseille, Tunis', country: 'TN', lang: 'fr', api_key: TMAPS_KEY });
const { results } = await fetch(url).then((r) => r.json());
const { lat, lng } = results[0].geometry.location;

Quatre paramètres renommés (address devient q, region devient country, language devient lang, key devient api_key) et c'est tout. La dernière ligne est strictement identique : les coordonnées sont dans geometry.location, comme chez Google. Le code qui place un marqueur ou enregistre une position en base n'a pas à bouger.

Étape 4 : simplifier le découpage de l'adresse

C'est là que la migration fait gagner du code. Chez Google, l'adresse détaillée arrive sous forme de tableau générique address_components, et il faut aller chercher chaque niveau par son type :

const pick = (type) =>
  results[0].address_components.find((c) => c.types.includes(type))?.long_name;

const governorate = pick('administrative_area_level_1');
const city = pick('locality');
// et la délégation ? À vérifier au cas par cas selon l'adresse...

Ce code de correspondance est fragile : les types génériques ne collent pas toujours aux niveaux administratifs tunisiens, et on finit avec des cas particuliers. TMaps renvoie directement des champs nommés selon le découpage du pays :

"components": {
  "street": "Rue de Marseille",
  "commune": "Habib Thameur",
  "delegation": "Bab El Bhar",
  "governorate": "Tunis",
  "country": "TN"
}

La fonction pick disparaît :

const { commune, delegation, governorate } = results[0].components;

Pour un formulaire de livraison qui calcule ses frais par délégation, c'est une source de bugs en moins.

Le piège : l'unité de facturation n'est pas la même

Avant de comparer des factures, il faut comprendre ce qu'on compte.

Google facture la carte au chargement : une page qui affiche une carte compte pour un, quel que soit le nombre de tuiles téléchargées ensuite.
TMaps compte chaque requête réussie : une tuile, c'est un appel ; un géocodage, c'est un appel.

Une carte TMaps consomme donc plusieurs appels par affichage. Mesuré sur nos démos avec une carte de 1500 × 963 pixels, le premier affichage charge environ 35 tuiles en raster (Leaflet) contre 12 en vectoriel (MapLibre). Les tuiles déjà en cache dans le navigateur ne sont pas redemandées, mais pour estimer votre consommation, comptez chaque affichage comme une première visite.

D'où le conseil de l'étape 2 : à trafic égal, le vectoriel divise à peu près par trois le nombre d'appels liés à la carte. Si vous migrez une application qui affiche beaucoup de cartes, c'est le réglage qui pèse le plus sur la facture. Le géocodage, lui, reste à un appel par requête dans les deux cas.

Et les prix ?

On ne refait pas le calcul ici. Nous avons publié un comparatif complet de Google Maps et TMaps avec les prix en dinars sur plusieurs scénarios (petite vitrine, livraison, e-commerce), le référentiel des rues, et les cas où il vaut mieux rester sur Google. Les grilles de TMaps sont sur la page tarifs.

Avant de migrer, regardez aussi la carte elle-même sur votre zone : les pages « Comparez vous-même » affichent Google et TMaps côte à côte, par exemple sur Ben Arous.

Checklist de migration

Remplacer le script Google par Leaflet, ou mieux, MapLibre avec les tuiles vectorielles.
Inverser l'ordre des coordonnées si vous passez à MapLibre ([lng, lat]).
Renommer les paramètres du géocodage, garder la lecture de geometry.location.
Supprimer le code de correspondance des address_components au profit de components.
Estimer la consommation en tuiles par affichage, pas en chargements de carte.

Les démos et leur code sont sur examples.tmaps.tn, et le dépôt tmaps-snippets contient les exemples de cette série. Une question sur votre migration ? Laissez un commentaire ou écrivez-nous à support@tmaps.tn.

MapLibre GL Vector Tiles with TMaps: Dark Mode and 3D

Tmaps Tunisia — Fri, 23 Oct 2026 13:28:05 +0000

Raster tiles are pictures of the map. They're simple and they work everywhere, but what you get is what you get. Vector tiles send the map data itself (roads, buildings, labels) and let the browser draw it. That means the map stays sharp on any screen, zooming is smooth, you can rotate and tilt it, and you can restyle it instantly.

In this post we'll use TMaps vector tiles with MapLibre GL JS, the open-source WebGL map library, and build a little style switcher with four styles.

Live demo: examples.tmaps.tn/03-vector-maplibre-styles

How TMaps vector tiles work

You don't request the tiles yourself. Each style is a JSON document that follows the Mapbox Style Specification:

https://tiles.tmaps.tn/v-tile/{style}.json?api_key=YOUR_API_KEY

That JSON lists the tile sources, the fonts (glyphs), the icons (sprites) and how every layer should be drawn. MapLibre reads it and fetches the rest on its own. There are four styles to choose from:

Style	Good for
`streets`	Everyday reference map, easy to read streets and points of interest
`dark`	Dashboards and night mode
`terrain`	Relief, rivers and topography
`sunny`	Tourism and retail, warmer colours

1. A first vector map

You'll need a TMaps API key from the TMaps console, with your domain (and localhost) in its Authorized Domains.

<!doctype html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Vector map of Tunisia</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.0/dist/maplibre-gl.css">
  <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.6.0/dist/maplibre-gl.js"></script>
  <style>
    html, body, #map { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const API_KEY = 'YOUR_API_KEY';

    const map = new maplibregl.Map({
      container: 'map',
      style: `https://tiles.tmaps.tn/v-tile/streets.json?api_key=${API_KEY}`,
      center: [10.1815, 36.8002], // Tunis, as [lng, lat]
      zoom: 12,
      maxZoom: 18,
    });

    map.addControl(new maplibregl.NavigationControl(), 'top-right');
  </script>
</body>
</html>

One thing to watch: MapLibre takes [longitude, latitude], the opposite of Leaflet's [lat, lng]. Mixing them up is the most common reason a map opens in the middle of the ocean.

2. Switch styles without reloading the map

map.setStyle(url) swaps the style but keeps the map, its position and its controls. A basic switcher is only a few lines:

const styleUrl = (name) => `https://tiles.tmaps.tn/v-tile/${name}.json?api_key=${API_KEY}`;

for (const name of ['streets', 'dark', 'terrain', 'sunny']) {
  const button = document.createElement('button');
  button.textContent = name;
  button.addEventListener('click', () => map.setStyle(styleUrl(name)));
  document.body.append(button);
}

Here's the same view of Tunis in the other three styles. First dark, which works well on dashboards:

Then terrain:

And sunny:

Follow the user's dark mode

Since switching is instant, you can simply follow the operating system's theme:

const dark = window.matchMedia('(prefers-color-scheme: dark)');
const applyTheme = () => map.setStyle(styleUrl(dark.matches ? 'dark' : 'streets'));

dark.addEventListener('change', applyTheme);
applyTheme();

3. Tilt and rotate

The map is drawn with WebGL, so you can tilt and rotate it, which raster tiles simply can't do:

map.jumpTo({
  center: [10.179, 36.799], // Medina of Tunis
  zoom: 15.5,
  pitch: 60,     // tilt, in degrees
  bearing: -25,  // rotation, in degrees
});

Users can do the same thing themselves with a right-click drag on desktop, or two fingers on a phone.

4. Customize a style

The style JSON is yours to tweak. Download it, change the layers (colours, fonts, which labels show up at which zoom), and host your own copy. Just keep two things in mind:

the tile URLs in sources must still point to tiles.tmaps.tn with your api_key, because that's how your usage is authenticated;
you're free to change layers, and also glyphs and sprite if you host your own fonts and icons.

Raster or vector?

	Raster	Vector
Libraries	Leaflet, OpenLayers, any XYZ client	MapLibre GL JS, MapLibre Native
High-density screens	Blurry (no @2x yet)	Always sharp
Changing the style	Needs new tiles	Instant, in the browser
Rotate and tilt	No	Yes
Older devices	Very light	Needs WebGL

For a simple map embedded in a page, raster tiles with Leaflet are hard to beat (that's the first post of this series). When the map is the heart of your product, go vector.

Going further

About TMaps: Tunisia maps, geocoding and routing API
Live demos: examples.tmaps.tn
Source code, MIT licensed: github.com/tmaps-tn/tmaps-snippets
Postman collection: postman.com/tmaps-tn/tmaps-api
Vector tiles documentation: tmaps.tn/documentation

Questions or feedback? Leave a comment or write to support@tmaps.tn.

DEV Community: Tmaps Tunisia

Leaflet Tutorial: Add a Map of Tunisia with TMaps Tiles

What are raster tiles?

1. Get an API key

2. The complete example

3. A few details worth getting right

Set maxZoom: 18

Say something when tiles fail

Caching

High-density screens

The same tiles work everywhere

Going further

Autocomplétion d'adresse en Tunisie : arabe et arabizi

L'arabizi en 30 secondes

Étape 1 : une autocomplétion de base solide

Étape 2 : des résultats en arabe, de droite à gauche

Étape 3 : ce que l'API comprend déjà

Étape 4 : normaliser l'arabizi côté navigateur

Étape 5 : chercher les deux versions en parallèle

Étape 6 : ne pas faire confiance à tous les résultats

Les limites actuelles

En résumé

Pour aller plus loin

Carte de la Tunisie avec OpenLayers et les tuiles TMaps

Avant de commencer

1. La couche de tuiles

2. La projection, le piège classique

3. Garder la vue dans l'URL

4. L'exemple complet

Quelques conseils

Pour aller plus loin

OpenLayers XYZ Tiles with TMaps: Shareable Map of Tunisia

Before you start

1. The tile layer

2. Get the projection right

3. Keep the view in the URL

4. The complete example

A few tips

Going further

Carte de la Tunisie sur votre site web en 10 minutes

Les outils

De 0 à 3 minutes : créer une clé API

De 3 à 7 minutes : la carte

De 7 à 9 minutes : un marqueur sur votre adresse

À 10 minutes : la mise en ligne

Pour aller plus loin

Carte vectorielle de la Tunisie avec MapLibre et TMaps

Comment fonctionnent les tuiles vectorielles TMaps

1. Une première carte vectorielle

2. Changer de style sans recharger la carte

Suivre le mode sombre de l'utilisateur

3. Incliner et faire pivoter

4. Personnaliser un style

Raster ou vectoriel ?

Pour aller plus loin

TMaps API in Postman: Test Geocoding in 2 Minutes

Step 1: get a key (30 seconds)

Step 2: fork the collection (30 seconds)

Step 3: set your key (30 seconds)

Step 4: send your first request (30 seconds)

Chaining requests

Bonus: run it from the command line with Newman

In GitHub Actions

What's in the collection

Going further

Tester l'API TMaps dans Postman en 2 minutes

Étape 1 : créer une clé (30 secondes)

Étape 2 : copier la collection (30 secondes)

Étape 3 : renseigner votre clé (30 secondes)

Étape 4 : envoyer votre première requête (30 secondes)

Enchaîner les requêtes

Bonus : lancer la collection en ligne de commande avec Newman

Dans GitHub Actions

Ce que contient la collection

Pour aller plus loin

Google Maps Alternative for Tunisia: TMaps Compared

1. The code: what does a migration look like?

Showing a map

Finding an address

2. Billing: two different units

Set `maxZoom: 18`