Introduction#

Version générique : tous les champs sont listés avec la formule minimale qui y donne accès (FREE, PRO, PARTNER). Envoyez votre clé API (Authorization: Bearer th_live_…) ou connectez-vous à votre espace développeur pour obtenir la version personnalisée.

L'API Trail Horizon donne accès au catalogue des courses de trail publiées sur Trail Horizon, en lecture seule et au format JSON.

• Base URL : https://trailhorizon.fr/api/v1
• Format : JSON, UTF-8. Les dates sont au format ISO 8601.
• Version : /v1 est stable. Ajouter un champ n'est pas un changement cassant : ignorez les champs inconnus. Un changement cassant (renommage, suppression, changement de type, nouvelle valeur d'une liste fermée) donnera lieu à /v2.

Authentification#

Envoyez votre clé API dans le header Authorization de chaque requête. Les clés de production ont la forme th_live_ suivie de 32 caractères (les clés de test, th_test_, sont décrites dans Domaines autorisés). Elles se créent dans votre espace développeur et ne sont affichées qu'une fois.

Envoyez aussi, sur chaque appel, le header X-TrailHorizon-Origin : le domaine du site qui exploite les données, parmi vos domaines autorisés. Sans ce header, l'API répond 403 origin_required.

curl -H "Authorization: Bearer th_live_VOTRE_CLE" \
  -H "X-TrailHorizon-Origin: votre-domaine.fr" \
  "https://trailhorizon.fr/api/v1/races"

API serveur à serveur : appelez-la depuis votre backend, jamais depuis un navigateur. Elle n'envoie aucun en-tête CORS (les appels depuis une page web sont bloqués) et une clé placée dans du code client serait exposée à tous.

Conditions d'utilisation et délai de grâce#

Quand une nouvelle version des conditions d'utilisation est publiée (version actuelle : 2026-11-03), votre accès continue de fonctionner pendant un délai de grâce de 30 jours à partir de la date de la version. Pendant ce délai, chaque réponse porte l'en-tête X-TrailHorizon-Terms: update-required; deadline=<date ISO 8601> : acceptez les nouvelles conditions depuis votre espace développeur avant cette date. Passé le délai, l'API répond 403 tos_outdated jusqu'à l'acceptation. Un compte qui n'a jamais accepté les conditions reçoit 403 tos_not_accepted immédiatement, sans délai. Dans ces deux cas, les envois de webhooks sont mis en attente et reprennent dès l'acceptation des conditions.

Endpoints#

Réponses et champs#

Seuls les champs autorisés pour votre compte sont renvoyés. Un champ non autorisé est absent de la réponse (jamais null). Un champ null signifie que la donnée n'est pas renseignée. Voir le catalogue des champs.

Quotas#

Les quotas sont comptés par compte (toutes clés de production confondues). Les clés de test (th_test_) ont leurs propres compteurs, séparés de ceux de la production. Valeurs des formules publiques ; la formule PARTNER est définie par contrat.

En-têtes de limitation#

Chaque réponse porte les en-têtes suivants (le plus contraignant de la minute et du jour), à l'exception des refus d'origine (origin_*), qui ne consomment pas de quota et ne portent pas ces en-têtes. Avec une clé de test, ils décrivent le quota de test :

Les requêtes refusées par un quota ne sont pas décomptées. Un refus d'origine (origin_*) ne l'est pas non plus : il est journalisé et compté dans vos erreurs du jour. Les autres erreurs (4xx) sont, elles, comptées comme des requêtes.

Erreurs#

Toutes les erreurs ont la même enveloppe :

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid \"limit\": must be between 1 and 100."
  }
}

Suivre les mises à jour#

Relisez le catalogue à intervalle régulier (GET /races paginé, ou GET /export). Le champ updatedAt de chaque course (s'il est disponible pour votre compte) permet d'ignorer ce qui n'a pas changé. Les comptes disposant des webhooks sont notifiés à chaque changement.

Licence et attribution#

Votre usage des données est encadré par les conditions d'utilisation de l'API (version 2026-11-03) : licence non commerciale (FREE), commerciale (PRO) ou par contrat (PARTNER), revente des données interdite.

Citation obligatoire : chaque course affichée doit porter la mention « Données : Trail Horizon » avec un lien, sans nofollow, vers l'URL url de la course, reprise telle quelle, paramètres de requête compris (les paramètres utm_* permettent à Trail Horizon d'identifier votre trafic : ne les retirez pas et n'en ajoutez pas).

Données : <a href="https://trailhorizon.fr/races/…?utm_source=partner-votre-slug&amp;utm_medium=api&amp;utm_campaign=race-data">Trail Horizon</a>

Pages de la documentation#

• Domaines autorisés
• GET /races
• GET /races/{id}
• GET /races/{id}/editions
• GET /export
• Webhooks
• Catalogue des champs