Ma Vie Numérique : développeurs et agents
Quand utiliser Ma Vie Numérique (when to use)
Utilisez Ma Vie Numérique pour trouver un commerce, une association ou un lieu dans une commune, préparer une sortie à partir de l’agenda, consulter des annonces et retrouver les coordonnées publiées d’un établissement. Choisissez d’abord le portail de la commune : brest.ma-vie-numerique.fr pour Brest. Citez l’URL de la fiche consultée et sa date de consultation ; ne présentez pas des horaires ou une disponibilité comme confirmés sans vérifier la source.
Ce portail n’est pas un service municipal officiel, un système de réservation ni un service d’urgence. N’utilisez pas les données d’annuaire pour affirmer qu’une entreprise est certifiée. Les actions de compte, de publication, de messagerie et de paiement nécessitent une session utilisateur et son accord explicite.
Lecture publique et authentification
Les pages publiques, /llms.txt et /sitemap.xml se consultent avec HTTP GET, sans compte ni clé API. Pour rechercher, ouvrez /recherche?q= avec une requête encodée dans l’URL, puis suivez les liens des résultats. Les rubriques /entreprises, /associations, /lieux et /agenda fournissent des points d’entrée lisibles sans JavaScript.
Demandez Accept: text/markdown pour une représentation Markdown des pages HTML ; /developers.md fournit également cette documentation. Une URL inexistante conserve le statut HTTP 404 avec des liens de récupération. En cas de HTTP 503, respectez Retry-After lorsqu’il est présent et réessayez plus tard ; une indisponibilité n’est pas une preuve d’absence de données.
curl -sS -H 'Accept: text/markdown' https://brest.ma-vie-numerique.fr/developers
curl -sS 'https://brest.ma-vie-numerique.fr/recherche?q=librairie'Flux public de l’agenda
GET /api/agenda-ics renvoie le calendrier de la commune au format iCalendar, avec Content-Type: text/calendar; charset=utf-8. Aucun compte ni clé n’est requis. Le paramètre facultatif dl=1 demande un téléchargement ; id sélectionne un événement à partir de l’identifiant fourni par le site. Un identifiant introuvable renvoie HTTP 404. Utilisez les liens d’export de l’agenda pour obtenir un identifiant, sans en inventer.
Les données de l’agenda sont mises en cache côté serveur ; évitez les consultations répétées. Les réponses HTTP portent un quota individuel et ne sont pas mises en cache. Ce flux sert à consulter et importer des événements, sans créer de réservation ni de publication. Le contrat OpenAPI décrit ce flux et la recherche publique. Les autres routes de compte, de publication et de paiement sont des interfaces internes, sans contrat public d’intégration. Aucun serveur MCP n’est proposé ici.
curl -sS https://brest.ma-vie-numerique.fr/api/agenda-icsAPI OpenAPI et appels de fonctions
Le contrat /openapi.json, au format OpenAPI 3.1.1, décrit les routes versionnées /api/v1/search et /api/v1/agenda et leurs alias historiques. Les opérations versionnées sont searchLocalDirectoryV1 et getCommuneAgendaV1. Chaque opération comporte une description, des paramètres typés et les schémas de réponse. Les agents peuvent utiliser ces identifiants pour construire leurs outils d’appel de fonctions. Aucun compte ni clé API n’est nécessaire. Le nom d’hôte sélectionne la commune ; Brest reste accessible sur le domaine principal et son sous-domaine.
GET /api/search/suggest?q=librairie renvoie du JSON : q et groups, avec les catégories et leurs items (title, sub, href). Suivez href pour lire et citer la fiche. Une recherche vide ou de moins de deux caractères ne renvoie aucun groupe ; le texte est limité aux 80 premiers caractères. La réponse peut être partielle si une source est indisponible : une liste vide ne prouve pas l’absence d’un établissement. Attendez au moins 30 secondes avant de renouveler une recherche identique ; les réponses HTTP ne sont pas mises en cache.
Les erreurs des endpoints documentés utilisent application/problem+json (RFC 9457) : type, title, status, detail, code et hint. Le code stable indique le problème ; hint explique comment le résoudre. Un événement absent renvoie 404 EVENT_NOT_FOUND ; un portail inconnu renvoie 404 PORTAL_NOT_FOUND ; une indisponibilité renvoie 503 SERVICE_UNAVAILABLE et Retry-After: 60. Les réponses d’erreur ne sont pas mises en cache. Les protections en amont peuvent renvoyer d’autres formats : vérifiez toujours le statut HTTP et Content-Type.
curl -sS 'https://brest.ma-vie-numerique.fr/api/search/suggest?q=librairie'
curl -sS https://brest.ma-vie-numerique.fr/openapi.jsonVersionnement, dépréciation et quotas
La version majeure 1 est disponible sous /api/v1/search et /api/v1/agenda. Les anciennes adresses /api/search/suggest et /api/agenda-ics restent compatibles. API-Version: 1 confirme la version servie. Les ajouts compatibles peuvent apparaître dans la même version ; ignorez les champs inconnus. Une modification incompatible utilisera un nouveau préfixe majeur, par exemple /api/v2/.
Aucun retrait de version n’est programmé. Si une version doit être retirée, un préavis d’au moins 90 jours sera annoncé ici. Les réponses concernées porteront Deprecation (date structurée @timestamp selon RFC 9745), Sunset (date HTTP selon RFC 8594), et un lien rel=deprecation vers la migration. Le Sunset sera postérieur à la dépréciation. Ces en-têtes de date ne sont pas envoyés tant qu’aucun retrait n’est décidé.
Les endpoints documentés partagent 120 requêtes par fenêtre fixe de 60 secondes et par adresse IP, tous portails et alias confondus. Les appels réussis et en erreur consomment une unité ; une requête déjà refusée pour quota ne consomme rien. Les clients derrière la même adresse partagent ce quota. Les compteurs sont partagés et atomiques et expirent après deux minutes. Ils ne stockent ni requête de recherche ni URL.
RateLimit-Policy: "public-api";q=120;w=60 annonce le quota et la fenêtre. RateLimit: "public-api";r=119;t=60 indique les requêtes restantes et les secondes avant réinitialisation. Les champs suivent draft-ietf-httpapi-ratelimit-headers-11, encore un projet IETF, et non un RFC publié. La négociation Accept respecte les priorités q et les exclusions q=0 ; un format non accepté renvoie HTTP 406. Sur HTTP 429, le corps JSON porte RATE_LIMITED et Retry-After donne le délai d’attente. Si le compteur est indisponible, HTTP 503 est renvoyé sans inventer de quota restant. Les réponses portent Cache-Control: private, no-store pour empêcher le partage d’un quota entre clients.
GET /api/v1/agenda renvoie par défaut du JSON typé (city et events). Chaque événement expose id, title, startDate, endDate, venue, address et city ; les informations absentes sont des chaînes vides. Demandez Accept: text/calendar pour l’export iCalendar. L’ancienne adresse /api/agenda-ics conserve son format iCalendar par défaut et fournit du JSON avec Accept: application/json.
CLI officiel Ma Vie Numérique
Le client en ligne de commande nécessite Node.js 20 ou une version ultérieure. Il permet de rechercher, télécharger l’agenda et lire le contrat API, sans compte ni clé. Le paquet officiel @benfavre/ma-vie-numerique-cli est publié sur npm par le compte benfavre pour Webdesign29. Installez-le avec la commande ci-dessous ; une archive identique reste téléchargeable depuis notre domaine.
Les commandes search et spec écrivent du JSON sur la sortie standard ; agenda écrit un calendrier iCalendar. Les erreurs sont du JSON sur la sortie d’erreur : code de sortie 1 pour une erreur HTTP ou réseau, 2 pour des arguments invalides. Le CLI utilise /api/v1/. L’option --city choisit une commune existante, --id sélectionne un événement pour agenda, et --json produit les événements structurés au lieu du calendrier iCalendar. Le délai réseau est de 15 secondes ; aucune nouvelle tentative ni action d’écriture n’est automatique.
npm install -g @benfavre/ma-vie-numerique-cli
ma-vie-numerique search "librairie" --city brest
ma-vie-numerique agenda --city brest > agenda.ics
ma-vie-numerique specRéutilisation et contact technique
Respectez robots.txt, les indications de source et les licences de chaque contenu. Ne considérez pas les photos et textes des contributeurs comme des données librement réutilisables. Limitez vos requêtes, conservez les réponses selon leurs en-têtes de cache et ne contournez pas l’authentification. Pour un besoin d’export ou d’intégration supplémentaire, contactez Webdesign29 en précisant la commune et les données souhaitées.