Recherche à proximité (nearby)

Trouvez les points d'intérêt (POI) autour d'un point GPS, filtrables par catégorie : restaurants, écoles, hôpitaux, transports...

L’endpoint Nearby retourne les points d’intérêt (POI) situés autour d’un point GPS, triés par distance croissante. Il est calibré pour le contexte tunisien (commerces, services publics, transport, santé).

Endpoint

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

Paramètres

Paramètres de query

Param	Type	Requis	Défaut	Description
`lat`	number	oui	—	Latitude du centre de la recherche.
`lng`	number	oui	—	Longitude du centre de la recherche.
`radius`	integer	oui	—	Rayon de recherche en mètres (max `10000`).
`api_key`	string	oui	—	Votre clé API TMaps.
`categories`	string	—	—	Filtre par catégories, séparées par une virgule (ex. `restaurant,pharmacy`). Voir la liste ci-dessous.
`q`	string	—	—	Filtre textuel sur le nom du POI (ex. `carrefour`).
`limit`	integer	—	`20`	Nombre maximum de résultats (1 → 100).
`lang`	string	—	`fr`	Langue des libellés : `fr`, `en` ou `ar`.

Catégories disponibles

Catégorie	Description
`restaurant`	Restaurants, fast-food, snacks
`cafe`	Cafés et salons de thé
`school`	Écoles, lycées, universités
`hospital`	Hôpitaux, cliniques
`pharmacy`	Pharmacies
`bank`	Banques, distributeurs
`atm`	Distributeurs automatiques (ATM)
`fuel`	Stations-service
`hotel`	Hôtels et hébergements
`parking`	Parkings publics et privés
`transit`	Stations de bus, métro, train, taxis
`municipality`	Mairies et services municipaux
`health`	Centres de santé, laboratoires
`education`	Tous types d’établissements éducatifs
`shopping`	Centres commerciaux, supermarchés, boutiques
`culture`	Musées, théâtres, cinémas, sites historiques
`mosque`	Mosquées
`place_of_worship`	Lieux de culte (toutes confessions)

Combiner plusieurs catégories

Vous pouvez passer plusieurs catégories séparées par une virgule : categories=restaurant,cafe,bakery. La recherche fait une union (OR).

Exemple de requête

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"

Réponse

{
"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": "Lun-Sam 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"
  }
]
}

Champs renvoyés

Champ d'un POI

Param	Type	Requis	Défaut	Description
`id`	string	—	—	Identifiant stable du POI dans la base TMaps.
`name`	string	—	—	Nom commercial du POI.
`category`	string	—	—	Catégorie (voir liste ci-dessus).
`lat`	number	—	—	Latitude du POI.
`lng`	number	—	—	Longitude du POI.
`distance`	number	—	—	Distance en mètres depuis le point de recherche.
`address`	string	—	—	Adresse formatée du POI.
`phone`	string	—	—	Téléphone (optionnel).
`opening_hours`	string	—	—	Horaires d'ouverture (optionnel, format libre).

Cas d’usage

Annuaires locaux : afficher les commerces / services autour d’une adresse saisie.
Apps de tourisme : suggérer les POI culturels autour de la position de l’utilisateur.
Immobilier : enrichir une fiche annonce avec les écoles et commerces à 5 minutes à pied.
Géomarketing : analyser la concurrence autour d’un point de vente potentiel.

Erreurs

Statut	Cause
`400`	`lat`, `lng` ou `radius` manquant, ou `radius` au-delà de `10000`
`401`	`api_key` manquant ou révoqué
`403`	Domaine non autorisé

Voir Codes d’erreur pour la liste complète.