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.

Base · https://api.balisio.com Version · v1 OpenAPI ↗ Hébergé en France

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éthodeRessourceDescription
GET/api/v1/public/consultationsListe 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}/questionsSchéma du questionnaire (pour afficher le formulaire).
GET/api/v1/public/consultations/{slug}/avisAvis publiés (paginés).
GET/api/v1/public/consultations/{slug}/shapesPérimètre et tracés en GeoJSON.
GET/api/v1/public/consultations/{slug}/resultsRésultats agrégés (total, répartition par thème).
POST/api/v1/public/consultations/{slug}/avisDéposer un avis (modéré, limité en débit).

Observatoire (signalements)

MéthodeRessourceDescription
GET/api/v1/public/observatoire/pinsSignalements 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/themesCatalogue des thèmes.
GET/api/v1/public/observatoire/statsStatistiques agrégées (par thème, par statut).
POST/api/v1/public/observatoire/signalementsDé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.

SignatureChaque 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énementsFamilles pin.* (assigned, status_changed, response_published), report.*, source.*, project.*, attachment.*, votation.*, budget.* · ou * pour tout recevoir.
RelancesRé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 v1Le 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éciationSi 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écificationLa référence machine est l'OpenAPI 3.0 · elle fait foi en cas d'écart avec cette page.

Bon à savoir

FormatRéponses JSON. Les listes renvoient { data, count, limit, offset } ; les objets sont renvoyés directement ; les erreurs { detail }.
CORSOuvert (Access-Control-Allow-Origin: *) sur tout le préfixe /api/v1 · appelable depuis n'importe quel domaine, sans configuration.
AuthentificationAucune pour la lecture. Les dépôts sont anonymes et modérés.
Paginationlimit (défaut 50, max 200) et offset.
DonnéesPubliques 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]