Nearby search

Find points of interest (POI) around a GPS point, filterable by category: restaurants, schools, hospitals, transit...

The Nearby endpoint returns the points of interest (POI) around a GPS point, sorted by ascending distance. It is calibrated for the Tunisian context (commerce, public services, transit, healthcare).

Endpoint

GET https://api.tmaps.tn/geocoding/nearby?lat=...&lng=...&radius=...&api_key=YOUR_API_KEY

Parameters

Query parameters

Param	Type	Requis	Défaut	Description
`lat`	number	oui	—	Latitude of the search center.
`lng`	number	oui	—	Longitude of the search center.
`radius`	integer	oui	—	Search radius in meters (max `10000`).
`api_key`	string	oui	—	Your TMaps API key.
`categories`	string	—	—	Comma-separated list of categories (e.g. `restaurant,pharmacy`). See the list below.
`q`	string	—	—	Text filter on the POI name (e.g. `carrefour`).
`limit`	integer	—	`20`	Maximum number of results (1 → 100).
`lang`	string	—	`fr`	Language for labels: `fr`, `en` or `ar`.

Available categories

Category	Description
`restaurant`	Restaurants, fast-food, snack bars
`cafe`	Cafés and tea rooms
`school`	Schools, high schools, universities
`hospital`	Hospitals, clinics
`pharmacy`	Pharmacies
`bank`	Banks and ATMs
`atm`	ATMs
`fuel`	Gas stations
`hotel`	Hotels and accommodations
`parking`	Public and private parking
`transit`	Bus, metro, train and taxi stations
`municipality`	Town halls and municipal services
`health`	Health centers, laboratories
`education`	All types of educational institutions
`shopping`	Shopping centers, supermarkets, shops
`culture`	Museums, theaters, cinemas, historical sites
`mosque`	Mosques
`place_of_worship`	Places of worship (all faiths)

Combine multiple categories

You can pass several categories separated by a comma: categories=restaurant,cafe,bakery. The search performs a union (OR).

Sample request

curl "https://api.tmaps.tn/geocoding/nearby?lat=36.8002&lng=10.1815&radius=1500&categories=pharmacy,hospital&limit=10&api_key=YOUR_API_KEY"

Response

{
"query": { "lat": 36.8002, "lng": 10.1815, "radius": 1500 },
"count": 3,
"results": [
  {
    "id": "poi_42018",
    "name": "Pharmacie de l'Avenue",
    "category": "pharmacy",
    "lat": 36.7995,
    "lng": 10.1820,
    "distance": 75,
    "address": "Avenue Habib Bourguiba, Tunis",
    "phone": "+216 71 245 678",
    "opening_hours": "Mon-Sat 08:30-19:00"
  },
  {
    "id": "poi_77110",
    "name": "Hôpital Charles Nicolle",
    "category": "hospital",
    "lat": 36.8000,
    "lng": 10.1815,
    "distance": 220,
    "address": "Boulevard du 9 Avril 1938, Tunis",
    "phone": "+216 71 562 000",
    "opening_hours": "24/7"
  },
  {
    "id": "poi_88231",
    "name": "Pharmacie Centrale",
    "category": "pharmacy",
    "lat": 36.8021,
    "lng": 10.1798,
    "distance": 310,
    "address": "Rue de la Liberté, Tunis"
  }
]
}

Returned fields

POI fields

Param	Type	Requis	Défaut	Description
`id`	string	—	—	Stable identifier of the POI in the TMaps database.
`name`	string	—	—	Trade name of the POI.
`category`	string	—	—	Category (see list above).
`lat`	number	—	—	POI latitude.
`lng`	number	—	—	POI longitude.
`distance`	number	—	—	Distance in meters from the search point.
`address`	string	—	—	POI formatted address.
`phone`	string	—	—	Phone number (optional).
`opening_hours`	string	—	—	Opening hours (optional, free format).

Use cases

Local directories: show businesses / services around a typed-in address.
Travel apps: suggest cultural POIs around the user’s location.
Real estate: enrich a listing page with schools and shops within 5 minutes’ walk.
Geomarketing: analyze the competition around a potential point of sale.

Errors

Status	Cause
`400`	Missing `lat`, `lng` or `radius`, or `radius` greater than `10000`
`401`	Missing or revoked `api_key`
`403`	Domain not authorized

See Error codes for the full list.