API Tiers-Lieux

Une API REST pour rechercher et accéder aux données des tiers-lieux avec recherche plein texte et filtres géographiques.

À quoi ça sert ?

L’API Tiers-Lieux est le point d’entrée programmatique vers les données du recensement. Elle permet à n’importe quelle application, site web ou partenaire d’interroger la base de données des tiers-lieux de manière structurée et performante.

Les données servies par l’API reflètent le contenu des fiches d’identité renseignées par les tiers-lieux dans Grist. L’API est une application 100% serveur : elle ne comporte pas d’interface graphique propre, elle expose uniquement des points d’accès REST consommés par les autres outils (annuaire, portail recensement, etc.).

Principe de fonctionnement

L’API est construite avec FastAPI (Python) et s’appuie sur Meilisearch comme moteur de recherche. Les données proviennent de Grist et sont synchronisées en temps réel via des webhooks, avec une synchronisation complète toutes les 24 heures en complément.

Les fonctionnalités principales :

  • Recherche plein texte sur le nom, le gestionnaire, la ville, la description
  • Filtrage géographique par rayon autour de coordonnées GPS
  • Filtres combinables : région, département, ville, famille, labels, reconnaissances, type de structure, état du projet, activités, surface, date d’ouverture
  • Proxy de logos pour servir les images stockées dans Grist

Limites d’usage

  • 5 requêtes par seconde en moyenne par adresse IP, avec des rafales de 20 tolérées ; au-delà, l’API répond 429 (trop de requêtes).
  • Les outils hébergés sur le même serveur (annuaire, portail du recensement) ne sont pas limités.
  • Réponses compressées en gzip : la liste complète des lieux pèse moins de 1 Mo au lieu de 5.

Endpoints principaux

  • GET /search?q=... — Recherche avec filtres optionnels
  • GET /tiers-lieux/{id} — Fiche d'un tiers-lieu
  • GET /tiers-lieux/{id}/logo — Logo d'un tiers-lieu
  • POST /webhook/grist — Synchronisation temps réel depuis Grist
  • GET /menu - Entrées du menu partagé (gérées dans le document national)
  • GET /nouveau-lieu - Redirige vers le formulaire « Ajouter un lieu »
  • POST /tiers-lieux/{id}/signalement - Signaler un lieu (5 par heure et par IP)
  • GET /health - État du service et de la dernière synchronisation