Tester l'API TMaps dans Postman en 2 minutes

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 à [e-mail].