Développeurs
L'API publique Balisio.
Intégrez l'observatoire citoyen et les consultations dans l'application de votre commune : votre site, votre appli mobile, un écran en mairie, un tableau de bord interne. API REST, CORS ouvert, sans clé pour la lecture, réponses JSON. Données publiques et modérées uniquement · aucune donnée de contact, aucune photo citoyenne, aucun brouillon.
Démarrage rapide
Lister les consultations en cours d'une commune (code INSEE), puis ses signalements. Aucune authentification.
# Consultations en cours de la commune 38185 (Grenoble) curl "https://api.balisio.com/api/v1/public/consultations?commune=38185&status=live" # Signalements publiés de la commune curl "https://api.balisio.com/api/v1/public/observatoire/pins?commune=38185&limit=50"
// Depuis l'application de votre commune (fetch navigateur, CORS ouvert)
const r = await fetch(
"https://api.balisio.com/api/v1/public/observatoire/pins?commune=38185&theme=voirie"
);
const { data, count } = await r.json();
data.forEach(p => console.log(p.text, p.status, p.lat, p.lon));
Consultations
| Méthode | Ressource | Description |
|---|---|---|
| GET | /api/v1/public/consultations | Liste des consultations publiques. Filtres : commune (INSEE), status. Pagination : limit, offset. |
| GET | /api/v1/public/consultations/{slug} | Détail : nom, format, dates, périmètre, description. |
| GET | /api/v1/public/consultations/{slug}/questions | Schéma du questionnaire (pour afficher le formulaire). |
| GET | /api/v1/public/consultations/{slug}/avis | Avis publiés (paginés). |
| GET | /api/v1/public/consultations/{slug}/shapes | Périmètre et tracés en GeoJSON. |
| GET | /api/v1/public/consultations/{slug}/results | Résultats agrégés (total, répartition par thème). |
| POST | /api/v1/public/consultations/{slug}/avis | Déposer un avis (modéré, limité en débit). |
Observatoire (signalements)
| Méthode | Ressource | Description |
|---|---|---|
| GET | /api/v1/public/observatoire/pins | Signalements publiés. Filtres : commune, theme, status, bbox (ouest,sud,est,nord). Pagination : limit, offset. |
| GET | /api/v1/public/observatoire/pins/{id} | Détail d'un signalement (avec la réponse publique de la mairie). |
| GET | /api/v1/public/observatoire/themes | Catalogue des thèmes. |
| GET | /api/v1/public/observatoire/stats | Statistiques agrégées (par thème, par statut). |
| POST | /api/v1/public/observatoire/signalements | Déposer un signalement (modéré, limité en débit). |
Déposer une contribution
Les dépôts passent par la même modération (anti-injures, retrait des données personnelles) et la même limitation de débit que le formulaire citoyen. Le consentement de publication est requis.
# Déposer un signalement curl -X POST "https://api.balisio.com/api/v1/public/observatoire/signalements" \ -H "content-type: application/json" \ -d '{ "text": "Trottoir affaissé au 12 rue des Écoles", "lat": 45.188, "lon": 5.724, "theme": "voirie", "consent": true }' # -> 201 publié · 202 en file de modération · 429 trop de requêtes
Webhooks sortants
Balisio pousse les événements de votre commune vers votre système (SI, GRC, tableau de bord interne). Les abonnements se créent depuis l'espace client (onglet SDK & intégration) : vous déclarez une URL https et recevez un secret HMAC.
| Signature | Chaque livraison porte X-Balisio-Signature: sha256=<hex> · HMAC-SHA256 du corps brut avec votre secret. Recalculez et comparez avant de traiter. L'en-tête X-Balisio-Event donne le type. |
| Corps | { id, type, project_slug, actor, summary, data, at } · JSON UTF-8. Utilisez id pour l'idempotence : une relance renvoie le même événement. |
| Événements | Familles pin.* (assigned, status_changed, response_published), report.*, source.*, project.*, attachment.*, votation.*, budget.* · ou * pour tout recevoir. |
| Relances | Réponse attendue : 2xx en moins de 8 s. En cas d'échec réseau, de 5xx, 408 ou 429, l'événement est relancé avec backoff : 1 min, 5 min, 30 min, 2 h, 12 h (en-tête X-Balisio-Retry: n), puis abandonné. Les autres 4xx sont définitifs (pas de relance). |
Stabilité et versionnement
| Contrat v1 | Le préfixe /api/v1 est stable : les évolutions sont additives (nouveaux champs, nouveaux endpoints). Aucun champ existant n'est renommé ni supprimé dans la v1. |
| Dépréciation | Si une rupture devient nécessaire, elle arrive dans une /api/v2 et la v1 reste servie au moins 6 mois après annonce, avec un en-tête Deprecation sur les routes concernées. |
| Spécification | La référence machine est l'OpenAPI 3.0 · elle fait foi en cas d'écart avec cette page. |
Bon à savoir
| Format | Réponses JSON. Les listes renvoient { data, count, limit, offset } ; les objets sont renvoyés directement ; les erreurs { detail }. |
| CORS | Ouvert (Access-Control-Allow-Origin: *) sur tout le préfixe /api/v1 · appelable depuis n'importe quel domaine, sans configuration. |
| Authentification | Aucune pour la lecture. Les dépôts sont anonymes et modérés. |
| Pagination | limit (défaut 50, max 200) et offset. |
| Données | Publiques et modérées uniquement. Jamais : coordonnées de contact, photos citoyennes, brouillons, données internes. |
| Souveraineté | Hébergement France (OVH), IA en Union européenne. Aucun transfert hors UE. |
| Contact | [email protected] |