Bienvenue dans la documentation TMaps. Cette section couvre tout ce dont vous avez besoin pour intégrer nos services : créer un compte, gérer vos clés API, sécuriser vos appels par domaine et utiliser chaque endpoint avec des exemples de code copiables.

Par où commencer ?

Si c'est votre première intégration, suivez le démarrage rapide. Si vous cherchez la référence d'un endpoint précis, utilisez la barre latérale.

Conventions

• Authentification : tous les endpoints utilisent un paramètre api_key en query string.
• Format : toutes les réponses sont en JSON, encodage UTF-8.
• Coordonnées : lat = latitude (–90 à 90), lng = longitude (–180 à 180), en degrés décimaux WGS84.
• HTTPS uniquement : les requêtes en HTTP renvoient 403.

Cette page résume les trois étapes pour passer de zéro à votre premier appel API. Chaque étape est détaillée dans sa propre page : suivez les liens pour aller en profondeur.

1. Créer un compte sur la console

Rendez-vous sur app.tmaps.tn et créez un compte avec votre email + mot de passe ou en un clic via Google.

→ Détails : Créer un compte

2. Créer une clé API et autoriser vos domaines

Une fois connecté à la console :

1. Ouvrez la section API Keys et cliquez sur Create API Key — vous obtenez une clé au format ak_….
2. Ouvrez la section Authorized Domains et ajoutez les domaines depuis lesquels votre clé sera utilisée (ex : monsite.tn, app.monsite.tn).
3. Liez la clé à un ou plusieurs domaines depuis l’écran de la clé.

→ Détails : Gérer les clés API · Domaines autorisés

3. Lancer votre première requête

Toutes les requêtes utilisent un paramètre api_key en query string :

curl "https://api.tmaps.tn/geocoding/forward?q=Avenue%20Habib%20Bourguiba%2C%20Tunis&api_key=YOUR_API_KEY"

const url = new URL('https://api.tmaps.tn/geocoding/forward');
url.searchParams.set('q', 'Avenue Habib Bourguiba, Tunis');
url.searchParams.set('api_key', 'YOUR_API_KEY');

const res = await fetch(url);
const data = await res.json();
console.log(data.results[0]);
// { lat: 36.8002, lng: 10.1815, formatted: '...', confidence: 0.95 }

import requests

res = requests.get(
  'https://api.tmaps.tn/geocoding/forward',
  params={
      'q': 'Avenue Habib Bourguiba, Tunis',
      'api_key': 'YOUR_API_KEY',
  },
)
print(res.json()['results'][0])

<?php
$query = http_build_query([
  'q'       => 'Avenue Habib Bourguiba, Tunis',
  'api_key' => 'YOUR_API_KEY',
]);
$res = file_get_contents("https://api.tmaps.tn/geocoding/forward?$query");
$data = json_decode($res, true);
print_r($data['results'][0]);

Et après ?

Selon votre cas d’usage, plongez dans la référence d’API correspondante :

• Afficher une carte : Tuiles raster ou Tuiles vectorielles
• Convertir des adresses : Géocodage direct / inverse
• Trouver des points d’intérêt : Recherche à proximité
• Calculer un itinéraire : Direction · Optimisé · Isochrone
• Comparer des temps de trajet : Matrice de distances
• Générer une image de carte : Cartes statiques

Toute requête vers l’API TMaps doit être authentifiée à l’aide d’une clé API (api_key), créée depuis la console TMaps.

Format de la clé

Une clé API TMaps a la forme suivante :

ak_a1b2c3d4e5f607xxxXXXxXXxxXX

Le préfixe ak_ est suivi de 32 caractères hexadécimaux. Considérez votre clé comme un mot de passe : ne la versionnez pas dans un dépôt public et ne l’exposez pas dans des logs côté client si possible.

Passer la clé : api_key en query string

Tous les endpoints (GET comme POST) acceptent la clé via le paramètre api_key dans la query string.

curl "https://api.tmaps.tn/geocoding/forward?q=Tunis&api_key=YOUR_API_KEY"

const url = new URL('https://api.tmaps.tn/geocoding/forward');
url.searchParams.set('q', 'Tunis');
url.searchParams.set('api_key', 'YOUR_API_KEY');

const res = await fetch(url);

Domaines autorisés (Origin / Referer)

Pour empêcher qu’une clé exposée dans le code JavaScript d’un site soit réutilisée ailleurs, vous pouvez restreindre une clé à une liste blanche de domaines depuis la console (rubrique Authorized Domains).

À chaque requête, le backend vérifie en cascade :

1. Le header Origin envoyé par le navigateur ;
2. À défaut, le header Referer.

Si l’un des deux est présent et ne correspond à aucun domaine autorisé pour la clé, la requête est rejetée avec un statut 403 :

{
"error": "domain not authorized"
}

Règles précises

• Pas de wildcard.*.monsite.tn n’est pas accepté : ajoutez chaque sous-domaine explicitement (app.monsite.tn, admin.monsite.tn, …).
• localhost doit être ajouté. Pour le développement local, ajoutez localhost (et 127.0.0.1 si vous l’utilisez) à votre liste de domaines.
• Plusieurs domaines par clé : une même clé peut être autorisée sur plusieurs domaines.
• Plusieurs clés sur un domaine : un même domaine peut être autorisé pour plusieurs clés (par ex. une clé pour la prod, une autre pour la pré-prod).
• HTTPS uniquement : les requêtes en HTTP sont systématiquement rejetées en 403.

Appels côté serveur

Quand votre code tourne dans un environnement server-side (Node, PHP, Python, Go, mobile natif…), les headers Origin et Referer sont absents de la requête. Dans ce cas, la liste des domaines autorisés est ignorée et la clé fonctionne sans restriction.

Erreurs d’authentification

Voir la liste complète sur la page Codes d’erreur.

Bonnes pratiques

• Une clé par environnement (dev / staging / prod) et par usage (frontend / backend).
• Restreindre les clés exposées au navigateur à la liste exacte de vos domaines.
• Désactiver immédiatement une clé suspecte depuis la console (la clé peut ensuite être réactivée plus tard ou révoquée définitivement).
• Surveiller l’usage depuis l’onglet Usage de la console pour détecter un pic anormal.

La console TMaps est l’interface qui vous permet de gérer vos clés API, vos domaines autorisés et de suivre votre consommation. Vous y accédez sur app.tmaps.tn.

1. Ouvrir la page d’inscription

Rendez-vous sur app.tmaps.tn/auth/sign-up.

2. Choisir une méthode d’inscription

Deux options vous sont proposées :

Option A — Email + mot de passe

1. Saisissez votre email professionnel.
2. Définissez un mot de passe robuste (au moins 8 caractères).
3. Cliquez sur Sign up.
4. Vous recevrez un email de confirmation : cliquez sur le lien pour activer votre compte.

Option B — Google (sign-in en un clic)

1. Cliquez sur Continue with Google.
2. Sélectionnez votre compte Google et autorisez l’accès aux informations de base (nom, email).
3. Vous êtes immédiatement connecté à la console.

3. Premier accès au tableau de bord

Une fois connecté, vous arrivez sur le tableau de bord de la console. Les sections principales sont accessibles depuis la barre latérale :

• API Keys — créer, désactiver et révoquer vos clés
• Authorized Domains — gérer les domaines autorisés à utiliser vos clés
• Usage — suivre votre consommation par endpoint
• Billing — abonnement et factures

Étape suivante

Vous êtes prêt à créer votre première clé API. Continuez avec :

→ Créer une clé API

Une clé API est l’identifiant unique qui authentifie vos requêtes vers les endpoints TMaps. Cette page explique comment la créer, la désactiver et la révoquer depuis la console.

Créer une clé

1. Connectez-vous à app.tmaps.tn.
2. Dans la barre latérale, cliquez sur API Keys.
3. Cliquez sur le bouton Create API Key en haut à droite.

4. Donnez un nom à la clé (ex. Production frontend, Mobile app iOS). Ce nom n’a aucun impact technique mais facilite la gestion quand vous en aurez plusieurs.

5. Cliquez sur Create. La clé s’affiche immédiatement, au format ak_....

Liste des clés

Toutes vos clés sont visibles depuis l’onglet API Keys. Chaque ligne affiche :

• Nom de la clé
• Préfixe (les premiers caractères de la clé) pour l’identifier sans la dévoiler en entier
• Statut : Active, Disabled ou Revoked
• Date de création
• Domaines liés (résumé)

Désactiver une clé

Désactiver suspend temporairement l’usage de la clé : tout appel renverra 401. La clé peut être réactivée à tout moment.

1. Sur la liste, cliquez sur les trois points (⋮) en bout de ligne.
2. Choisissez Disable.
3. Confirmez. Le statut passe à Disabled.

Pour réactiver, ouvrez le même menu et cliquez sur Enable.

Révoquer une clé

La révocation est définitive : la clé ne pourra plus être réactivée. Utilisez-la quand :

• la clé a fuité publiquement,
• vous mettez hors service le projet qui l’utilisait,
• vous faites du nettoyage post-rotation.

1. Sur la liste, cliquez sur les trois points (⋮).
2. Choisissez Revoke.
3. Tapez le nom de la clé pour confirmer.

Bonnes pratiques

• Une clé par environnement : dev, staging, production.
• Une clé par usage : frontend (avec domaines stricts), backend (sans domaine), mobile (sans domaine).
• Tournez régulièrement vos clés : créez la nouvelle, déployez, puis révoquez l’ancienne.
• Surveillez la consommation depuis l’onglet Usage pour repérer un pic anormal.

Étape suivante

Pour sécuriser une clé exposée au navigateur, ajoutez-lui des domaines autorisés :

→ Domaines autorisés

Un domaine autorisé (Authorized Domain) est un nom d’hôte depuis lequel vos clés API sont autorisées à être utilisées. Le check se fait à chaque requête en comparant les headers Origin puis Referer à la liste des domaines liés à la clé.

Créer un domaine autorisé

1. Connectez-vous à app.tmaps.tn.
2. Dans la barre latérale, cliquez sur Authorized Domains.
3. Cliquez sur Add Domain.

4. Saisissez le nom de domaine sans schéma ni chemin :

   • ✅ monsite.tn
   • ✅ app.monsite.tn
   • ✅ localhost
   • ❌ https://monsite.tn
   • ❌ monsite.tn/dashboard
   • ❌ *.monsite.tn(wildcard non supporté)

5. Cliquez sur Add.

Lier une clé à un ou plusieurs domaines

Une fois vos domaines ajoutés, vous devez les lier aux clés concernées. Vous pouvez le faire de deux façons :

Depuis la fiche d’une clé

1. Ouvrez API Keys puis cliquez sur la clé concernée.
2. Dans la section Authorized Domains, cliquez sur Link domain.
3. Sélectionnez les domaines à autoriser pour cette clé puis validez.

Depuis la fiche d’un domaine

1. Ouvrez Authorized Domains puis cliquez sur le domaine concerné.
2. Dans la section API Keys, cliquez sur Link key.
3. Sélectionnez les clés à associer puis validez.

Modèle N : N

Le lien entre clés et domaines est N : N :

• Une même clé peut être autorisée sur plusieurs domaines (ex. monsite.tn, app.monsite.tn, localhost).
• Un même domaine peut être autorisé pour plusieurs clés (ex. votre clé de prod et celle de pré-production utilisent toutes deux app.monsite.tn).

Comportement à l’exécution

À chaque requête authentifiée par une clé qui a au moins un domaine lié, le backend :

1. Lit le header Origin de la requête. S’il est présent et figure dans la liste des domaines autorisés → la requête passe.
2. Sinon, lit le header Referer. S’il est présent et figure dans la liste → la requête passe.
3. Sinon, la requête est rejetée avec un statut 403 : {"error":"domain not authorized"}.

Cas particulier — appels server-to-server (Node, PHP, mobile natif…) : ni Origin ni Referer n’est envoyé. Dans ce cas, la liste de domaines est ignorée et la clé fonctionne sans restriction. Voir Authentification pour le détail.

Délier ou supprimer un domaine

• Délier d’une clé : ouvrez la clé, puis cliquez sur l’icône × à côté du domaine dans la section Authorized Domains. La clé reste active mais ne fonctionnera plus depuis ce domaine.
• Supprimer un domaine : ouvrez Authorized Domains, cliquez sur le domaine, puis sur Delete domain. Le domaine est délié de toutes les clés en une seule opération.

Bonnes pratiques

• Restreignez les clés exposées au navigateur dès la création — n’attendez pas une fuite.
• Distinguez prod et dev : pour la prod, listez uniquement vos domaines réels ; pour le dev, utilisez une clé dédiée avec localhost ajouté.
• Pour le mobile / backend, créez une clé séparée sans aucun domaine : la liste blanche ne s’applique pas (pas d’Origin/Referer) et c’est plus clair que de lister manuellement l’absence de check.
• Auditez régulièrement les liens clé ↔ domaine : retirez les domaines obsolètes pour réduire la surface d’attaque.

L’endpoint Raster Tiles sert des tuiles d’image PNG suivant la convention XYZ standard (z = zoom, x / y = coordonnées). Compatible avec toutes les bibliothèques cartographiques web et mobile.

Endpoint

Paramètres

Caractéristiques

• Format de retour : image/png
• Plage de zoom : 0 → 18
• Taille de tuile : 256 × 256 pixels
• Retina (@2x) : non supporté pour le moment
• Couverture : monde entier, optimisée et enrichie pour la Tunisie

Réponse

Une réponse réussie est un fichier PNG (Content-Type: image/png).

En cas d’erreur, vous recevez un statut HTTP 4xx/5xx avec un body JSON :

{ "error": "missing api_key" }

Voir la liste complète sur la page Codes d’erreur.

Intégration — Leaflet

import L from 'leaflet';
import 'leaflet/dist/leaflet.css';

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_API_KEY',
{
  maxZoom: 18,
  attribution: '© TMaps',
}
).addTo(map);

<link rel="stylesheet" href="https://unpkg.com/leaflet/dist/leaflet.css" />
<script src="https://unpkg.com/leaflet"><\/script>
<div id="map" style="height: 400px"></div>
<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=YOUR_API_KEY',
  { maxZoom: 18 }
).addTo(map);
<\/script>

Intégration — MapLibre GL JS

MapLibre supporte les couches raster via la propriété sources du style :

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
container: 'map',
center: [10.1815, 36.8002],
zoom: 12,
maxZoom: 18,
style: {
  version: 8,
  sources: {
    'tmaps-raster': {
      type: 'raster',
      tiles: ['https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=YOUR_API_KEY'],
      tileSize: 256,
    },
  },
  layers: [{ id: 'tmaps-raster', type: 'raster', source: 'tmaps-raster' }],
},
});

Intégration — OpenLayers

import 'ol/ol.css';
import { Map, View } from 'ol';
import TileLayer from 'ol/layer/Tile';
import XYZ from 'ol/source/XYZ';
import { fromLonLat } from 'ol/proj';

new Map({
target: 'map',
layers: [
  new TileLayer({
    source: new XYZ({
      url: 'https://tiles.tmaps.tn/r-tile/{z}/{x}/{y}?api_key=YOUR_API_KEY',
      maxZoom: 18,
    }),
  }),
],
view: new View({
  center: fromLonLat([10.1815, 36.8002]),
  zoom: 12,
}),
});

Intégration mobile

Tous les SDK mobiles qui supportent les couches XYZ (MapLibre Native, MapKit JS, react-native-maps en mode UrlTemplate, etc.) sont compatibles. Utilisez le même template :

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

Obtenir votre clé

Pour tester l’API et l’utiliser en production, créez un compte puis générez une clé API depuis la console TMaps. Pensez à ajouter localhost à vos domaines autorisés si vous testez en local depuis un navigateur.

Les tuiles vectorielles TMaps sont distribuées au format Mapbox Vector Tile (.pbf) et encapsulées dans un manifest TileJSON / Mapbox Style Spec prêt à être consommé par MapLibre GL.

Quatre styles sont disponibles, chacun avec sa palette et sa thématique.

Endpoint

Chaque style est exposé sous la forme d’un fichier JSON conforme à la Mapbox Style Specification :

L’URL des tuiles .pbf est référencée dans la propriété sources du JSON renvoyé : aucun appel manuel à faire, MapLibre gère tout automatiquement.

Styles disponibles

Intégration — MapLibre GL JS

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

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

map.addControl(new maplibregl.NavigationControl(), 'top-right');

<link href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/maplibre-gl"><\/script>
<div id="map" style="height: 400px"></div>
<script>
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.tmaps.tn/v-tile/streets.json?api_key=YOUR_API_KEY',
  center: [10.1815, 36.8002],
  zoom: 12,
});
<\/script>

import { useEffect, useRef } from 'react';
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

export function TmapsVectorMap() {
const ref = useRef(null);

useEffect(() => {
  const map = new maplibregl.Map({
    container: ref.current,
    style: 'https://tiles.tmaps.tn/v-tile/streets.json?api_key=YOUR_API_KEY',
    center: [10.1815, 36.8002],
    zoom: 12,
  });
  return () => map.remove();
}, []);

return <div ref={ref} style={{ height: 400 }} />;
}

Switch de style (dark / light)

const styles = {
light: 'https://tiles.tmaps.tn/v-tile/streets.json?api_key=YOUR_API_KEY',
dark:  'https://tiles.tmaps.tn/v-tile/dark.json?api_key=YOUR_API_KEY',
};

document.querySelector('#toggle-dark').addEventListener('click', () => {
const current = map.getStyle().name;
map.setStyle(current === 'dark' ? styles.light : styles.dark);
});

Intégration mobile

MapLibre Native (iOS, Android) et MapLibre RN consomment directement le style.json. Passez simplement l’URL complète à votre constructeur :

let url = URL(string: "https://tiles.tmaps.tn/v-tile/streets.json?api_key=YOUR_API_KEY")!
let mapView = MLNMapView(frame: view.bounds, styleURL: url)

val mapView = MapView(context)
mapView.getMapAsync { map ->
map.setStyle(Style.Builder().fromUri(
  "https://tiles.tmaps.tn/v-tile/streets.json?api_key=YOUR_API_KEY"
))
}

import MapLibreGL from '@maplibre/maplibre-react-native';

<MapLibreGL.MapView
styleURL="https://tiles.tmaps.tn/v-tile/streets.json?api_key=YOUR_API_KEY"
style={{ flex: 1 }}
/>

Personnaliser un style

Le JSON renvoyé suit la Mapbox Style Spec, donc vous pouvez :

1. Le télécharger une fois (curl https://tiles.tmaps.tn/v-tile/streets.json?api_key=…).
2. Modifier les layers (couleurs, polices, visibilité par zoom).
3. Recharger votre version personnalisée (en local ou hébergée chez vous), en gardant l’URL des tuiles .pbf d’origine.

Caractéristiques

• Format de tuiles : Mapbox Vector Tiles (.pbf)
• Plage de zoom : 0 → 18
• Couverture : monde entier, niveaux de détail enrichis pour la Tunisie
• Glyphs et sprites : hébergés par TMaps, références incluses dans le style.json

Obtenir votre clé

Pour tester l’API et l’utiliser en production, créez un compte puis générez une clé API depuis la console TMaps. Pensez à ajouter localhost à vos domaines autorisés si vous testez en local depuis un navigateur.

L’endpoint Forward Geocoding convertit une adresse en texte libre en coordonnées géographiques (latitude / longitude). Il est calibré pour le découpage administratif tunisien (commune, délégation, gouvernorat).

Endpoint

Paramètres

Exemple de requête

curl "https://api.tmaps.tn/geocoding/forward?q=Avenue%20Habib%20Bourguiba%2C%20Tunis&country=TN&limit=3&lang=fr&api_key=YOUR_API_KEY"

const url = new URL('https://api.tmaps.tn/geocoding/forward');
url.searchParams.set('q', 'Avenue Habib Bourguiba, Tunis');
url.searchParams.set('country', 'TN');
url.searchParams.set('limit', '3');
url.searchParams.set('lang', 'fr');
url.searchParams.set('api_key', 'YOUR_API_KEY');

const res = await fetch(url);
const data = await res.json();

const best = data.results[0];
console.log(best.lat, best.lng, best.confidence);

import requests

res = requests.get('https://api.tmaps.tn/geocoding/forward', params={
  'q': 'Avenue Habib Bourguiba, Tunis',
  'country': 'TN',
  'limit': 3,
  'lang': 'fr',
  'api_key': 'YOUR_API_KEY',
})
data = res.json()
best = data['results'][0]
print(best['lat'], best['lng'], best['confidence'])

<?php
$query = http_build_query([
  'q'       => 'Avenue Habib Bourguiba, Tunis',
  'country' => 'TN',
  'limit'   => 3,
  'lang'    => 'fr',
  'api_key' => 'YOUR_API_KEY',
]);
$res = file_get_contents("https://api.tmaps.tn/geocoding/forward?$query");
$data = json_decode($res, true);
$best = $data['results'][0];
echo "{$best['lat']}, {$best['lng']} ({$best['confidence']})";

Réponse

{
"query": "Avenue Habib Bourguiba, Tunis",
"results": [
  {
    "lat": 36.8002,
    "lng": 10.1815,
    "formatted": "Avenue Habib Bourguiba, 1001 Tunis, Tunisie",
    "confidence": 0.95,
    "type": "street",
    "components": {
      "street": "Avenue Habib Bourguiba",
      "postcode": "1001",
      "commune": "Tunis",
      "delegation": "Tunis Médina",
      "governorate": "Tunis",
      "country": "TN"
    },
    "bbox": [10.1750, 36.7980, 10.1880, 36.8030]
  }
]
}

Champs renvoyés

Cas d’usage

• E-commerce : valider et géocoder les adresses de livraison à la saisie.
• Annuaires : enrichir une fiche entreprise avec sa position GPS et sa délégation.
• Recherche : autocomplete d’adresse via une intégration typeahead.

Erreurs

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

L’endpoint Reverse Geocoding prend une paire lat / lng et renvoie l’adresse postale correspondante avec sa décomposition administrative (commune, délégation, gouvernorat).

Endpoint

Paramètres

Exemple de requête

curl "https://api.tmaps.tn/geocoding/reverse?lat=36.8002&lng=10.1815&lang=fr&api_key=YOUR_API_KEY"

const url = new URL('https://api.tmaps.tn/geocoding/reverse');
url.searchParams.set('lat', '36.8002');
url.searchParams.set('lng', '10.1815');
url.searchParams.set('lang', 'fr');
url.searchParams.set('api_key', 'YOUR_API_KEY');

const res = await fetch(url);
const { results } = await res.json();
console.log(results[0].formatted);
// → "Avenue Habib Bourguiba, 1001 Tunis, Tunisie"

import requests

res = requests.get('https://api.tmaps.tn/geocoding/reverse', params={
  'lat': 36.8002,
  'lng': 10.1815,
  'lang': 'fr',
  'api_key': 'YOUR_API_KEY',
})
print(res.json()['results'][0]['formatted'])

<?php
$query = http_build_query([
  'lat'     => 36.8002,
  'lng'     => 10.1815,
  'lang'    => 'fr',
  'api_key' => 'YOUR_API_KEY',
]);
$res = file_get_contents("https://api.tmaps.tn/geocoding/reverse?$query");
$data = json_decode($res, true);
echo $data['results'][0]['formatted'];

Réponse

{
"query": { "lat": 36.8002, "lng": 10.1815 },
"results": [
  {
    "lat": 36.8002,
    "lng": 10.1815,
    "formatted": "Avenue Habib Bourguiba, 1001 Tunis, Tunisie",
    "distance": 4.2,
    "type": "address",
    "components": {
      "street": "Avenue Habib Bourguiba",
      "postcode": "1001",
      "commune": "Tunis",
      "delegation": "Tunis Médina",
      "governorate": "Tunis",
      "country": "TN"
    }
  }
]
}

Champs renvoyés

Cas d’usage

• Apps mobiles : afficher l’adresse de la position GPS de l’utilisateur.
• Tournées d’inspection : associer chaque point GPS terrain à une adresse cadastrale.
• Logs et audits : enrichir des coordonnées brutes avec le contexte administratif.

Erreurs

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

L’endpoint Nearby retourne les points d’intérêt (POI) situés autour d’un point GPS, triés par distance croissante. Il est calibré pour le contexte tunisien (commerces, services publics, transport, santé).

Endpoint

Paramètres

Catégories disponibles

Exemple de requête

curl "https://api.tmaps.tn/geocoding/nearby?lat=36.8002&lng=10.1815&radius=1500&categories=pharmacy,hospital&limit=10&api_key=YOUR_API_KEY"

const url = new URL('https://api.tmaps.tn/geocoding/nearby');
url.searchParams.set('lat', '36.8002');
url.searchParams.set('lng', '10.1815');
url.searchParams.set('radius', '1500');
url.searchParams.set('categories', 'pharmacy,hospital');
url.searchParams.set('limit', '10');
url.searchParams.set('api_key', 'YOUR_API_KEY');

const res = await fetch(url);
const { results } = await res.json();

results.forEach((p) => {
console.log(`${p.name} — ${p.distance} m`);
});

import requests

res = requests.get('https://api.tmaps.tn/geocoding/nearby', params={
  'lat': 36.8002,
  'lng': 10.1815,
  'radius': 1500,
  'categories': 'pharmacy,hospital',
  'limit': 10,
  'api_key': 'YOUR_API_KEY',
})
for p in res.json()['results']:
  print(f"{p['name']} — {p['distance']} m")

Réponse

{
"query": { "lat": 36.8002, "lng": 10.1815, "radius": 1500 },
"count": 3,
"results": [
  {
    "id": "poi_42018",
    "name": "Pharmacie de l'Avenue",
    "category": "pharmacy",
    "lat": 36.7995,
    "lng": 10.1820,
    "distance": 75,
    "address": "Avenue Habib Bourguiba, Tunis",
    "phone": "+216 71 245 678",
    "opening_hours": "Lun-Sam 08:30-19:00"
  },
  {
    "id": "poi_77110",
    "name": "Hôpital Charles Nicolle",
    "category": "hospital",
    "lat": 36.8000,
    "lng": 10.1815,
    "distance": 220,
    "address": "Boulevard du 9 Avril 1938, Tunis",
    "phone": "+216 71 562 000",
    "opening_hours": "24/7"
  },
  {
    "id": "poi_88231",
    "name": "Pharmacie Centrale",
    "category": "pharmacy",
    "lat": 36.8021,
    "lng": 10.1798,
    "distance": 310,
    "address": "Rue de la Liberté, Tunis"
  }
]
}

Champs renvoyés

Cas d’usage

• Annuaires locaux : afficher les commerces / services autour d’une adresse saisie.
• Apps de tourisme : suggérer les POI culturels autour de la position de l’utilisateur.
• Immobilier : enrichir une fiche annonce avec les écoles et commerces à 5 minutes à pied.
• Géomarketing : analyser la concurrence autour d’un point de vente potentiel.

Erreurs

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

L’endpoint Direction calcule l’itinéraire optimal entre un point de départ et un ou plusieurs points d’arrivée (waypoints). Il renvoie la distance totale, la durée estimée, la géométrie et — sur demande — les instructions turn-by-turn.

Endpoint

Deux variantes équivalentes :

Utilisez GET pour les itinéraires simples (2 points). Utilisez POST dès que vous avez plusieurs waypoints ou des options avancées.

Paramètres

Exemple — GET (simple)

curl "https://api.tmaps.tn/routing/direction?from=36.8002,10.1815&to=36.8528,10.3261&profile=driving&api_key=YOUR_API_KEY"

const url = new URL('https://api.tmaps.tn/routing/direction');
url.searchParams.set('from', '36.8002,10.1815');  // Tunis centre
url.searchParams.set('to', '36.8528,10.3261');    // Carthage
url.searchParams.set('profile', 'driving');
url.searchParams.set('api_key', 'YOUR_API_KEY');

const res = await fetch(url);
const data = await res.json();
console.log(`${data.distance} m, ${data.duration} s`);

Exemple — POST (multi-waypoints + steps)

curl -X POST "https://api.tmaps.tn/routing/direction?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "waypoints": [
    { "lat": 36.7992, "lng": 10.1709 },
    { "lat": 36.8094, "lng": 10.1400 },
    { "lat": 36.8528, "lng": 10.3261 }
  ],
  "profile": "driving",
  "steps": true,
  "geometry": "geojson"
}'

const res = await fetch(
'https://api.tmaps.tn/routing/direction?api_key=YOUR_API_KEY',
{
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    waypoints: [
      { lat: 36.7992, lng: 10.1709 }, // Médina de Tunis
      { lat: 36.8094, lng: 10.1400 }, // Musée du Bardo
      { lat: 36.8528, lng: 10.3261 }, // Carthage
    ],
    profile: 'driving',
    steps: true,
    geometry: 'geojson',
  }),
}
);
const data = await res.json();
console.log(`${data.distance / 1000} km en ${Math.round(data.duration / 60)} min`);

import requests

res = requests.post(
  'https://api.tmaps.tn/routing/direction',
  params={'api_key': 'YOUR_API_KEY'},
  json={
      'waypoints': [
          {'lat': 36.7992, 'lng': 10.1709},
          {'lat': 36.8094, 'lng': 10.1400},
          {'lat': 36.8528, 'lng': 10.3261},
      ],
      'profile': 'driving',
      'steps': True,
      'geometry': 'geojson',
  },
)
data = res.json()
print(f"{data['distance'] / 1000} km en {round(data['duration'] / 60)} min")

Réponse

{
"distance": 19420,
"duration": 1830,
"geometry": {
  "type": "LineString",
  "coordinates": [
    [10.1709, 36.7992],
    [10.1655, 36.8021],
    [10.1400, 36.8094],
    [10.2630, 36.8420],
    [10.3261, 36.8528]
  ]
},
"legs": [
  {
    "distance": 4870,
    "duration": 540,
    "from": { "lat": 36.7992, "lng": 10.1709 },
    "to":   { "lat": 36.8094, "lng": 10.1400 },
    "steps": [
      { "instruction": "Continuez sur Avenue Habib Bourguiba", "distance": 320, "duration": 50 },
      { "instruction": "Tournez à droite sur Rue de Carthage", "distance": 180, "duration": 30 }
    ]
  },
  {
    "distance": 14550,
    "duration": 1290,
    "from": { "lat": 36.8094, "lng": 10.1400 },
    "to":   { "lat": 36.8528, "lng": 10.3261 },
    "steps": [
      { "instruction": "Prenez l'autoroute A1 direction Carthage", "distance": 12300, "duration": 850 }
    ]
  }
]
}

Champs renvoyés

Profils de transport

Cas d’usage

• Apps de livraison : itinéraire restaurant → client avec ETA.
• Tourisme : enchaînement de sites avec durée totale.
• Mobilité douce : profils walking et cycling pour des apps urbaines.
• B2B logistique : profil truck pour les flottes de poids lourds.

Erreurs

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

L’endpoint Optimized Routing réordonne une liste de points pour calculer la tournée optimale — typiquement l’ordre de livraison qui minimise la distance ou la durée totale. C’est une solution au problème du voyageur de commerce (TSP).

Endpoint

Paramètres

Exemple — Tournée de livraison

curl -X POST "https://api.tmaps.tn/routing/optimized?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "origin":      { "lat": 36.8355, "lng": 10.2261 },
  "waypoints": [
    { "lat": 36.8485, "lng": 10.1712 },
    { "lat": 36.8644, "lng": 10.1808 },
    { "lat": 36.8664, "lng": 10.1938 },
    { "lat": 36.8779, "lng": 10.2024 }
  ],
  "profile":     "driving",
  "optimize":    "duration",
  "roundtrip":   true
}'

const res = await fetch(
'https://api.tmaps.tn/routing/optimized?api_key=YOUR_API_KEY',
{
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    origin: { lat: 36.8355, lng: 10.2261 }, // Dépôt RapidoTN
    waypoints: [
      { lat: 36.8485, lng: 10.1712 }, // Client A
      { lat: 36.8644, lng: 10.1808 }, // Client B
      { lat: 36.8664, lng: 10.1938 }, // Client C
      { lat: 36.8779, lng: 10.2024 }, // Client D
    ],
    profile: 'driving',
    optimize: 'duration',
    roundtrip: true,
  }),
}
);
const data = await res.json();
console.log('Ordre optimal :', data.order);
console.log(`${data.distance / 1000} km, ${Math.round(data.duration / 60)} min`);

import requests

res = requests.post(
  'https://api.tmaps.tn/routing/optimized',
  params={'api_key': 'YOUR_API_KEY'},
  json={
      'origin': {'lat': 36.8355, 'lng': 10.2261},
      'waypoints': [
          {'lat': 36.8485, 'lng': 10.1712},
          {'lat': 36.8644, 'lng': 10.1808},
          {'lat': 36.8664, 'lng': 10.1938},
          {'lat': 36.8779, 'lng': 10.2024},
      ],
      'profile': 'driving',
      'optimize': 'duration',
      'roundtrip': True,
  },
)
data = res.json()
print('Ordre :', data['order'])
print(f"{data['distance'] / 1000} km, {round(data['duration'] / 60)} min")

Réponse

{
"distance": 14820,
"duration": 1680,
"order": [2, 0, 3, 1],
"geometry": "ahvqEi}_iL...",
"legs": [
  {
    "from":     { "lat": 36.8355, "lng": 10.2261 },
    "to":       { "lat": 36.8664, "lng": 10.1938 },
    "distance": 3120,
    "duration": 380
  },
  {
    "from":     { "lat": 36.8664, "lng": 10.1938 },
    "to":       { "lat": 36.8485, "lng": 10.1712 },
    "distance": 2940,
    "duration": 320
  }
]
}

Lecture de la réponse

• order est un tableau d’indices (zéro-indexés) qui décrit l’ordre optimisé dans lequel visiter les waypoints d’origine. Dans l’exemple : visitez d’abord waypoints[2], puis waypoints[0], puis waypoints[3], puis waypoints[1].
• distance et duration sont les totaux pour la tournée complète (origine → tous les waypoints dans l’ordre optimisé → éventuelle destination ou retour).
• legs détaille chaque segment dans l’ordre optimisé.

Cas d’usage

• Livraison express : minimiser la distance pour un livreur avec 10 colis.
• Tournées d’inspection : ordre optimal des sites à visiter par un agent terrain.
• Maintenance : tournées techniciens (réseau, équipement, etc.).

Limites

• Max 50 waypoints par requête. Pour les flottes plus larges, découpez en lots et appelez l’API plusieurs fois.
• Pas de fenêtres temporelles ni de capacités dans cette version (voir l’encart au-dessus).

Erreurs

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

L’endpoint Isochrone calcule la zone atteignable depuis un point d’origine en un certain temps (en minutes) ou une certaine distance (en kilomètres). Le résultat est un polygone GeoJSON prêt à afficher sur une carte.

Endpoint

Paramètres

Exemple — zone de chalandise 15 minutes en voiture

curl -X POST "https://api.tmaps.tn/routing/isochrone?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "origin":   { "lat": 36.8002, "lng": 10.1815 },
  "contours": [{ "time": 15 }],
  "profile":  "driving"
}'

const res = await fetch(
'https://api.tmaps.tn/routing/isochrone?api_key=YOUR_API_KEY',
{
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    origin: { lat: 36.8002, lng: 10.1815 },
    contours: [{ time: 15 }],
    profile: 'driving',
  }),
}
);
const geojson = await res.json();

// Affichage sur MapLibre
map.addSource('catchment', { type: 'geojson', data: geojson });
map.addLayer({
id: 'catchment-fill',
type: 'fill',
source: 'catchment',
paint: { 'fill-color': '#22c55e', 'fill-opacity': 0.3 },
});

import requests

res = requests.post(
  'https://api.tmaps.tn/routing/isochrone',
  params={'api_key': 'YOUR_API_KEY'},
  json={
      'origin': {'lat': 36.8002, 'lng': 10.1815},
      'contours': [{'time': 15}],
      'profile': 'driving',
  },
)
geojson = res.json()
# → ready-to-render FeatureCollection

Exemple — isochrones empilées (5 / 10 / 15 min)

const res = await fetch(
'https://api.tmaps.tn/routing/isochrone?api_key=YOUR_API_KEY',
{
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    origin: { lat: 36.8002, lng: 10.1815 },
    contours: [
      { time: 5 },
      { time: 10 },
      { time: 15 },
    ],
    profile: 'driving',
    colors: ['#22c55e', '#f59e0b', '#ef4444'],
  }),
}
);
const geojson = await res.json();
// → 3 features dans le FeatureCollection

Réponse

La réponse est un FeatureCollection GeoJSON : une feature par contour demandé, dans le même ordre que la requête.

{
"type": "FeatureCollection",
"features": [
  {
    "type": "Feature",
    "properties": {
      "contour": 15,
      "metric": "time",
      "color": "#22c55e"
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [[
        [10.0801, 36.8412],
        [10.1240, 36.8650],
        [10.2308, 36.8580],
        [10.2620, 36.8011],
        [10.2210, 36.7530],
        [10.1100, 36.7480],
        [10.0801, 36.8412]
      ]]
    }
  }
]
}

Champs renvoyés

Cas d’usage

• Géomarketing & retail : zones de chalandise pour ouvrir un nouveau point de vente.
• Immobilier : afficher « toutes les écoles à 10 min à pied de ce bien ».
• Logistique : zones desservables par un dépôt en moins de 30 min.
• Urgences : couverture d’une caserne / d’un hôpital en 5 min.

Erreurs

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

L’endpoint Distance Matrix calcule en une seule requête la distance et la durée entre chaque paire (origine × destination). Idéal pour :

• trouver la ressource la plus proche (livreur, ambulance, expert…),
• afficher un tableau « durée d’un trajet » dans une UI,
• alimenter un solveur d’optimisation côté client.

Endpoint

Paramètres

Exemple — Trouver l’ambulance la plus proche

curl -X POST "https://api.tmaps.tn/distance-matrix?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "origins": [
    { "lat": 36.8280, "lng": 10.2100 },
    { "lat": 36.8450, "lng": 10.1850 },
    { "lat": 36.8094, "lng": 10.1400 }
  ],
  "destinations": [
    { "lat": 36.8000, "lng": 10.1815 }
  ],
  "profile": "driving"
}'

const ambulances = [
{ id: 'A-01', lat: 36.8280, lng: 10.2100 },
{ id: 'A-02', lat: 36.8450, lng: 10.1850 },
{ id: 'A-03', lat: 36.8094, lng: 10.1400 },
];
const patient = { lat: 36.8000, lng: 10.1815 };

const res = await fetch(
'https://api.tmaps.tn/distance-matrix?api_key=YOUR_API_KEY',
{
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    origins: ambulances.map(({ lat, lng }) => ({ lat, lng })),
    destinations: [patient],
    profile: 'driving',
  }),
}
);

const { durations } = await res.json();
const fastestIdx = durations
.map((row) => row[0])
.reduce((best, t, i, arr) => (t < arr[best] ? i : best), 0);

console.log('Ambulance la plus proche :', ambulances[fastestIdx].id);

import requests

ambulances = [
  {'id': 'A-01', 'lat': 36.8280, 'lng': 10.2100},
  {'id': 'A-02', 'lat': 36.8450, 'lng': 10.1850},
  {'id': 'A-03', 'lat': 36.8094, 'lng': 10.1400},
]
patient = {'lat': 36.8000, 'lng': 10.1815}

res = requests.post(
  'https://api.tmaps.tn/distance-matrix',
  params={'api_key': 'YOUR_API_KEY'},
  json={
      'origins':      [{'lat': a['lat'], 'lng': a['lng']} for a in ambulances],
      'destinations': [patient],
      'profile':      'driving',
  },
)
durations = res.json()['durations']
fastest = min(range(len(durations)), key=lambda i: durations[i][0])
print('Plus proche :', ambulances[fastest]['id'])

Réponse

{
"durations": [
  [320],
  [180],
  [420]
],
"distances": [
  [3120],
  [1840],
  [4250]
],
"origins": [
  { "lat": 36.8280, "lng": 10.2100 },
  { "lat": 36.8450, "lng": 10.1850 },
  { "lat": 36.8094, "lng": 10.1400 }
],
"destinations": [
  { "lat": 36.8000, "lng": 10.1815 }
]
}

Lecture de la matrice

• durations[i][j] = durée en secondes depuis origins[i] jusqu’à destinations[j].
• distances[i][j] = distance en mètres sur la même paire.
• origins et destinations sont renvoyés dans le même ordre que la requête, pour faciliter les corrélations côté client.

Cas d’usage

• Affectation : ambulance / livreur / expert le plus proche d’un nouveau dossier.
• Choix de site : comparer la durée de trajet de N candidats vers M cibles.
• Géomarketing : table de durées « point de vente × clients » pour un solveur de zone.

Erreurs

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

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

Paramètres

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

<img
src="https://api.tmaps.tn/maps/static?center=36.8528,10.3261&zoom=15&size=800x500&marker=36.8528,10.3261|red|H&api_key=YOUR_API_KEY"
alt="Carte de la propriété"
width="800"
height="500"
/>

const url = new URL('https://api.tmaps.tn/maps/static');
url.searchParams.set('center', '36.8528,10.3261');
url.searchParams.set('zoom', '15');
url.searchParams.set('size', '800x500');
url.searchParams.set('style', 'streets');
url.searchParams.append('marker', '36.8528,10.3261|red|H');
url.searchParams.set('api_key', 'YOUR_API_KEY');

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

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.

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

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

Toutes les erreurs renvoyées par l'API TMaps suivent un format JSON commun et utilisent les codes HTTP standard. Cette page liste les codes que vous pouvez rencontrer et leur signification.

Format des erreurs

Toute réponse d'erreur a un body JSON minimal, encodé en UTF-8 :

{
  "error": "missing api_key"
}

Le champ error contient un message court en anglais, exploitable pour le debug. Ce message peut évoluer dans le temps : ne le parsez pas pour piloter votre logique métier — utilisez le code HTTP.

Codes HTTP

Gérer les erreurs côté client

Reconnaître une erreur d'authentification

Les codes 401 et 403 sont des erreurs de configuration, pas d'usage : il ne sert à rien de retenter la requête. Vérifiez plutôt :

• 401 : la clé est-elle bien renseignée ? Active dans la console ?
• 403 : le domaine d'appel est-il dans la liste des domaines autorisés ? Si l'appel est server-side (sans Origin), le 403 ne devrait pas se produire.

Stratégie de retry

• 4xx : ne jamais retenter automatiquement (sauf 429).
• 429 : retry avec un backoff exponentiel (1 s, 2 s, 4 s) — max 3 tentatives.
• 5xx : retry avec un backoff exponentiel — max 3 tentatives.

Exemple — wrapper fetch avec retry

async function tmapsFetch(url, options = {}, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);

    // Pas d'erreur → on retourne
    if (res.ok) return res.json();

    // 4xx (sauf 429) → erreur définitive
    if (res.status >= 400 && res.status < 500 && res.status !== 429) {
      const body = await res.json().catch(() => ({}));
      throw new Error(`TMaps ${res.status} — ${body.error ?? 'unknown'}`);
    }

    // 429 ou 5xx → backoff exponentiel
    await new Promise((r) => setTimeout(r, 2 ** i * 1000));
  }
  throw new Error('TMaps: max retries reached');
}