TMaps API examples / 04

Address search (forward geocoding)

Type an address, a street or a place in Tunisia. The TMaps Forward Geocoding API returns its GPS coordinates, a confidence score and the commune, delegation and governorate.

Results update as you type and favour places near the map center.

    API request 
    GET https://api.tmaps.tn/geocoding/forward?q=Avenue+Habib+Bourguiba%2C+Tunis&country=TN&limit=5&api_key=YOUR_API_KEY

    How it works

    1. Each keystroke (debounced by 300 ms) sends GET /geocoding/forward with the text in q.
    2. country=TN limits results to Tunisia and proximity favours places near the map center.
    3. A pending request is cancelled with AbortController when a new one starts, so old results never overwrite new ones.
    4. Click a result to place it on the map. Its bbox is used to zoom to the right level.

    Arabic and Tunisian Arabizi

    • Type in Arabic (نهج مرسيليا) and set the language to Arabic: lang=ar returns the addresses in Arabic, shown right-to-left with dir="auto".
    • Tunisian words and Arabizi digits are understood: nahj (rue), zan9a (impasse), chare3 (avenue), and 3, 5, 7, 9 for ع, خ, ح, ق. Try 9asr said or 3in zaghouan.
    • When the text contains these, the page sends the raw and a normalized query in parallel and merges the results. Numbers (4014) and road names (RN9) are left untouched.

    Good to know

    • confidence goes from 0 to 1. For deliveries or e-commerce, only save coordinates when it is at least 0.85 and ask the user to confirm otherwise.
    • The point is in geometry.location and components gives the Tunisian administrative breakdown: street, commune, delegation, governorate.
    • type filters results: address, street, poi or locality.

    Forward Geocoding docs · Source on GitHub