---
title: API voor resultaten van uitdagingen
description: Bouw ranglijsten, heatmaps, deelnemersdetails en activiteitsanalyses voor uitdagingen
order: 6
source_hash: 3be9a0ef7fd2
slug: api-voor-uitdagingsresultaten
---

# API voor resultaten van uitdagingen

Whitelabelportalen en andere ondersteunde integraties kunnen met de onderstaande eindpunten een resultaatweergave voor uitdagingen bouwen. Ze gebruiken allemaal de code van de uitdaging en vereisen een geauthenticeerd API-verzoek.

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

::: warning Toegang voor integraties
API-referenties, ondersteunde authenticatiestromen en snelheidslimieten worden afgestemd met de ondersteuning van DistantRace. Behandel een `404` van een resultaat- of analyse-eindpunt als niet beschikbaar voor de huidige aanvrager; dezelfde reactie wordt gebruikt wanneer privacyinstellingen de bron verbergen.
:::

## Volgorde van eindpunten

| Eindpunt | Gebruik |
|----------|-----|
| `GET result-settings/` | Ontdek resultaatkolommen, sortering, totalen, secties, afstanden en welke optionele weergaven beschikbaar zijn |
| `GET heatmap/` | Laad samengevoegde cellen met trainingsdichtheid wanneer `show_heatmap` is ingeschakeld |
| `GET results/{challenger_id}/detailed/` | Laad het resultaat van één deelnemer, samengevoegde statistieken, vergelijkingen en de activiteitstijdlijn |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Laad tussentijden, grafieken en toegestane sensoranalyses voor één geaccepteerde activiteit |

Begin met `result-settings/`. Gebruik de vlaggen en kolombeschrijvingen om te bepalen welke bedieningselementen en schermen moeten worden weergegeven, in plaats van ervan uit te gaan dat elke uitdaging dezelfde resultaatindeling heeft.

Haal `challenger_id`-waarden op uit de gepagineerde `results/`-ranglijst van de uitdaging. Activiteits-ID's staan in de geneste lijst `activities.results` van het gedetailleerde antwoord.

## Resultaatinstellingen

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

Het antwoord beschrijft de huidige resultaatweergave van de uitdaging:

- `primary_column` en `ordered_by` geven de rangschikkingsmaatstaf en standaardvolgorde aan.
- `columns` en `team_columns` zijn geordende weergavebeschrijvingen; hun sleutels komen overeen met velden in de ranglijstregels voor deelnemers en teams.
- `totals`, `progress`, `sections`, `distances` en `participant_data` bieden optionele context voor de hele uitdaging.
- `show_map` en `show_heatmap` vertellen de client welke kaartweergaven moeten worden aangeboden. `show_analytics` geeft aan of deze aanvrager de fysiologische activiteitsgegevens van een andere deelnemer mag zien; het beperkt niet de eigen bereikbare analyses van de aanvrager.
- `results_limited` is `null` voor onbeperkte resultaten. Een getal betekent dat de aanvrager alleen dat aantal bovenste regels kan zien en dat bedieningselementen voor filteren, sorteren en pagineren van resultaten moeten worden verborgen.

Deze waarden zijn afgestemd op de aanvrager. Dezelfde uitdaging kan bijvoorbeeld onbeperkte instellingen teruggeven aan een deelnemer en beperkte instellingen aan een ingelogde gebruiker die niet deelneemt.

## Heatmap van trainingen

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

De heatmap voegt geaccepteerde GPS-activiteiten samen in rastercellen van ongeveer 150 meter. Elke cel is `[longitude, latitude, weight]`, waarbij het gewicht het aantal afzonderlijke activiteiten is dat door die cel liep. Een activiteit draagt maximaal één keer bij aan elke cel en trainingen die in de bronapp als privé zijn gemarkeerd, worden uitgesloten.

Heatmaps worden pas gegenereerd wanneer ze nodig zijn. Als er geen opgeslagen heatmap bestaat, start het eerste verzoek de generatie op de achtergrond en wordt het volgende teruggegeven:

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

Vraag de gegevens na enkele seconden opnieuw op. Een gereed antwoord bevat `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` en `cells`. Opgeslagen gegevens kunnen worden weergegeven terwijl een verouderde heatmap op de achtergrond wordt vernieuwd.

Gebruik `max_weight` om een gewogen dichtheidslaag te normaliseren. Als `truncated` `true` is, bevat het antwoord de zwaarst gewogen cellen in plaats van alle gegenereerde cellen.

Het eindpunt geeft `404` terug wanneer de organisator `show_heatmap` niet heeft ingeschakeld, tijdens een periode met verborgen resultaten of wanneer openbare resultaten beperkt zijn en de aanvrager geen deelnemer is.

## Gedetailleerd deelnemersresultaat

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

Het antwoord combineert:

- De ranglijstregel, gekozen afstand, rang en `result_rank_total` van de deelnemer.
- `statistics` zoals afstand, duur, tempo of snelheid, energie, stappen, aantal activiteiten, actieve dagen, langste reeks en gemiddelde hartslag indien beschikbaar.
- `is_own_result`, dat aangeeft of de regel bij de geauthenticeerde deelnemer hoort.
- `head_to_head`, dat alleen beschikbaar is wanneer een deelnemer het eigen resultaat bekijkt. Het bevat rang en percentiel, de rangschikkingsmaatstaf, verschillen met nabije concurrenten en de leider, het gemiddelde van alle deelnemers en de podiumregels.
- `activities`, een geneste gepagineerde lijst van geaccepteerde, zichtbare activiteiten die aan het resultaat zijn toegekend. Elke regel bevat basismetadata van de training, gemiddeld tempo, een routevorm indien beschikbaar en `has_analytics`.

Voor een resultaat met een vaste afstand stopt de activiteitenlijst bij de activiteit waarmee de gekozen afstand is voltooid. Latere activiteiten worden niet weergegeven omdat ze niet aan dat resultaat hebben bijgedragen.

### Paginering van geneste activiteiten

De activiteitenlijst heeft de gebruikelijke velden `count`, `next`, `previous` en `results`, maar gebruikt eigen queryparameters zodat deze niet conflicteren met paginering op het hoogste niveau:

| Parameter | Betekenis |
|-----------|---------|
| `activities_page` | Paginanummer, beginnend bij 1 |
| `activities_per_page` | Items per pagina; standaard 25 en onderworpen aan het API-maximum |

### Locatievrije routevormen

Routes in de activiteitstijdlijn zijn geen geografische coördinaten. De server verschuift en schaalt elke GPS-route naar een vaste SVG-coördinatenruimte van `158 × 108` en geeft alleen het volgende terug:

- `path` — SVG-padgegevens
- `start` en `end` — punten in de genormaliseerde coördinatenruimte
- `point_count` — aantal punten in de teruggegeven vorm

Absolute breedtegraad, lengtegraad, begrenzingen en middelpunt zijn niet opgenomen. Dezelfde route die naar een andere locatie wordt verplaatst, levert dezelfde vorm op. De vorm is daarom geschikt als miniatuur, maar kan niet op een geografische kaart worden getekend.

## Analyse per activiteit

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

De activiteit moet geaccepteerd en zichtbaar zijn en aan precies dit deelnemersresultaat zijn gekoppeld. Het antwoord bevat basisgegevens over afstand, duur, tempo en snelheid, plus alle analyses die uit de opgeslagen gegevensstromen kunnen worden afgeleid:

| Blok | Inhoud |
|-------|----------|
| `route` | Dezelfde locatievrije routevorm die in de activiteitstijdlijn wordt gebruikt |
| `km_splits` | Tussentijden voor volledige kilometers plus een optioneel laatste deel, inclusief markeringen voor het snelste en langzaamste deel |
| `elevation` | Uitgedund hoogteprofiel, stijging, daling, minimum en maximum |
| `heart_rate` en `hr_zones` | Uitgedunde hartslagreeks, gemiddelde, maximum, referentiemaximum en tijd in vijf zones |
| `cadence` | Uitgedunde cadansreeks en gemiddelde |
| `effort_score` | Op hartslag gebaseerde schatting van de inspanning |

Elk blok kan afzonderlijk `null` zijn omdat providers en apparaten verschillende gegevensstromen leveren. `has_streams` geeft aan of bruikbare stroomanalyses beschikbaar zijn. `x_kind` geeft aan of de x-waarden van grafieken de cumulatieve afstand of verstreken tijd vertegenwoordigen.

Blokken met een lage gevoeligheid — routevorm, tussentijden, tempo en hoogte — zijn beschikbaar voor elke aanvrager die toegang heeft tot het resultaat. Fysiologische blokken — hartslag, zones, cadans en inspanning — zijn altijd beschikbaar voor het eigen bereikbare resultaat van de aanvrager. Voor de activiteit van een andere deelnemer worden ze alleen teruggegeven als de organisator `show_analytics` heeft ingeschakeld en de aanvrager aan de zichtbaarheidsregels voor resultaten voldoet. Anders zijn die blokken `null` en is `physio_restricted` `true`.

## Zichtbaarheids- en privacyregels

| Instelling of status | Effect |
|------------------|--------|
| `show_heatmap` uit | Heatmap geeft `404` terug; `result-settings` meldt `show_heatmap: false` |
| `show_analytics` uit | Fysiologische activiteitsblokken van andere deelnemers worden verwijderd; eigen bereikbare analyses blijven ongewijzigd |
| Periode met verborgen resultaten actief | Gedetailleerde deelnemersresultaten worden verborgen; heatmap geeft `404` terug; `show_heatmap` en `show_analytics` zijn false |
| `hide_results_public` aan | Ingelogde niet-deelnemers worden beperkt tot het ingestelde aantal topresultaten, kunnen de heatmap niet laden en kunnen geen fysiologische analyses van andere deelnemers bekijken |
| Training niet geaccepteerd of niet zichtbaar | De training wordt uit de tijdlijn weggelaten en kan niet via het analyse-eindpunt worden geopend |

Deelnemers aan de uitdaging behouden buiten een periode met verborgen resultaten toegang tot alle resultaten. De toegang van organisatiemedewerkers kan verschillen van die van deelnemers, maar clients moeten altijd de aanvragerspecifieke waarden volgen die door `result-settings/` worden teruggegeven.

## Gerelateerd

- [Overzicht van de openbare API](public-api-overview.md)
- [Whitelabel en bedrijfsinstellingen](../running-events/whitelabel-and-enterprise-setup.md)