TMaps - Mapping API Tunisia

Authentication

How to pass your API key, how authorized domains (Origin/Referer) work, and how to call the API from a server.

Every request to the TMaps API must be authenticated with an API key (api_key), created from the TMaps console.

Key format

A TMaps API key looks like this:

ak_a1b2c3d4e5f607xxxXXXxXXxxXX

The ak_ prefix is followed by 32 hex characters. Treat your key as a password: don’t commit it to a public repository, and avoid logging it on the client side when possible.

Passing the key: api_key query parameter

All endpoints (GET and POST alike) accept the key via the api_key query parameter.

GET https://api.tmaps.tn/{endpoint}?api_key=YOUR_API_KEY&... 
curl "https://api.tmaps.tn/geocoding/forward?q=Tunis&api_key=YOUR_API_KEY"

No Authorization header

TMaps does not use an Authorization: Bearer … header. The key is always passed via the api_key query parameter, including for POST requests.

Authorized domains (Origin / Referer)

To prevent a key embedded in a website’s JavaScript from being reused elsewhere, you can restrict a key to a whitelist of domains in the console (under Authorized Domains).

For each request, the backend checks in order:

  1. The browser’s Origin header;
  2. As a fallback, the Referer header.

If either is present and doesn’t match any of the key’s authorized domains, the request is rejected with status 403:

403 Domain not authorized for this key 
{
"error": "domain not authorized"
}

Specific rules

  • No wildcards. *.mysite.tn is not accepted: add each subdomain explicitly (app.mysite.tn, admin.mysite.tn, …).
  • localhost must be added. For local development, add localhost (and 127.0.0.1 if you use it) to your domain list.
  • Multiple domains per key: a single key can be authorized on several domains.
  • Multiple keys per domain: a single domain can be authorized for several keys (e.g. one for production, one for staging).
  • HTTPS only: HTTP requests are systematically rejected with 403.

Server-side calls

When your code runs server-side (Node, PHP, Python, Go, mobile native…), Origin and Referer headers are absent. In that case, the authorized-domains list is ignored and the key works without restriction.

Security tip

For pure backend integrations, create a dedicated key with no authorized domain: it stays usable from your servers (no Origin) but is blocked in the browser if it ever leaks into a public repo.

Authentication errors

StatusCauseBody
401api_key missing, disabled or revoked{"error":"missing api_key"}
403Origin/Referer not whitelisted, or HTTP request{"error":"domain not authorized"}

See the full list on the Error codes page.

Best practices

  • One key per environment (dev / staging / prod) and per usage (frontend / backend).
  • Restrict browser-exposed keys to the exact list of your domains.
  • Disable suspicious keys immediately from the console (a disabled key can be re-enabled later or revoked permanently).
  • Monitor usage from the Usage tab of the console to catch abnormal spikes.