---
title: API wyników wyzwań
description: Twórz rankingi wyzwań, mapy cieplne, szczegóły uczestników i analizy aktywności
order: 6
source_hash: 3be9a0ef7fd2
slug: api-wynikow-wyzwan
---

# API wyników wyzwań

Portale whitelabel i inne obsługiwane integracje mogą tworzyć interfejs wyników wyzwania za pomocą poniższych punktów końcowych. Wszystkie używają kodu wyzwania i wymagają uwierzytelnionego żądania API.

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

::: warning Dostęp integracji
Dane uwierzytelniające API, obsługiwane przepływy uwierzytelniania i limity wywołań są uzgadniane z pomocą techniczną DistantRace. Odpowiedź `404` z punktu końcowego wyników lub analiz należy traktować jako informację, że zasób jest niedostępny dla bieżącego wywołującego; ta sama odpowiedź jest używana, gdy zasób ukrywają ustawienia prywatności.
:::

## Kolejność punktów końcowych

| Punkt końcowy | Zastosowanie |
|---------------|--------------|
| `GET result-settings/` | Odczyt kolumn wyników, sortowania, sum, sekcji, dystansów i dostępnych widoków opcjonalnych |
| `GET heatmap/` | Pobranie zagregowanych komórek gęstości treningów, gdy włączono `show_heatmap` |
| `GET results/{challenger_id}/detailed/` | Pobranie wyniku jednego uczestnika, statystyk zbiorczych, porównań i osi czasu aktywności |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Pobranie międzyczasów, wykresów i dozwolonych analiz danych z czujników dla jednej zaakceptowanej aktywności |

Zacznij od `result-settings/`. Na podstawie jego flag i opisów kolumn wybierz elementy sterujące i ekrany do wyświetlenia, zamiast zakładać, że każde wyzwanie ma taki sam format wyników.

Wartości `challenger_id` pobierz z podzielonego na strony rankingu `results/` wyzwania. Identyfikatory aktywności pochodzą z zagnieżdżonej listy `activities.results` w odpowiedzi szczegółowej.

## Ustawienia wyników

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

Odpowiedź opisuje bieżący sposób prezentacji wyników wyzwania:

- `primary_column` i `ordered_by` określają miarę rankingu i domyślną kolejność.
- `columns` i `team_columns` to uporządkowane opisy renderowania; ich klucze odpowiadają polom w wierszach rankingów uczestników i zespołów.
- `totals`, `progress`, `sections`, `distances` i `participant_data` dostarczają opcjonalnego kontekstu całego wyzwania.
- `show_map` i `show_heatmap` wskazują klientowi, które widoki mapy udostępnić. `show_analytics` określa, czy wywołujący może zobaczyć fizjologiczne dane aktywności innego uczestnika; nie ogranicza dostępnych analiz własnych wywołującego.
- `results_limited` ma wartość `null` dla wyników bez ograniczeń. Liczba oznacza, że wywołujący widzi tylko tyle najwyższych wierszy, a elementy filtrowania, sortowania i stronicowania wyników powinny być ukryte.

Wartości te zależą od wywołującego. To samo wyzwanie może na przykład zwrócić ustawienia bez ograniczeń uczestnikowi, a ograniczone ustawienia zalogowanej osobie niebędącej uczestnikiem.

## Mapa cieplna treningów

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

Mapa cieplna agreguje zaakceptowane aktywności GPS w komórkach siatki o rozmiarze około 150 metrów. Każda komórka ma postać `[longitude, latitude, weight]`, gdzie `weight` oznacza liczbę różnych aktywności, które przez nią przebiegały. Aktywność wnosi wkład do każdej komórki najwyżej raz, a treningi oznaczone jako prywatne w aplikacji źródłowej są wykluczane.

Mapy cieplne są generowane na żądanie. Gdy nie ma zapisanej mapy, pierwsze żądanie uruchamia generowanie w tle i zwraca:

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

Ponów żądanie po kilku sekundach. Gotowa odpowiedź zawiera `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` i `cells`. Zapisane dane mogą być udostępniane, gdy nieaktualna mapa cieplna jest odświeżana w tle.

Użyj `max_weight`, aby znormalizować ważoną warstwę gęstości. Jeśli `truncated` ma wartość `true`, odpowiedź zawiera komórki o największej wadze zamiast wszystkich wygenerowanych komórek.

Punkt końcowy zwraca `404`, gdy organizator nie włączył `show_heatmap`, podczas okresu ukrywania wyników albo gdy wyniki publiczne są ograniczone, a wywołujący nie jest uczestnikiem.

## Szczegółowy wynik uczestnika

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

Odpowiedź łączy:

- Wiersz rankingu uczestnika, wybrany dystans, miejsce i `result_rank_total`.
- `statistics`, takie jak dystans, czas trwania, tempo lub prędkość, energia, kroki, liczba aktywności, aktywne dni, najdłuższa seria oraz średnie tętno, jeśli jest dostępne.
- `is_own_result`, które wskazuje, czy wiersz należy do uwierzytelnionego uczestnika.
- `head_to_head`, dostępne tylko wtedy, gdy uczestnik wyświetla własny wynik. Obejmuje miejsce i percentyl, miarę rankingu, różnice do najbliższych rywali i lidera, średnią stawki oraz wiersze podium.
- `activities`, zagnieżdżoną, stronicowaną listę zaakceptowanych i widocznych aktywności zaliczonych do wyniku. Każdy wiersz zawiera podstawowe metadane treningu, średnie tempo, kształt trasy, gdy jest dostępny, oraz `has_analytics`.

Dla wyniku na ustalonym dystansie lista aktywności kończy się na aktywności, która ukończyła wybrany dystans. Późniejsze aktywności nie są wyświetlane, ponieważ nie przyczyniły się do tego wyniku.

### Stronicowanie zagnieżdżonych aktywności

Lista aktywności ma standardowe pola `count`, `next`, `previous` i `results`, ale używa osobnych parametrów zapytania, aby nie kolidować ze stronicowaniem najwyższego poziomu:

| Parametr | Znaczenie |
|----------|-----------|
| `activities_page` | Numer strony, zaczynając od 1 |
| `activities_per_page` | Liczba elementów na stronie; domyślnie 25, z uwzględnieniem maksimum API |

### Kształty tras bez danych o położeniu

Trasy na osi czasu aktywności nie są współrzędnymi geograficznymi. Serwer przesuwa i skaluje każdy ślad GPS do stałej przestrzeni współrzędnych SVG `158 × 108` i zwraca tylko:

- `path` — dane ścieżki SVG
- `start` i `end` — punkty w znormalizowanej przestrzeni współrzędnych
- `point_count` — liczba punktów w zwróconym kształcie

Bezwzględna szerokość i długość geograficzna, granice oraz środek nie są dołączane. Ta sama trasa przeniesiona w inne miejsce daje ten sam kształt, dlatego nadaje się do miniatury, ale nie można jej nanieść na mapę geograficzną.

## Analizy poszczególnych aktywności

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

Aktywność musi być zaakceptowana, widoczna i przypisana dokładnie do tego wyniku uczestnika. Odpowiedź zawiera podstawowy dystans, czas trwania, tempo i prędkość oraz analizy, które można uzyskać z zapisanych strumieni:

| Blok | Zawartość |
|------|-----------|
| `route` | Ten sam pozbawiony położenia kształt trasy, co na osi czasu aktywności |
| `km_splits` | Pełne międzyczasy kilometrowe oraz opcjonalny ostatni częściowy odcinek, ze znacznikami najszybszego i najwolniejszego |
| `elevation` | Profil ze zmniejszoną liczbą punktów, przewyższenie w górę i w dół, minimum i maksimum |
| `heart_rate` i `hr_zones` | Szereg tętna ze zmniejszoną liczbą punktów, średnia, maksimum, referencyjne maksimum i czas w pięciu strefach |
| `cadence` | Szereg kadencji ze zmniejszoną liczbą punktów i średnia |
| `effort_score` | Szacowany wysiłek na podstawie tętna |

Poszczególne bloki mogą niezależnie mieć wartość null, ponieważ dostawcy i urządzenia udostępniają różne strumienie. `has_streams` informuje, czy są dostępne użyteczne analizy strumieni. `x_kind` wskazuje, czy wartości x wykresu oznaczają skumulowany dystans czy czas, który upłynął.

Bloki o niskiej wrażliwości — kształt trasy, międzyczasy, tempo i wysokość — są dostępne dla każdego wywołującego, który ma dostęp do wyniku. Bloki fizjologiczne — tętno, strefy, kadencja i wysiłek — są zawsze dostępne dla własnego osiągalnego wyniku wywołującego. W przypadku aktywności innego uczestnika są zwracane tylko wtedy, gdy organizator włączył `show_analytics`, a wywołujący spełnia reguły widoczności wyników. W przeciwnym razie bloki te mają wartość `null`, a `physio_restricted` ma wartość `true`.

## Reguły widoczności i prywatności

| Ustawienie lub stan | Efekt |
|---------------------|-------|
| `show_heatmap` wyłączone | Mapa cieplna zwraca `404`; `result-settings` podaje `show_heatmap: false` |
| `show_analytics` wyłączone | Fizjologiczne bloki aktywności innych uczestników są usuwane; własne dostępne analizy pozostają bez zmian |
| Aktywny okres ukrywania wyników | Szczegóły wyników uczestników są ukryte; mapa cieplna zwraca `404`; `show_heatmap` i `show_analytics` mają wartość false |
| `hide_results_public` włączone | Zalogowani nieuczestnicy są ograniczeni do skonfigurowanej liczby najlepszych wyników, nie mogą pobrać mapy cieplnej ani wyświetlić analiz fizjologicznych innych uczestników |
| Trening niezaakceptowany lub niewidoczny | Jest pomijany na osi czasu i nie można go otworzyć przez punkt końcowy analiz |

Poza okresem ukrywania wyników uczestnicy wyzwania zachowują dostęp do pełnych wyników. Dostęp pracowników organizacji może różnić się od dostępu uczestników, ale klienci powinni zawsze stosować wartości właściwe dla wywołującego, zwracane przez `result-settings/`.

## Powiązane artykuły

- [Przegląd Publicznego API](public-api-overview.md)
- [Whitelabel i konfiguracja dla przedsiębiorstw](../running-events/whitelabel-and-enterprise-setup.md)