Géocodage direct (forward)

Convertissez une adresse libre en coordonnées GPS précises, avec un score de confiance et la décomposition (commune, délégation, gouvernorat).

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

GET https://api.tmaps.tn/geocoding/forward?q=...&api_key=YOUR_API_KEY

Paramètres

Paramètres de query

Param	Type	Requis	Défaut	Description
`q`	string	oui	—	Texte à géocoder. Peut être une adresse, un POI, une commune, une rue. Exemples : `Avenue Habib Bourguiba, Tunis`, `Médina de Tunis`.
`api_key`	string	oui	—	Votre clé API TMaps.
`country`	string	—	`TN`	Code ISO 3166-1 alpha-2 du pays cible (ex. `TN`). Restreint la recherche à ce pays.
`limit`	integer	—	`5`	Nombre maximum de résultats à renvoyer (1 → 20).
`lang`	string	—	`fr`	Langue des libellés et adresses formatées : `fr`, `en` ou `ar`.
`proximity`	string	—	—	Coordonnées `lat,lng` pour favoriser les résultats proches d'un point (ex. la position de l'utilisateur).
`bbox`	string	—	—	Boîte englobante `minLng,minLat,maxLng,maxLat` pour restreindre la recherche à une zone.
`type`	string	—	—	Filtre par type de résultat : `address`, `street`, `poi`, `locality`.

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"

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

Champ d'un résultat

Param	Type	Requis	Défaut	Description
`lat`	number	—	—	Latitude WGS84 en degrés décimaux.
`lng`	number	—	—	Longitude WGS84 en degrés décimaux.
`formatted`	string	—	—	Adresse complète formatée pour l'affichage.
`confidence`	number	—	—	Score de confiance entre `0` et `1`. Au-delà de `0.9`, considérez le résultat comme fiable.
`type`	string	—	—	Type d'objet géocodé : `address`, `street`, `poi`, `locality`.
`components`	object	—	—	Détail administratif : `street`, `postcode`, `commune`, `delegation`, `governorate`, `country`.
`bbox`	array	—	—	Boîte englobante du résultat `[minLng, minLat, maxLng, maxLat]`.

Filtrer par score de confiance

Pour des cas d’usage transactionnels (livraison, e-commerce), n’enregistrez les coordonnées que si confidence >= 0.85 et présentez à l’utilisateur les autres résultats à valider.

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

Statut	Cause
`400`	Paramètre `q` manquant ou vide
`401`	`api_key` manquant ou révoqué
`403`	Domaine non autorisé

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