À 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 optionnelsGET /tiers-lieux/{id} — Fiche d'un tiers-lieuGET /tiers-lieux/{id}/logo — Logo d'un tiers-lieuPOST /webhook/grist — Synchronisation temps réel depuis GristGET /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