---
title: API des résultats de challenge
description: Créez des classements, cartes thermiques, fiches de participants et analyses d'activités pour les challenges
order: 6
source_hash: 3be9a0ef7fd2
slug: api-des-resultats-de-challenge
---

# API des résultats de challenge

Les portails en marque blanche et les autres intégrations prises en charge peuvent créer une expérience de résultats de challenge avec les points de terminaison ci-dessous. Ils utilisent tous le code du challenge et nécessitent une requête API authentifiée.

```
/api/v1/gamification/challenge/{code}/
```

::: warning Accès aux intégrations
Les identifiants API, les flux d'authentification pris en charge et les limites de débit sont définis avec l'assistance DistantRace. Considérez une réponse `404` d'un point de terminaison de résultats ou d'analyses comme une indisponibilité pour l'appelant actuel ; la même réponse est utilisée lorsque les paramètres de confidentialité masquent la ressource.
:::

## Séquence des points de terminaison

| Point de terminaison | Utilisation |
|----------------------|-------------|
| `GET result-settings/` | Découvrir les colonnes de résultats, le tri, les totaux, les sections, les distances et les vues facultatives disponibles |
| `GET heatmap/` | Charger les cellules agrégées de densité des entraînements lorsque `show_heatmap` est activé |
| `GET results/{challenger_id}/detailed/` | Charger le résultat, les statistiques agrégées, les comparaisons et la chronologie d'activités d'un participant |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Charger les temps intermédiaires, graphiques et analyses de capteurs autorisées pour une activité acceptée |

Commencez par `result-settings/`. Utilisez ses indicateurs et descripteurs de colonnes pour décider quels contrôles et écrans afficher, plutôt que de supposer que tous les challenges ont le même format de résultats.

Récupérez les valeurs `challenger_id` dans le classement paginé `results/` du challenge. Les identifiants d'activité proviennent de la liste imbriquée `activities.results` de la réponse détaillée.

## Paramètres des résultats

`GET /api/v1/gamification/challenge/{code}/result-settings/`

La réponse décrit la présentation actuelle des résultats du challenge :

- `primary_column` et `ordered_by` indiquent la mesure du classement et l'ordre par défaut.
- `columns` et `team_columns` sont des descripteurs d'affichage ordonnés ; leurs clés correspondent aux champs des lignes des classements des participants et des équipes.
- `totals`, `progress`, `sections`, `distances` et `participant_data` fournissent un contexte facultatif à l'échelle du challenge.
- `show_map` et `show_heatmap` indiquent au client les vues cartographiques à proposer. `show_analytics` indique si cet appelant peut voir les données physiologiques des activités d'un autre participant ; il ne limite pas les analyses accessibles de l'appelant lui-même.
- `results_limited` vaut `null` lorsque les résultats ne sont pas limités. Un nombre signifie que l'appelant ne peut voir que ce nombre de premières lignes ; les commandes de filtrage, de tri et de pagination des résultats doivent alors être masquées.

Ces valeurs dépendent de l'appelant. Le même challenge peut, par exemple, renvoyer des paramètres sans restriction à un participant et des paramètres limités à une personne connectée qui ne participe pas.

## Carte thermique des entraînements

`GET /api/v1/gamification/challenge/{code}/heatmap/`

La carte thermique regroupe les activités GPS acceptées dans des cellules d'environ 150 mètres. Chaque cellule a la forme `[longitude, latitude, weight]`, où `weight` est le nombre d'activités distinctes qui l'ont traversée. Une activité ne contribue qu'une seule fois à chaque cellule, et les entraînements marqués comme privés dans leur application source sont exclus.

Les cartes thermiques sont générées à la demande. Lorsqu'aucune carte n'est enregistrée, la première requête lance sa génération en arrière-plan et renvoie :

```json
{"status": "pending"}
```

Interrogez de nouveau le point de terminaison après quelques secondes. Une réponse prête contient `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` et `cells`. Les données enregistrées peuvent être fournies pendant qu'une carte thermique obsolète est actualisée en arrière-plan.

Utilisez `max_weight` pour normaliser une couche de densité pondérée. Si `truncated` vaut `true`, la réponse contient les cellules de poids le plus élevé plutôt que toutes les cellules générées.

Le point de terminaison renvoie `404` lorsque l'organisateur n'a pas activé `show_heatmap`, pendant une période de masquage des résultats, ou lorsque les résultats publics sont restreints et que l'appelant ne participe pas.

## Résultat détaillé d'un participant

`GET /api/v1/gamification/challenge/{code}/results/{challenger_id}/detailed/`

La réponse réunit :

- La ligne de classement du participant, la distance choisie, le rang et `result_rank_total`.
- Des `statistics` telles que la distance, la durée, l'allure ou la vitesse, l'énergie, les pas, le nombre d'activités, les jours actifs, la plus longue série et la fréquence cardiaque moyenne lorsqu'elle est disponible.
- `is_own_result`, qui indique si la ligne appartient au participant authentifié.
- `head_to_head`, disponible uniquement lorsqu'un participant consulte son propre résultat. Il comprend son rang et son percentile, la mesure du classement, les écarts avec les concurrents proches et le leader, la moyenne des participants et les lignes du podium.
- `activities`, une liste imbriquée et paginée des activités acceptées et visibles créditées au résultat. Chaque ligne comprend les métadonnées principales de l'entraînement, l'allure moyenne, une forme de parcours lorsqu'elle est disponible et `has_analytics`.

Pour un résultat à distance fixe, la liste des activités s'arrête à l'activité qui a permis d'atteindre la distance choisie. Les activités ultérieures n'apparaissent pas, car elles n'ont pas contribué à ce résultat.

### Pagination imbriquée des activités

La liste des activités comporte les champs habituels `count`, `next`, `previous` et `results`, mais utilise des paramètres de requête dédiés pour ne pas entrer en conflit avec la pagination de premier niveau :

| Paramètre | Signification |
|-----------|---------------|
| `activities_page` | Numéro de page, à partir de 1 |
| `activities_per_page` | Éléments par page ; 25 par défaut et soumis au maximum de l'API |

### Formes de parcours sans localisation

Les parcours de la chronologie des activités ne sont pas des coordonnées géographiques. Le serveur translate et met à l'échelle chaque trace GPS dans un espace de coordonnées SVG fixe de `158 × 108` et renvoie uniquement :

- `path` — données du tracé SVG
- `start` et `end` — points dans l'espace de coordonnées normalisé
- `point_count` — nombre de points dans la forme renvoyée

La latitude, la longitude, les limites et le centre absolus ne sont pas inclus. Un même parcours déplacé à un autre endroit produit la même forme : elle convient donc à une miniature, mais ne peut pas être placée sur une carte géographique.

## Analyses par activité

`GET /api/v1/gamification/challenge/{code}/results/{challenger_id}/activities/{activity_id}/analytics/`

L'activité doit être acceptée, visible et rattachée exactement au résultat de ce participant. La réponse contient la distance, la durée, l'allure et la vitesse principales, ainsi que les analyses pouvant être dérivées des flux enregistrés :

| Bloc | Contenu |
|------|---------|
| `route` | La même forme de parcours sans localisation que dans la chronologie des activités |
| `km_splits` | Kilomètres intermédiaires complets et, éventuellement, dernier segment partiel, avec repères du plus rapide et du plus lent |
| `elevation` | Profil sous-échantillonné, dénivelés positif et négatif, minimum et maximum |
| `heart_rate` et `hr_zones` | Série de fréquence cardiaque sous-échantillonnée, moyenne, maximum, maximum de référence et temps dans cinq zones |
| `cadence` | Série de cadence sous-échantillonnée et moyenne |
| `effort_score` | Estimation de l'effort dérivée de la fréquence cardiaque |

Chaque bloc peut indépendamment être nul, car les fournisseurs et les appareils transmettent des flux différents. `has_streams` indique si des analyses de flux exploitables sont disponibles. `x_kind` précise si les valeurs x des graphiques représentent la distance cumulée ou le temps écoulé.

Les blocs peu sensibles — forme du parcours, temps intermédiaires, allure et altitude — sont accessibles à tout appelant autorisé à consulter le résultat. Les blocs physiologiques — fréquence cardiaque, zones, cadence et effort — sont toujours disponibles pour le propre résultat accessible de l'appelant. Pour l'activité d'un autre participant, ils ne sont renvoyés que si l'organisateur a activé `show_analytics` et si l'appelant respecte les règles de visibilité des résultats. Dans le cas contraire, ces blocs valent `null` et `physio_restricted` vaut `true`.

## Règles de visibilité et de confidentialité

| Paramètre ou état | Effet |
|-------------------|-------|
| `show_heatmap` désactivé | La carte thermique renvoie `404` ; `result-settings` indique `show_heatmap: false` |
| `show_analytics` désactivé | Les blocs physiologiques des activités des autres participants sont retirés ; les analyses accessibles de l'appelant ne changent pas |
| Période de masquage des résultats active | Le détail des résultats des participants est masqué ; la carte thermique renvoie `404` ; `show_heatmap` et `show_analytics` valent false |
| `hide_results_public` activé | Les non-participants connectés sont limités au nombre configuré de meilleurs résultats, ne peuvent pas charger la carte thermique ni consulter les analyses physiologiques des autres participants |
| Entraînement non accepté ou non visible | Il est omis de la chronologie et ne peut pas être ouvert via le point de terminaison d'analyses |

Les participants au challenge conservent l'accès à l'intégralité des résultats en dehors d'une période de masquage. L'accès du personnel de l'organisation peut différer de celui des participants, mais les clients doivent toujours suivre les valeurs propres à l'appelant renvoyées par `result-settings/`.

## Articles connexes

- [Aperçu de l'API publique](public-api-overview.md)
- [Configuration en marque blanche et pour les entreprises](../running-events/whitelabel-and-enterprise-setup.md)