Données ouvertes et API — Les Fées-rues du Bitume

Cette API publique donne accès aux courses de caisses à savon affichées sur la carte nationale du site. Elle est destinée aux agents, développeurs et services qui souhaitent consulter ces données publiques sous une forme JSON stable. Elle ne permet aucune inscription, modification ou action administrative.

Quand utiliser cette API

Utilisez-la pour rechercher les prochaines courses françaises, construire un calendrier, répondre à une question sur une date ou un lieu, ou vérifier les données visibles sur la carte. Pour les informations officielles concernant la course de Martigné-Ferchaud, préférez les pages du site et leurs versions Markdown répertoriées dans llms.txt.

Accès

L’API est anonyme, gratuite et en lecture seule. Aucun compte, jeton, OAuth ou environnement sandbox n’est nécessaire. Le point d’entrée versionné est GET /api/v1/courses/. Le paramètre facultatif scope accepte upcoming par défaut ou all.

curl "https://www.lesfeesruesdubitume.fr/api/v1/courses/?scope=upcoming"

Contrat et versions

Le contrat complet est publié dans openapi.json. Les nouvelles intégrations doivent utiliser le chemin /api/v1/. Un changement incompatible utilisera une nouvelle version de chemin. Toute dépréciation sera annoncée ici et dans la description OpenAPI avant la suppression d’une version. L’ancien chemin /api/courses/ reste disponible comme alias de compatibilité.

Erreurs JSON

Les erreurs utilisent application/problem+json avec un code stable, un titre, un détail et une piste de résolution. Les codes actuellement publiés sont les suivants.

• invalid_scope — utiliser scope=upcoming ou scope=all.
• method_not_allowed — recommencer avec la méthode GET.
• courses_unavailable — réessayer plus tard ou consulter la carte publique.

Cache et usage raisonnable

Les réponses scope=upcoming sont mises en cache par le CDN Vercel pendant 6 heures. Les réponses scope=all le sont pendant 24 heures, avec une réponse périmée autorisée pendant 7 jours durant la revalidation. La carte effectue un appel au chargement, puis un second seulement si la personne demande les courses passées.

Aucun quota applicatif chiffré n’est actuellement annoncé et le site n’émet donc pas de faux en-têtes de limite. Les clients doivent réutiliser les réponses selon Cache-Control, éviter les interrogations répétitives et appliquer un délai progressif après une erreur temporaire.