FFBB Data Client
nickdesi/ffbb-data-client
SDK assíncrono type-safe para dados de basquete francês com MCP server
Ver no GitHubSDK Python assíncrono e type-safe para consumir a API da Federação Francesa de Basquete. Fornece acesso a dados de clubes, competições, placares em tempo real, classificações, calendários e ginásios com suporte nativo a streaming e integração com agentes IA.
Instalação
npx convez-ai nickdesi/ffbb-data-client1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar dados de clubes e competições da FFBB
- Obter placares e classificações em tempo real
- Buscar ginásios e informações regionais de basquete
- Integrar dados de basquete em aplicações IA/agentes
Veredito

Solução profissional e bem mantida para integração com dados oficiais da FFBB. Excelente para quem precisa de dados de basquete francês em aplicações Python modernas, especialmente em contextos de agentes IA com suporte a MCP server.
README
A tradução para o português deste README ainda está na fila.
🏀 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 :
162collections Directus OpenAPI cartographiées,17index Meilisearch surveillés.
[!NOTE] API Mobile Officielle (
v2.4.42+) : Utilisation native de l'origine mobile officiellehttps://api.ffbb.com/avec bootstrapping dynamique des jetons (/items/configuration) et émulation User-Agent Android officielle. L'intégralité des données Directus (y compris les feuilles de poules et les classements complets) est accessible en temps réel avec fallback résilient Meilisearch.
🏆 Pourquoi choisir ffbb-data-client ?
| Fonctionnalité | Ancien client (ffbb-api-client) | ffbb-data-client (v2.4+) |
|---|---|---|
| Origine Directus & Anti-403 | ❌ Bloqué en 403 Forbidden (BunnyCDN) | ✅ API mobile api.ffbb.com + bootstrapping dynamique |
| Architecture Asynchrone Native | ❌ 100% bloquant / synchrone | ✅ Async native (async/await + aiter) |
| Modèles de Données & Typage | ❌ Dictionnaires bruts sans type | ✅ Dataclasses & Pydantic v2 validés |
| Recherche Meilisearch Instantanée | ❌ Partielle ou absente | ✅ Multi-index (Clubs, Salles, Poules, 3x3) |
| Recherche Géographique par GPS | ❌ Non disponible | ✅ Rayon kilométrique autour de coordonnées |
| Streaming de Masse (Pagination auto) | ❌ Manuelle, risque d'OOM | ✅ Générateurs streaming aiter_all_* |
| Résolution d'Adresses de Salles | ❌ Nom brut souvent vide | ✅ Résolution physique complète (Gymnase, Rue, CP, Ville) |
| Compatibilité IA & Agents MCP | ❌ Incompatible | ✅ Connecteur natif Model Context Protocol |
| Couverture de Tests & Fiabilité | ⚠️ < 30% | ✅ 680+ tests unitaires & 100% Zero-Red CI |
📦 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()).
| Domaine | Méthodes (Sync & Async) | Description |
|---|---|---|
| 🌐 Multi-Search | multi_search()multi_search_async() | Recherche globale simultanée sur tous les index Meilisearch |
| 🏀 Clubs & Organismes | search_organismes()search_organismes_async() | Recherche par nom, commune, département ou code postal |
| 📍 Géo-Localisation | search_organismes_by_geo()search_organismes_by_geo_async() | Recherche de clubs par rayon GPS (lat/lng, km) |
| 👤 Contacts Club | get_club_contacts()get_club_contacts_async() | Fiche contacts officielle (président, correspondants, emails) |
| 📅 Rencontres & Matchs | search_rencontres()search_rencontres_async() | Calendriers, résultats de matchs et scores |
| ⚡ Streaming Continu | aiter_all_rencontres() | Générateur asynchrone paginé en streaming (aiter) |
| 🏟️ Salles & Gymnases | search_salles()search_salles_async() | Adresses physiques complètes, gymnases et coordonnées |
| 🏆 Compétitions | search_competitions()search_competitions_async() | Championnats nationaux (NM1, LF2...), régionaux, départ. |
| 📊 Poules & Classement | get_poule()get_poule_async() | Classement officiel complet (V/D, pts) et matchs de poule |
| ⚡ Scores en Direct | get_lives()get_lives_async() | Flux officiel des scores en temps réel (Lives FFBB) |
| 🎯 Tournois 3x3 | search_tournois()search_tournois_async() | Tournois officiels homologués 3x3 FFBB |
🛠️ Robustesse, CI/CD & Découverte Quotidienne
- Origine Directus & API Mobile : Origine officielle
https://api.ffbb.com/issue du reverse engineering de l'app mobile (pullzone 5204911). Les jetons Directus et Meilisearch sont découverts à chaud via/items/configuration. En cas d'indisponibilité temporaire de l'upstream, un disjoncteur bascule sur Meilisearch avec signalement défensif (degraded). - 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
hishelavec 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 :
| Variable | Description | Valeur par défaut |
|---|---|---|
API_FFBB_BASE_URL | URL de base du backend Directus | https://api.ffbb.com/ |
FFBB_USER_AGENT | En-tête User-Agent transmis aux requêtes | FFBB Android Mobile (1.6.7.42) |
API_FFBB_APP_BEARER_TOKEN | Jeton Directus explicite (override l'auto-résolution) | Auto-résolu dynamiquement |
MEILISEARCH_BEARER_TOKEN | Jeton Meilisearch explicite (override l'auto-résolution) | Auto-résolu dynamiquement |
HTTP_PROXY / HTTPS_PROXY | Proxy HTTP/HTTPS sortant (ex: swarm / environnement conteneurisé) | Aucun |
🤝 Contribuer
Les contributions, signalements de bugs et suggestions sont les bienvenus !
- Forkez le projet.
- Créez une branche (
git checkout -b feat/ma-nouvelle-fonctionnalite). - Installez l'environnement de développement :
pip install -e ".[testing]". - Vérifiez que tous les tests passent :
pytest tests/etpre-commit run --all-files. - Ouvrez une Pull Request claire et documentée.
📄 Licence
Distribué sous la licence Apache-2.0. Voir LICENSE.txt pour plus de détails.
Développé avec passion pour la communauté du basketball français. 🇫🇷🏀
Si cette bibliothèque vous est utile, n'hésitez pas à ajouter une étoile ⭐ sur GitHub pour encourager le projet !