---
title: Challenge-Ergebnis-API
description: Erstellen Sie Challenge-Ranglisten, Heatmaps, Teilnehmerdetails und Aktivitätsanalysen
order: 6
source_hash: 3be9a0ef7fd2
slug: challenge-ergebnis-api
---

# Challenge-Ergebnis-API

Whitelabel-Portale und andere unterstützte Integrationen können mit den folgenden Endpunkten eine Ergebnisansicht für Challenges erstellen. Sie verwenden alle den Challenge-Code und erfordern eine authentifizierte API-Anfrage.

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

::: warning Integrationszugriff
API-Anmeldedaten, unterstützte Authentifizierungsabläufe und Ratenlimits werden mit dem DistantRace-Support vereinbart. Behandeln Sie eine `404` von einem Ergebnis- oder Analyseendpunkt als für den aktuellen Aufrufer nicht verfügbar; dieselbe Antwort wird verwendet, wenn Datenschutzeinstellungen die Ressource ausblenden.
:::

## Reihenfolge der Endpunkte

| Endpunkt | Verwendung |
|----------|------------|
| `GET result-settings/` | Ergebnisspalten, Sortierung, Gesamtsummen, Abschnitte, Distanzen und verfügbare optionale Ansichten ermitteln |
| `GET heatmap/` | Aggregierte Zellen der Workout-Dichte laden, wenn `show_heatmap` aktiviert ist |
| `GET results/{challenger_id}/detailed/` | Ergebnis, aggregierte Statistiken, Vergleiche und Aktivitätszeitleiste eines Teilnehmers laden |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Splits, Diagramme und zulässige Sensordatenanalysen für eine akzeptierte Aktivität laden |

Beginnen Sie mit `result-settings/`. Verwenden Sie dessen Flags und Spaltenbeschreibungen, um zu entscheiden, welche Steuerelemente und Ansichten dargestellt werden, statt davon auszugehen, dass jede Challenge dasselbe Ergebnisformat hat.

Die Werte für `challenger_id` stammen aus der paginierten `results/`-Rangliste der Challenge. Aktivitäts-IDs stammen aus der verschachtelten Liste `activities.results` in der Detailantwort.

## Ergebniseinstellungen

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

Die Antwort beschreibt die aktuelle Ergebnisdarstellung der Challenge:

- `primary_column` und `ordered_by` geben die Ranglistenmetrik und die Standardsortierung an.
- `columns` und `team_columns` sind geordnete Darstellungsbeschreibungen; ihre Schlüssel entsprechen Feldern in Teilnehmer- und Team-Ranglistenzeilen.
- `totals`, `progress`, `sections`, `distances` und `participant_data` liefern optionalen Challenge-weiten Kontext.
- `show_map` und `show_heatmap` geben dem Client vor, welche Kartenansichten angeboten werden. `show_analytics` gibt an, ob dieser Aufrufer physiologische Aktivitätsdaten eines anderen Teilnehmers sehen darf; die eigenen erreichbaren Analysen des Aufrufers werden dadurch nicht eingeschränkt.
- `results_limited` ist bei uneingeschränkten Ergebnissen `null`. Eine Zahl bedeutet, dass der Aufrufer nur so viele oberste Zeilen sehen kann; Filter-, Sortier- und Seitennavigationsfunktionen für Ergebnisse sollten dann ausgeblendet werden.

Diese Werte hängen vom Aufrufer ab. Dieselbe Challenge kann einem Teilnehmer beispielsweise uneingeschränkte Einstellungen und einem angemeldeten Nicht-Teilnehmer eingeschränkte Einstellungen liefern.

## Workout-Heatmap

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

Die Heatmap fasst akzeptierte GPS-Aktivitäten in etwa 150 Meter großen Rasterzellen zusammen. Jede Zelle hat die Form `[longitude, latitude, weight]`; der Wert `weight` ist die Anzahl verschiedener Aktivitäten, die diese Zelle durchquert haben. Eine Aktivität zählt höchstens einmal je Zelle, und in der Quell-App als privat markierte Workouts werden ausgeschlossen.

Heatmaps werden bei Bedarf erzeugt. Ist noch keine Heatmap gespeichert, startet die erste Anfrage die Hintergrundgenerierung und liefert:

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

Fragen Sie nach einigen Sekunden erneut ab. Eine fertige Antwort enthält `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` und `cells`. Gespeicherte Daten können ausgeliefert werden, während eine veraltete Heatmap im Hintergrund aktualisiert wird.

Verwenden Sie `max_weight`, um eine gewichtete Dichteschicht zu normalisieren. Wenn `truncated` den Wert `true` hat, enthält die Antwort die am stärksten gewichteten Zellen statt aller erzeugten Zellen.

Der Endpunkt liefert `404`, wenn der Organisator `show_heatmap` nicht aktiviert hat, während eines Zeitfensters mit ausgeblendeten Ergebnissen oder wenn öffentliche Ergebnisse eingeschränkt sind und der Aufrufer kein Teilnehmer ist.

## Detailliertes Teilnehmerergebnis

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

Die Antwort kombiniert:

- Ranglistenzeile, gewählte Distanz, Rang und `result_rank_total` des Teilnehmers.
- `statistics` wie Distanz, Dauer, Pace oder Geschwindigkeit, Energie, Schritte, Aktivitätsanzahl, aktive Tage, längste Serie und durchschnittliche Herzfrequenz, sofern verfügbar.
- `is_own_result`, das angibt, ob die Zeile zum authentifizierten Teilnehmer gehört.
- `head_to_head`, das nur verfügbar ist, wenn ein Teilnehmer sein eigenes Ergebnis betrachtet. Es enthält Rang und Perzentil, die Ranglistenmetrik, Abstände zu benachbarten Teilnehmern und zum Führenden, den Felddurchschnitt sowie Podiumszeilen.
- `activities`, eine verschachtelte paginierte Liste akzeptierter, sichtbarer Aktivitäten, die dem Ergebnis gutgeschrieben wurden. Jede Zeile enthält grundlegende Workout-Metadaten, durchschnittliche Pace, eine Routenform, sofern verfügbar, und `has_analytics`.

Bei einem Ergebnis über eine feste Distanz endet die Aktivitätsliste bei der Aktivität, mit der die gewählte Distanz erreicht wurde. Spätere Aktivitäten erscheinen nicht, weil sie nicht zu diesem Ergebnis beigetragen haben.

### Verschachtelte Aktivitäts-Paginierung

Die Aktivitätsliste enthält die üblichen Felder `count`, `next`, `previous` und `results`, verwendet jedoch eigene Abfrageparameter, damit sie nicht mit der Paginierung auf oberster Ebene kollidiert:

| Parameter | Bedeutung |
|-----------|-----------|
| `activities_page` | Seitennummer, beginnend bei 1 |
| `activities_per_page` | Einträge pro Seite; Standardwert 25, begrenzt durch das API-Maximum |

### Routenformen ohne Positionsdaten

Routen in der Aktivitätszeitleiste sind keine geografischen Koordinaten. Der Server verschiebt und skaliert jede GPS-Spur in einen festen SVG-Koordinatenraum von `158 × 108` und liefert nur:

- `path` — SVG-Pfaddaten
- `start` und `end` — Punkte im normalisierten Koordinatenraum
- `point_count` — Anzahl der Punkte in der gelieferten Form

Absolute Werte für Breitengrad, Längengrad, Grenzen und Mittelpunkt sind nicht enthalten. Dieselbe an einen anderen Ort verschobene Route erzeugt dieselbe Form. Sie eignet sich daher für ein Vorschaubild, kann aber nicht auf einer geografischen Karte dargestellt werden.

## Analyse einzelner Aktivitäten

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

Die Aktivität muss akzeptiert und sichtbar sein und genau diesem Teilnehmerergebnis zugeordnet sein. Die Antwort enthält grundlegende Werte für Distanz, Dauer, Pace und Geschwindigkeit sowie alle Analysen, die sich aus den gespeicherten Datenströmen ableiten lassen:

| Block | Inhalt |
|-------|--------|
| `route` | Dieselbe positionsfreie Routenform wie in der Aktivitätszeitleiste |
| `km_splits` | Volle Kilometersplits sowie optional ein abschließender Teilsplit, einschließlich Markierungen für den schnellsten und langsamsten Split |
| `elevation` | Reduziertes Profil, Anstieg, Abstieg, Minimum und Maximum |
| `heart_rate` und `hr_zones` | Reduzierte Herzfrequenzreihe, Durchschnitt, Maximum, Referenzmaximum und Zeit in fünf Zonen |
| `cadence` | Reduzierte Trittfrequenzreihe und Durchschnitt |
| `effort_score` | Aus der Herzfrequenz abgeleitete Belastungsschätzung |

Blöcke sind unabhängig voneinander nullfähig, da Anbieter und Geräte unterschiedliche Datenströme liefern. `has_streams` gibt an, ob nutzbare Datenstromanalysen vorhanden sind. `x_kind` gibt an, ob die x-Werte eines Diagramms die kumulierte Distanz oder die verstrichene Zeit darstellen.

Blöcke mit geringer Sensibilität – Routenform, Splits, Pace und Höhe – stehen jedem Aufrufer zur Verfügung, der das Ergebnis erreichen kann. Physiologische Blöcke – Herzfrequenz, Zonen, Trittfrequenz und Belastung – stehen dem Aufrufer für sein eigenes erreichbares Ergebnis immer zur Verfügung. Bei der Aktivität eines anderen Teilnehmers werden sie nur geliefert, wenn der Organisator `show_analytics` aktiviert hat und der Aufrufer die Sichtbarkeitsregeln für Ergebnisse erfüllt. Andernfalls sind diese Blöcke `null` und `physio_restricted` hat den Wert `true`.

## Sichtbarkeits- und Datenschutzregeln

| Einstellung oder Status | Auswirkung |
|-------------------------|------------|
| `show_heatmap` aus | Heatmap liefert `404`; `result-settings` meldet `show_heatmap: false` |
| `show_analytics` aus | Physiologische Aktivitätsblöcke anderer Teilnehmer werden entfernt; eigene erreichbare Analysen bleiben unverändert |
| Zeitfenster mit ausgeblendeten Ergebnissen aktiv | Detailansichten von Teilnehmerergebnissen sind ausgeblendet; Heatmap liefert `404`; `show_heatmap` und `show_analytics` sind false |
| `hide_results_public` an | Angemeldete Nicht-Teilnehmer sind auf die konfigurierte Zahl oberster Ergebnisse begrenzt, können die Heatmap nicht laden und keine physiologischen Analysen anderer Teilnehmer sehen |
| Workout nicht akzeptiert oder nicht sichtbar | Es wird in der Zeitleiste ausgelassen und kann über den Analyseendpunkt nicht geöffnet werden |

Challenge-Teilnehmer behalten außerhalb eines Zeitfensters mit ausgeblendeten Ergebnissen Zugriff auf die vollständigen Ergebnisse. Der Zugriff von Organisationsmitarbeitern kann sich vom Teilnehmerzugriff unterscheiden; Clients sollten dennoch den aufruferspezifischen Werten aus `result-settings/` folgen.

## Verwandte Themen

- [Öffentliche API-Übersicht](public-api-overview.md)
- [Whitelabel- und Enterprise-Einrichtung](../running-events/whitelabel-and-enterprise-setup.md)