---
title: API för utmaningsresultat
description: Bygg topplistor, värmekartor, deltagardetaljer och aktivitetsanalys för utmaningar
order: 6
source_hash: 3be9a0ef7fd2
---

# API för utmaningsresultat

Whitelabel-portaler och andra integrationer som stöds kan bygga en upplevelse för utmaningsresultat med slutpunkterna nedan. Alla använder utmaningskoden och kräver en autentiserad API-begäran.

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

::: warning Integrationsåtkomst
API-uppgifter, autentiseringsflöden som stöds och hastighetsbegränsningar avtalas med DistantRace support. Behandla ett `404` från en resultat- eller analysslutpunkt som att resursen inte är tillgänglig för den aktuella anroparen; samma svar används när sekretessinställningar döljer resursen.
:::

## Slutpunkternas ordning

| Slutpunkt | Användning |
|-----------|------------|
| `GET result-settings/` | Upptäck resultatkolumner, sortering, totaler, sektioner, distanser och tillgängliga valfria vyer |
| `GET heatmap/` | Läs in samlade celler för träningsdensitet när `show_heatmap` är aktiverat |
| `GET results/{challenger_id}/detailed/` | Läs in en deltagares resultat, samlad statistik, jämförelser och aktivitetstidslinje |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Läs in mellantider, diagram och tillåten sensoranalys för en accepterad aktivitet |

Börja med `result-settings/`. Använd dess flaggor och kolumnbeskrivningar för att avgöra vilka kontroller och skärmar som ska visas, i stället för att anta att alla utmaningar har samma resultatformat.

Hämta värden för `challenger_id` från utmaningens paginerade topplista `results/`. Aktivitets-ID:n kommer från den nästlade listan `activities.results` i det detaljerade svaret.

## Resultatinställningar

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

Svaret beskriver den aktuella presentationen av utmaningsresultaten:

- `primary_column` och `ordered_by` identifierar rankningsmåttet och standardsorteringen.
- `columns` och `team_columns` är ordnade visningsbeskrivningar; deras nycklar motsvarar fält i deltagarnas och lagens topplisterader.
- `totals`, `progress`, `sections`, `distances` och `participant_data` ger valfritt sammanhang för hela utmaningen.
- `show_map` och `show_heatmap` talar om för klienten vilka kartvyer som ska erbjudas. `show_analytics` anger om anroparen får se fysiologiska aktivitetsdata för en annan deltagare; det begränsar inte anroparens egen åtkomliga analys.
- `results_limited` är `null` när resultaten är obegränsade. Ett tal innebär att anroparen bara kan se så många topprader och att kontroller för filtrering, sortering och paginering av resultat ska döljas.

Värdena är anpassade till anroparen. Samma utmaning kan till exempel ge obegränsade inställningar till en deltagare och begränsade inställningar till en inloggad användare som inte deltar.

## Värmekarta över träningspass

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

Värmekartan samlar accepterade GPS-aktiviteter i rutnätsceller på cirka 150 meter. Varje cell är `[longitude, latitude, weight]`, där vikten är antalet unika aktiviteter som passerade genom den. En aktivitet bidrar högst en gång till varje cell och träningspass som markerats som privata i källappen utesluts.

Värmekartor genereras vid behov. När ingen lagrad värmekarta finns startar den första begäran generering i bakgrunden och returnerar:

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

Fråga igen efter några sekunder. Ett färdigt svar innehåller `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` och `cells`. Lagrade data kan fortsätta att visas medan en inaktuell värmekarta uppdateras i bakgrunden.

Använd `max_weight` för att normalisera ett viktat densitetslager. Om `truncated` är `true` innehåller svaret de tyngsta cellerna i stället för alla genererade celler.

Slutpunkten returnerar `404` när arrangören inte har aktiverat `show_heatmap`, under en period med dolda resultat eller när offentliga resultat är begränsade och anroparen inte är deltagare.

## Detaljerat deltagarresultat

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

Svaret kombinerar:

- Deltagarens topplisterad, valda distans, placering och `result_rank_total`.
- `statistics`, till exempel distans, varaktighet, tempo eller hastighet, energi, steg, antal aktiviteter, aktiva dagar, längsta serie och genomsnittspuls när den finns.
- `is_own_result`, som anger om raden tillhör den autentiserade deltagaren.
- `head_to_head`, som bara är tillgängligt när en deltagare visar sitt eget resultat. Det innehåller placering och percentil, rankningsmåttet, avstånd till närliggande konkurrenter och ledaren, fältets genomsnitt samt pallraderna.
- `activities`, en nästlad paginerad lista över accepterade och synliga aktiviteter som tillgodoräknats resultatet. Varje rad innehåller grundläggande träningsmetadata, genomsnittstempo, en ruttform när den finns och `has_analytics`.

För ett resultat med fast distans slutar aktivitetslistan vid den aktivitet som slutförde den valda distansen. Senare aktiviteter visas inte eftersom de inte bidrog till det resultatet.

### Nästlad aktivitetspaginering

Aktivitetslistan har de vanliga fälten `count`, `next`, `previous` och `results`, men använder särskilda frågeparametrar så att den inte krockar med paginering på toppnivån:

| Parameter | Betydelse |
|-----------|-----------|
| `activities_page` | Sidnummer, med början på 1 |
| `activities_per_page` | Poster per sida; standardvärdet är 25 och underställt API:ets maxgräns |

### Platsoberoende ruttformer

Rutterna i aktivitetstidslinjen är inte geografiska koordinater. Servern flyttar och skalar varje GPS-spår till ett fast SVG-koordinatutrymme på `158 × 108` och returnerar endast:

- `path` — SVG-sökvägsdata
- `start` och `end` — punkter i det normaliserade koordinatutrymmet
- `point_count` — antal punkter i den returnerade formen

Absolut latitud, longitud, gränser och centrum ingår inte. Samma rutt flyttad till en annan plats ger samma form, så den passar som miniatyr men kan inte ritas på en geografisk karta.

## Analys per aktivitet

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

Aktiviteten måste vara accepterad, synlig och kopplad till just det deltagarresultatet. Svaret innehåller grundläggande distans, varaktighet, tempo och hastighet samt all analys som kan härledas från de lagrade dataströmmarna:

| Block | Innehåll |
|-------|----------|
| `route` | Samma platsoberoende ruttform som används i aktivitetstidslinjen |
| `km_splits` | Hela kilometermellantider plus en valfri sista delsträcka, inklusive markeringar för snabbast och långsammast |
| `elevation` | Nedsamplad höjdprofil, stigning, höjdförlust, minimum och maximum |
| `heart_rate` och `hr_zones` | Nedsamplad pulsserie, genomsnitt, maximum, referensmaximum och tid i fem zoner |
| `cadence` | Nedsamplad kadensserie och genomsnitt |
| `effort_score` | Pulsbaserad uppskattning av ansträngning |

Varje block kan oberoende vara `null` eftersom leverantörer och enheter tillhandahåller olika dataströmmar. `has_streams` anger om användbar strömanalys finns. `x_kind` anger om diagrammets x-värden representerar kumulativ distans eller förfluten tid.

Block med låg känslighet — ruttform, mellantider, tempo och höjd — är tillgängliga för alla anropare som kan nå resultatet. Fysiologiska block — puls, zoner, kadens och ansträngning — är alltid tillgängliga för anroparens eget nåbara resultat. För en annan deltagares aktivitet returneras de bara när arrangören har aktiverat `show_analytics` och anroparen uppfyller reglerna för resultatsynlighet. Annars är blocken `null` och `physio_restricted` är `true`.

## Regler för synlighet och sekretess

| Inställning eller tillstånd | Effekt |
|-----------------------------|--------|
| `show_heatmap` av | Värmekartan returnerar `404`; `result-settings` rapporterar `show_heatmap: false` |
| `show_analytics` av | Andra deltagares fysiologiska aktivitetsblock tas bort; egen nåbar analys påverkas inte |
| Period med dolda resultat aktiv | Detaljerade deltagarresultat döljs; värmekartan returnerar `404`; `show_heatmap` och `show_analytics` är false |
| `hide_results_public` på | Inloggade användare som inte deltar begränsas till det konfigurerade antalet toppresultat, kan inte läsa in värmekartan och kan inte se andra deltagares fysiologiska analys |
| Träningspasset är inte accepterat eller synligt | Det utelämnas från tidslinjen och kan inte öppnas genom analysslutpunkten |

Utmaningsdeltagare behåller åtkomst till fullständiga resultat utanför en period med dolda resultat. Organisationens personal kan ha annan åtkomst än deltagarna, men klienter ska ändå följa de anroparspecifika värden som returneras av `result-settings/`.

## Relaterat

- [Offentlig API-översikt](public-api-overview.md)
- [Whitelabel och företagsinställningar](../running-events/whitelabel-and-enterprise-setup.md)