Choisir une API de cartographie, c'est un engagement. Une fois le géocodage branché sur votre formulaire de livraison, votre CRM ou votre application de VTC, en changer coûte des semaines. La décision mérite donc mieux qu'une page commerciale lue en diagonale. Ce qu'il vous faut, ce sont de vraies réponses, sur vos propres adresses, avant que le premier sprint ne commence.
C'est pour cela que nous publions une collection Postman de TMaps. Elle couvre les tuiles de carte, la recherche d'adresse, le géocodage inverse et la recherche de lieux à proximité. Cet article ne détaille pas chaque clic (le tutoriel pas à pas s'en charge) : il explique comment une équipe peut s'en servir pour décider, puis pour garder un œil sur l'API une fois en production.
Pourquoi tester avant d'écrire la moindre ligne
Un développeur qui intègre une API sans l'avoir essayée découvre ses limites au pire moment : en recette, ou pire, quand un client signale que son adresse « n'existe pas ». Une demi-journée passée dans Postman évite ce scénario. Elle permet aussi à des profils non développeurs, un chef de projet ou une personne de l'équipe qualité, de se faire leur propre idée sans attendre qu'on leur monte un prototype.
Autre avantage, plus discret : la discussion change de nature. Au lieu de débattre d'une fiche produit, l'équipe compare des réponses JSON concrètes. Les désaccords se règlent plus vite quand tout le monde regarde la même chose.
Ce qu'il faut vraiment vérifier
La qualité des adresses tunisiennes
C'est le critère numéro un, et le seul que personne ne peut vérifier à votre place. Prenez une vingtaine d'adresses tirées de vos propres données : des commandes passées, des fiches clients, des tickets de support. Mélangez les cas faciles (une grande avenue de Tunis) et les cas pénibles : un quartier récent de la périphérie de Sfax, une adresse écrite en arabe, une autre en abrégé avec une faute de frappe. Passez-les dans la requête Forward geocoding et notez ce qui revient.
Chaque réponse contient l'adresse complète dans formatted, le point dans geometry.location et un score confidence. Ce score est précieux pour fixer une règle métier : en dessous d'un certain seuil, votre application peut demander au client de confirmer sa position sur la carte.
Le découpage commune, délégation, gouvernorat
Si votre logistique raisonne par zones, regardez de près les champs commune, delegation et governorate. Ils suivent le découpage administratif tunisien, sans que vous ayez à faire correspondre des catégories génériques à la réalité du pays. Vérifiez qu'ils tombent juste sur vos adresses de test, notamment aux limites entre deux délégations. C'est souvent là que se cachent les erreurs de tarification d'une livraison.
Faites aussi le chemin inverse. La requête Reverse geocoding prend des coordonnées et renvoie une adresse : utile pour juger ce qu'un livreur verrait s'il partageait sa position. La collection enchaîne d'ailleurs les requêtes toute seule, puisque le résultat d'une recherche d'adresse alimente automatiquement le géocodage inverse et la recherche à proximité.
Les temps de réponse
Postman affiche le temps de chaque requête à côté du code de statut. Lancez la même requête plusieurs fois, à des heures différentes, et notez les valeurs. Pour une autocomplétion dans un champ de saisie, quelques centaines de millisecondes font la différence entre une recherche fluide et une recherche qui agace. Le plus parlant reste de tester depuis le réseau de vos utilisateurs, en Tunisie, plutôt que depuis un serveur à l'étranger.
Ce que le paramétrage permet
L'onglet Params de chaque requête documente tous les paramètres. Les facultatifs, comme proximity, bbox ou type, sont déjà présents mais décochés. Activez-les un par un pour voir comment ils orientent les résultats : favoriser les adresses proches d'un point, ou limiter la recherche à une zone précise, par exemple.
Partager la collection dans l'équipe
Le bouton Run in Postman ci-dessus, ou l'espace de travail public, vous propose de copier la collection (Fork Collection). Copiez-la dans l'espace de travail de votre équipe plutôt que dans votre espace personnel : chacun retrouve alors les mêmes requêtes, et vous pouvez y ajouter vos propres adresses de test pour que toute l'équipe évalue sur la même base.
Un point d'hygiène à ne pas négliger : la clé API. Chaque membre crée la sienne sur la console TMaps et la saisit dans la variable api_key, en Current value. Cette valeur reste sur sa machine et n'est pas synchronisée avec l'espace de travail partagé. Personne ne se retrouve donc à publier par mégarde la clé d'un collègue.
Surveiller l'API en continu avec Newman
Une fois l'API adoptée, la collection garde son utilité. Elle contient déjà des tests : code de statut, forme de la réponse, résultats triés par distance pour la recherche à proximité. Newman, l'outil en ligne de commande de Postman, sait les exécuter sans interface, et donc dans votre intégration continue.
Les fichiers de la collection et de l'environnement se trouvent dans le dépôt tmaps-snippets. Dans GitHub Actions, après avoir enregistré votre clé comme secret TMAPS_API_KEY, une seule étape suffit :
- name: Vérifier l'API TMaps
run: npx newman run postman/TMaps-API.postman_collection.json -e postman/TMaps.postman_environment.json --env-var "api_key=${{ secrets.TMAPS_API_KEY }}"
Si un endpoint dont votre application dépend cesse de répondre comme prévu, le pipeline échoue et votre équipe le sait avant vos clients. Rien ne vous empêche ensuite d'ajouter vos propres assertions, par exemple sur une adresse critique pour votre activité.
Attention toutefois : Newman affiche l'URL complète de chaque requête, clé comprise. Sur un dépôt public, masquez la sortie ou utilisez une clé dédiée aux tests.
Une grille d'évaluation simple
Pour conclure votre évaluation, quelques questions suffisent souvent. Combien de vos adresses de test reviennent avec la bonne délégation ? Combien ont un score de confiance assez haut pour se passer d'une confirmation manuelle ? Les temps de réponse mesurés conviennent-ils à votre usage ? Si les réponses vous satisfont, l'intégration elle-même ira vite : les exemples de code et les démos sont sur examples.tmaps.tn, et la documentation complète sur tmaps.tn/documentation.
Vous voulez aller plus loin sur le géocodage lui-même ? La page API de géocodage pour la Tunisie présente le service en détail, et notre équipe répond à vos questions d'évaluation sur support@tmaps.tn.
