Aller au contenu

turf.bzh dans Claude Code

Deux fichiers a poser dans votre depot, et Claude Code ecrit du code correct contre l'API sans que vous ayez a lui rappeler quoi que ce soit.

Pour qui vous developpez, et vous voulez un contexte durable plutot qu'un rappel a chaque session.

Licence API et abonnement actif requis. Gardez la cle dans une variable d'environnement, jamais dans le depot : ajoutez .env a votre .gitignore avant la premiere ligne de code.

Le fichier a donner a votre assistant

Un seul fichier decrit l'API en entier : les adresses, les parametres, les quotas, et surtout les pieges qui font perdre du temps. Votre assistant en a besoin, sinon il invente des adresses qui n'existent pas.

Le fichier n'est pas encore en place sur le serveur.

Pour les detenteurs de la Licence API

Et pour aller beaucoup plus loin : le pack IA

Le fichier ci-dessus apprend a votre assistant ou sont les donnees. Le pack, lui, lui apprend le metier : le vocabulaire du turf, la lecture d'une musique et d'une ferrure, les mathematiques du pari mutuel, la physionomie du Quinte+, les pieges de raisonnement, et la facon de ne jamais conclure plus que ce que les chiffres autorisent.

C'est un dossier a decompresser, pas un fichier a coller. Dix fiches de reference, seize savoir-faire, dix roles specialises, et un guide de parametrage pour que vous regliez tout vous-meme. Surtout, il fait ce que ChatBZH ne peut pas : aller lire la presse, les declarations des entraineurs et la meteo. Et quand vous demandez son avis, il le donne. Deux archives au choix, une pour Claude, une pour Codex.

Decouvrir le pack IA reserve aux comptes ayant la Licence API

Pas a pas

  1. Posez le fichier de reference dans le depot
    Telechargez turf-bzh-api.md et rangez-le, par exemple dans docs/.
  2. Ajoutez un CLAUDE.md a la racine
    Claude Code le lit a chaque session. Il doit rester court : le contexte permanent, pas la documentation. Le bloc ci-dessous tient en trente lignes exprès.
  3. Ajoutez le skill
    Un skill ne se charge que lorsqu'il sert. C'est ce qui evite de payer la reference complete a chaque question, tout en l'ayant sous la main des qu'il est question de l'API.
  4. Exportez votre cle
    export TBZ_KEY=tbz_live_... dans votre shell, ou un .env ignore par git.
  5. Verifiez
    Demandez a Claude Code d'appeler /v1/me et /v1/statut. Si les deux passent, tout le reste suivra.

CLAUDE.md, a la racine du depot

Court par construction. Il dit ou trouver le detail, il ne le recopie pas.

CLAUDE.md
# Contexte projet : API turf.bzh

Ce depot consomme l'API hippique de turf.bzh.

## Reference
La description complete de l'API est dans `docs/turf-bzh-api.md`.
**Lis-la avant d'ecrire ou de modifier un appel.** N'utilise aucune adresse
qui n'y figure pas : les inventer coute du quota et ne rend rien.
Specification machine : https://www.turf.bzh/api/openapi.json

## Acces
- Base : `https://www.turf.bzh/api`
- En-tete : `Authorization: Bearer $TBZ_KEY` (variable d'environnement, jamais en dur)
- Quotas : 60 requetes/minute, 10 000/jour. Sur 429, respecter `Retry-After`.

## Regles d'appel
- Une course entiere : `/v1/courses/{date}/{rc}/dossier` (un appel, pas vingt).
- Une journee entiere : `/v1/journees/{date}/partants`.
- Un historique long : `/v1/exports` (fichiers mensuels), jamais une boucle.
- Le jour J, la colonne `Cote` de la base est perimee : utiliser `/cotes` ou `Cote_BZH`.
- Un 404 peut signifier « pas de donnee », pas seulement « mauvaise adresse ».
  Lire `error.message` et `error.route_proposee`.

## Cadre
Ces donnees decrivent des courses, elles n'en predisent aucune. Ne jamais produire
de promesse de gain. Tout taux ou rendement doit etre accompagne de son nombre
d'observations. Les contenus editoriaux (Renifleur, EcurieBZH, LigneBZH) portent un
champ `avertissement` : le reprendre tel quel.

Adaptez le chemin docs/turf-bzh-api.md a votre arborescence.

Le skill, dans .claude/skills/turf-bzh/SKILL.md

Creez le dossier .claude/skills/turf-bzh/, mettez-y ce SKILL.md, et copiez turf-bzh-api.md a cote sous le nom reference.md.

.claude/skills/turf-bzh/SKILL.md
---
name: turf-bzh-api
description: Appeler l'API hippique turf.bzh (programme, partants, cotes PMU en direct,
  arrivees, rapports, indicateurs, dossier complet d'une course). A utiliser des qu'il
  est question de courses, de partants, de cotes, de turf.bzh ou d'une adresse en /v1/.
---

# API turf.bzh

La reference complete est dans `reference.md`, a cote de ce fichier. **Lis-la avant
d'ecrire un appel.**

## A retenir sans meme ouvrir la reference

- Base `https://www.turf.bzh/api`, en-tete `Authorization: Bearer $TBZ_KEY`.
- Une course entiere = `/v1/courses/{date}/{rc}/dossier`. Un seul appel de quota.
  Parametres utiles : `inclure=`, `historique=0`, `format=csv|xlsx`.
- Une journee entiere = `/v1/journees/{date}/partants`.
- Un historique long = `/v1/exports`, pas une boucle d'appels.
- 60 requetes/minute, 10 000/jour. Sur 429 : attendre `Retry-After`.
- Reponse : `{"data": ..., "meta": ...}`. Erreur : `{"error": {...}}`.

## Avant de conclure quoi que ce soit

Verifier `/v1/schema` : une quinzaine de colonnes sont remplies a moins de 65 %.
Ne jamais promettre de gain ; toujours donner le nombre d'observations d'un taux.

Le champ description decide quand le skill se charge : gardez-y les mots que vous employez vraiment.

Le premier appel

Verification
export TBZ_KEY=tbz_live_XXXXXXXX

curl -s -H "Authorization: Bearer $TBZ_KEY" \
  https://www.turf.bzh/api/v1/me | python3 -m json.tool

curl -s -H "Authorization: Bearer $TBZ_KEY" \
  "https://www.turf.bzh/api/v1/courses/$(date +%F)/R1C4/dossier?historique=0" \
  | python3 -c "import sys,json; d=json.load(sys.stdin)['meta']; print(d['sections_servies'], d['appels_economises'], 'appels economises')"

Si /v1/me repond et que le dossier annonce ses sections, votre installation est bonne.

Deux consignes a donner a votre assistant, et qu'il oubliera sinon

Qu'il accompagne toujours un taux ou un rendement de son nombre d'observations, et qu'il reprenne les champs avertissement que l'API renvoie avec les contenus editoriaux. Le fichier turf-bzh-api.md le dit deja dans sa derniere section : c'est voulu, pour que l'assistant le lise. Le reste, vous le savez : le prelevement PMU s'applique a chaque mise, et un avantage mesure sur le passe n'est pas une garantie sur l'avenir.

Questions frequentes

CLAUDE.md ou skill : lequel ?
Les deux, ils ne servent pas au meme moment. Le CLAUDE.md est lu a chaque session et doit rester court. Le skill ne se charge que lorsque le sujet arrive, et peut donc porter le detail sans peser sur les sessions qui parlent d'autre chose.
Faut-il versionner turf-bzh-api.md ?
Oui. C'est un fichier de contexte : le figer dans le depot garantit que votre code et sa reference avancent ensemble. Retelechargez-le quand l'API evolue, la page de doc annonce les changements.
Comment eviter de bruler le quota en developpant ?
Mettez en cache les reponses pendant que vous mettez au point. Une journee de partants sur disque vous evite des centaines d'appels identiques, et le contenu ne change plus une fois la course courue.

Documentation complete pour les humains : api-docs.php · Specification machine : openapi.json · Votre cle : api-cle.php