TMaps API in Postman: Test Geocoding in 2 Minutes

Before writing a single line of code against a new API, most of us want to poke at it first and see what comes back. That's what the TMaps Postman collection is for: map tiles, address search, reverse geocoding and nearby places, each with documented parameters, example responses and tests.

Here's how to get your first response in about two minutes, and then how to automate the whole thing.

Step 1: get a key (30 seconds)

Create an API key in the TMaps console. It starts with ak_.

Postman calls the API from a server context, without an Origin header, so the key's authorized domains don't come into play here. Any valid key will do.

Step 2: fork the collection (30 seconds)

Click Run in Postman above, or open the public workspace, and choose Fork Collection. You now have your own copy of the collection in your own workspace.

The workspace README gives a quick overview of what's inside:

Step 3: set your key (30 seconds)

Open your forked collection, go to its Variables tab and add a variable called api_key, with your key as the Current value. If you prefer environments, you can also fork the TMaps environment from the public workspace and set api_key there.

That's the only setting. The collection adds the key to every request as an api_key query parameter. It's configured once in the collection's Authorization tab and every request inherits it. TMaps doesn't use an Authorization header.

Keep the key in Current value: it stays on your machine and isn't shared with your workspace.

Step 4: send your first request (30 seconds)

Open Geocoding, then Forward geocoding, and hit Send.

Each request comes with its own documentation: what it does, what it returns, and a link to the matching live demo.

The Params tab lists every parameter with a description. The optional ones (proximity, bbox, type) are already there, just unchecked. Tick them to try them out.

In the response you'll find the point in geometry.location, a formatted address, a confidence score and the Tunisian administrative breakdown (commune, delegation, governorate). No key yet? Open the saved example to see a real response:

Chaining requests

The test script of Forward geocoding saves the first result's coordinates in the lat and lng collection variables:

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);
}

So Reverse geocoding and Nearby search work straight away on the address you just found. No copying coordinates around by hand.

Every request also has a few tests (status code, response shape, results sorted by distance…). After sending, you'll see them in the Tests tab of the response.

Bonus: run it from the command line with Newman

The same collection runs outside Postman with Newman. The files live in the GitHub repository:

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"

Here's what a run looks like:

❏ Geocoding
↳ Forward geocoding
  GET https://api.tmaps.tn/geocoding/forward?q=Avenue Habib Bourguiba, Tunis&country=TN&limit=5&lang=fr&api_key=YOUR_API_KEY [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=YOUR_API_KEY [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=YOUR_API_KEY [200 OK, 2.38kB, 28ms]
  ✓  Status is 200
  ✓  Results are sorted by distance

│              assertions │                10 │                 0 │

In GitHub Actions

Store your key as a repository secret named TMAPS_API_KEY, then add a step:

- 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 }}"

Now your pipeline fails as soon as an endpoint your app relies on stops answering the way it should.

One word of caution: Newman prints full request URLs, key included. Don't run it with a real key in public CI logs, or mask the output first.

What's in the collection

Folder	Request	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

Going further

• Geocoding API for Tunisia: www.tmaps.tn/en/geocoding
• Public Postman workspace: postman.com/tmaps-tn/tmaps-api
• Live demos in the browser: examples.tmaps.tn
• Source code, MIT licensed: github.com/tmaps-tn/tmaps-snippets
• Documentation: tmaps.tn/documentation

Questions or feedback? Leave a comment or write to [e-mail].