Forward geocoding

Convert a free-text address into precise GPS coordinates with a confidence score and full breakdown (commune, delegation, governorate).

The Forward Geocoding endpoint converts a free-text address into geographic coordinates (latitude / longitude). It is calibrated for the Tunisian administrative breakdown (commune, delegation, governorate).

Endpoint

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

Parameters

Query parameters

Param	Type	Requis	Défaut	Description
`q`	string	oui	—	Text to geocode. Can be an address, a POI, a commune, a street. Examples: `Avenue Habib Bourguiba, Tunis`, `Médina de Tunis`.
`api_key`	string	oui	—	Your TMaps API key.
`country`	string	—	`TN`	ISO 3166-1 alpha-2 country code (e.g. `TN`). Restricts the search to that country.
`limit`	integer	—	`5`	Maximum number of results to return (1 → 20).
`lang`	string	—	`fr`	Language for labels and formatted addresses: `fr`, `en` or `ar`.
`proximity`	string	—	—	`lat,lng` coordinates to favor results close to a point (e.g. the user's location).
`bbox`	string	—	—	Bounding box `minLng,minLat,maxLng,maxLat` to restrict the search to a region.
`type`	string	—	—	Filter by result type: `address`, `street`, `poi`, `locality`.

Sample request

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

Response

{
"query": "Avenue Habib Bourguiba, Tunis",
"results": [
  {
    "lat": 36.8002,
    "lng": 10.1815,
    "formatted": "Avenue Habib Bourguiba, 1001 Tunis, Tunisia",
    "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]
  }
]
}

Returned fields

Result fields

Param	Type	Requis	Défaut	Description
`lat`	number	—	—	WGS84 latitude in decimal degrees.
`lng`	number	—	—	WGS84 longitude in decimal degrees.
`formatted`	string	—	—	Full formatted address for display.
`confidence`	number	—	—	Confidence score between `0` and `1`. Above `0.9`, treat the result as reliable.
`type`	string	—	—	Type of geocoded object: `address`, `street`, `poi`, `locality`.
`components`	object	—	—	Administrative breakdown: `street`, `postcode`, `commune`, `delegation`, `governorate`, `country`.
`bbox`	array	—	—	Bounding box of the result `[minLng, minLat, maxLng, maxLat]`.

Filter by confidence score

For transactional use cases (delivery, e-commerce), only persist the coordinates if confidence >= 0.85 and present the other results to the user for review.

Use cases

E-commerce: validate and geocode delivery addresses on input.
Directories: enrich a business listing with its GPS position and delegation.
Search: address autocomplete via a typeahead integration.

Errors

Status	Cause
`400`	Missing or empty `q`
`401`	Missing or revoked `api_key`
`403`	Domain not authorized

See Error codes for the full list.