🏀 API FFBB (Python SDK) — ffbb-data-client

Client Officiel & Asynchrone pour l'API de la Fédération Française de BasketBall (2026)

Le SDK Python moderne, ultra-rapide, asynchrone et typé pour exploiter l'API de la Fédération Française de BasketBall (FFBB) : clubs, compétitions nationales & régionales, scores en direct (lives), classements, calendriers, gymnases/salles et détection de niveau.

Alternative officielle, haute performance et maintenue aux anciens packages obsolètes ffbb-api-client et ffbb-api-client-v2.

---

⚡ Démarrage Rapide • 📍 Recherche Géo & Clubs • 🔥 Cas d'Usage • 🧵 Streaming Async • 🤖 Intégration IA / MCP • 🌐 API REST • 📖 Documentation

🔄 Cartographie API synchronisée : 162 collections Directus OpenAPI cartographiées, 17 index Meilisearch surveillés.

🏆 Pourquoi choisir ffbb-data-client ?

📦 Installation

Installez la dernière version stable via pip ou uv :

# Via pip standard
pip install ffbb-data-client

# Via uv (recommandé pour la rapidité)
uv add ffbb-data-client

Options supplémentaires

# Avec le serveur d'API REST FastAPI intégré
pip install "ffbb-data-client[server]"

# Pour le développement local et la suite de tests complète
pip install "ffbb-data-client[testing]"

Prérequis : Python >=3.10.

⚡ Démarrage Rapide (30 secondes)

Aucun compte développeur ni clé d'API compliquée : FFBBDataClient.create() résout et rafraîchit automatiquement les tokens publics nécessaires :

from ffbb_data_client import FFBBDataClient

# Initialisation en une seule ligne (zéro configuration requise)
client = FFBBDataClient.create()

# 1. Rechercher un club de basket en France
clubs = client.search_organismes("Clermont", limit=3)
for club in clubs.hits:
    print(f"🏀 {club.nom} ({club.codePostal} {club.commune}) - ID: {club.id}")

# 2. Consulter les scores et matchs en direct (Lives FFBB)
lives = client.get_lives()
print(f"Matchs suivis en direct : {len(lives)}")

# 3. Explorer les rencontres d'une compétition (ex: Nationale 1 Masculine)
rencontres = client.search_rencontres("NM1", limit=5)
for m in rencontres.hits:
    print(f"📅 {m.date_rencontre} : {m.equipe1} vs {m.equipe2}")

📍 Recherche Géographique & Clubs de France

Idéal pour concevoir des applications mobiles, des cartes interactives ou des annuaires de basketball :

🌍 Trouver tous les clubs autour d'un point GPS

# Exemple : Clubs dans un rayon de 20 km autour de Lyon / Clermont-Ferrand
clubs = client.search_organismes_by_geo(
    lat=45.7772,
    lng=3.0870,
    radius_km=20,
    limit=15,
)

for club in clubs.hits:
    print(f"📍 {club.nom} à {club.commune} [{club.geo}]")

🔍 Recherche ciblée par Code Postal, Ville ou Catégorie

# Filtrer par département ou code postal
organismes = client.search_organismes(
    "Basket",
    filter=['codePostal = "63000"'],
    sort=["nom:asc"],
    limit=10,
)

🔥 Recettes & Cas d'Usage Concrets

from ffbb_data_client import FFBBDataClient

client = FFBBDataClient.create()

# Récupération complète d'une poule de championnat
poule = client.get_poule(11111)

print(f"Championnat : {poule.nom}")
for rk in poule.classement or []:
    print(f"#{rk.position} {rk.organisme_nom} - {rk.points} pts ({rk.victoires}V - {rk.defaites}D)")

# Fini les adresses partielles : résolution déterministe certifiée FFBB
salles = client.search_salles("Maison des Sports", limit=3)
for salle in salles.hits:
    print(f"🏟️ {salle.nom} : {salle.adresse}, {salle.codePostal} {salle.ville}")

from ffbb_data_client import NiveauExtractor, NiveauType

# Détection intelligente du niveau hiérarchique
niveau = NiveauExtractor.extract_niveau("RÉGIONALE MASCULINE SENIORS - DIVISION 2")
print(niveau.type)       # NiveauType.REGIONAL
print(niveau.division)   # 2

# Contacts administratifs officiels
contacts = client.get_club_contacts(organisme_id=9326)
if contacts:
    print(f"Club : {contacts.club_contact.nom}")
    print(f"Email : {contacts.club_contact.email}")
    for membre in contacts.membres:
        print(f" - {membre.role} : {membre.prenom} {membre.nom} ({membre.email})")

🧵 Haute Performance & Streaming Asynchrone

Pour traiter de gros volumes de données sans saturer la mémoire vive ni bloquer la boucle d'événements :

import asyncio
from ffbb_data_client import FFBBDataClient

async def main():
    client = FFBBDataClient.create()

    # Streaming asynchrone mémoire-constant (aiter)
    count = 0
    async for rencontre in client.aiter_all_rencontres(page_size=100, max_items=500):
        count += 1
        if count % 100 == 0:
            print(f"Traitement du match #{count} : {rencontre.id}")

    # Recherche asynchrone non-bloquante
    results = await client.search_organismes_async("ASVEL")
    print(f"Résultats trouvés : {results.estimated_total_hits}")

asyncio.run(main())

🤖 IA, Agents & MCP Server

Le SDK ffbb-data-client est le moteur officiel du serveur Model Context Protocol (MCP) pour le basket français.

Il permet aux LLMs (Claude, ChatGPT, Cursor, Gemini, Antigravity) d'interagir nativement avec les championnats de basket :

• 💬 "Quels sont les prochains matchs du SCBA ce week-end ?"
• 💬 "Donne-moi le classement de la Poule Haute U13M2."
• 💬 "Quelle est l'adresse exacte de la salle pour le match de samedi ?"

👉 Découvrez le projet dédié : FFBB-MCP-Server

🌐 Serveur REST FastAPI Embarqué

Besoin d'une API web pour votre application React, Vue, Next.js ou mobile ? ffbb-data-client intègre une API FastAPI prête à l'emploi :

# Démarrer le serveur API local
uvicorn ffbb_data_client.api:app --host 0.0.0.0 --port 8000 --reload

Accédez ensuite à la documentation Swagger interactive sur http://localhost:8000/docs !

Endpoints phares :

• GET /health : Statut de santé et horodatage UTC.
• GET /api/v1/club/{id}/matches : Calendrier optimisé du club avec adresses de salles résolues.
• GET /api/v1/lives : Matchs en direct agrégés.

📚 Référence des Méthodes (Sync & Async)

💡 Pattern standard : Toutes les méthodes existent en version synchrone (nom()) et asynchrone (nom_async()).

🛠️ Robustesse, CI/CD & Découverte Quotidienne

• Origine Directus & Anti-403 : Bascule native vers l'origine Directus https://bo.ffbb.com/ (et fallback miroir https://bo.ffbb.app/) avec User-Agent mobile Safari authentique, éliminant définitivement les erreurs 403 Forbidden de l'ancienne pullzone BunnyCDN.
• Auto-Résolution des Tokens : Découverte et rotation dynamiques des jetons Bearer Directus et Meilisearch sans configuration requise.
• Découverte Quotidienne du Schéma : Un cron GitHub Actions analyse chaque matin à 5h17 UTC l'OpenAPI spec officielle de la FFBB et détecte automatiquement tout nouveau champ ou collection Directus.
• Cache Intelligent Sécurisé : Gestionnaire de cache HTTP hishel avec SQLite distinct pour les flux synchrones et asynchrones.
• CodeQL & Zéro Dette : Conformité aux normes de sécurité, zéro alerte d'injection de log, 100% typé.

⚙️ Configuration & Variables d'Environnement

Le SDK fonctionne instantanément sans configuration. Des variables d'environnement permettent de surcharger les comportements réseaux si nécessaire :

🤝 Contribuer

Les contributions, signalements de bugs et suggestions sont les bienvenus !

1. Forkez le projet.
2. Créez une branche (git checkout -b feat/ma-nouvelle-fonctionnalite).
3. Installez l'environnement de développement : pip install -e ".[testing]".
4. Vérifiez que tous les tests passent : pytest tests/ et pre-commit run --all-files.
5. Ouvrez une Pull Request claire et documentée.

📄 Licence

Distribué sous la licence Apache-2.0. Voir LICENSE.txt pour plus de détails.