---
title: Meydan okuma sonuçları API'si
description: Meydan okuma liderlik tabloları, ısı haritaları, katılımcı ayrıntıları ve aktivite analizleri oluşturun
order: 6
source_hash: 3be9a0ef7fd2
slug: meydan-okuma-sonuclari-api
---

# Meydan okuma sonuçları API'si

White-label portallar ve desteklenen diğer entegrasyonlar, aşağıdaki uç noktalarla bir meydan okuma sonuç deneyimi oluşturabilir. Bu uç noktaların tümü meydan okuma kodunu kullanır ve kimliği doğrulanmış bir API isteği gerektirir.

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

::: warning Entegrasyon erişimi
API kimlik bilgileri, desteklenen kimlik doğrulama akışları ve hız sınırları DistantRace desteğiyle kararlaştırılır. Sonuç veya analiz uç noktasından gelen `404` yanıtını, kaynağın isteği yapan mevcut kullanıcı için kullanılamadığı şeklinde değerlendirin; gizlilik ayarları kaynağı gizlediğinde de aynı yanıt kullanılır.
:::

## Uç nokta sırası

| Uç nokta | Kullanım |
|----------|-----|
| `GET result-settings/` | Sonuç sütunlarını, sıralamayı, toplamları, bölümleri, mesafeleri ve kullanılabilen isteğe bağlı görünümleri keşfedin |
| `GET heatmap/` | `show_heatmap` etkin olduğunda toplu antrenman yoğunluğu hücrelerini yükleyin |
| `GET results/{challenger_id}/detailed/` | Bir katılımcının sonucunu, toplu istatistikleri, karşılaştırmaları ve aktivite zaman çizelgesini yükleyin |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Kabul edilen bir aktivitenin bölümlerini, grafiklerini ve izin verilen sensör analizlerini yükleyin |

`result-settings/` ile başlayın. Her meydan okumanın aynı sonuç biçimine sahip olduğunu varsaymak yerine, hangi denetimlerin ve ekranların gösterileceğine karar vermek için buradaki bayrakları ve sütun açıklamalarını kullanın.

`challenger_id` değerlerini meydan okumanın sayfalanmış `results/` liderlik tablosundan alın. Aktivite kimlikleri, ayrıntılı yanıttaki iç içe `activities.results` listesinde bulunur.

## Sonuç ayarları

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

Yanıt, meydan okumanın mevcut sonuç sunumunu açıklar:

- `primary_column` ve `ordered_by`, sıralama ölçütünü ve varsayılan düzeni belirtir.
- `columns` ve `team_columns` sıralı görüntüleme açıklamalarıdır; anahtarları katılımcı ve takım liderlik tablosu satırlarındaki alanlarla eşleşir.
- `totals`, `progress`, `sections`, `distances` ve `participant_data`, meydan okuma genelinde isteğe bağlı bağlam sağlar.
- `show_map` ve `show_heatmap`, istemciye hangi harita görünümlerinin sunulacağını bildirir. `show_analytics`, isteği yapan kullanıcının başka bir katılımcının fizyolojik aktivite verilerini görüp göremeyeceğini belirtir; kullanıcının kendi erişilebilir analizlerini kısıtlamaz.
- `results_limited`, sınırsız sonuçlar için `null` değerindedir. Bir sayı, isteği yapan kullanıcının yalnızca bu kadar üst sırayı görebileceği ve sonuç filtreleme, sıralama ve sayfalama denetimlerinin gizlenmesi gerektiği anlamına gelir.

Bu değerler isteği yapan kullanıcıya göre uyarlanır. Örneğin aynı meydan okuma, bir katılımcıya sınırsız ayarlar; oturum açmış ancak katılımcı olmayan bir kullanıcıya ise sınırlı ayarlar döndürebilir.

## Antrenman ısı haritası

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

Isı haritası, kabul edilen GPS aktivitelerini yaklaşık 150 metrelik ızgara hücrelerinde toplar. Her hücre `[longitude, latitude, weight]` biçimindedir; ağırlık, o hücreden geçen farklı aktivitelerin sayısıdır. Bir aktivite her hücreye en fazla bir kez katkıda bulunur ve kaynak uygulamada özel olarak işaretlenen antrenmanlar dahil edilmez.

Isı haritaları gerektiğinde oluşturulur. Kayıtlı bir ısı haritası yoksa ilk istek arka planda oluşturmayı başlatır ve şu yanıtı döndürür:

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

Birkaç saniye sonra verileri yeniden isteyin. Hazır yanıt `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` ve `cells` alanlarını içerir. Eski bir ısı haritası arka planda yenilenirken kayıtlı veriler sunulmaya devam edebilir.

Ağırlıklı yoğunluk katmanını normalleştirmek için `max_weight` değerini kullanın. `truncated` `true` ise yanıt, oluşturulan tüm hücreler yerine en yüksek ağırlığa sahip hücreleri içerir.

Organizatör `show_heatmap` özelliğini etkinleştirmediyse, sonuçların gizlendiği bir dönem etkinse veya herkese açık sonuçlar sınırlıyken isteği yapan kullanıcı katılımcı değilse uç nokta `404` döndürür.

## Ayrıntılı katılımcı sonucu

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

Yanıt şunları birleştirir:

- Katılımcının liderlik tablosu satırı, seçilen mesafe, sıralama ve `result_rank_total`.
- Mesafe, süre, tempo veya hız, enerji, adımlar, aktivite sayısı, aktif günler, en uzun seri ve mevcut olduğunda ortalama kalp atış hızı gibi `statistics` verileri.
- Satırın kimliği doğrulanmış katılımcıya ait olup olmadığını belirten `is_own_result`.
- Yalnızca bir katılımcı kendi sonucuna baktığında kullanılabilen `head_to_head`. Sıralama ve yüzdelik dilim, sıralama ölçütü, yakındaki rakiplere ve lidere olan farklar, tüm katılımcıların ortalaması ve podyum satırlarını içerir.
- Sonuca dahil edilen, kabul edilmiş ve görünür aktivitelerden oluşan iç içe sayfalanmış `activities` listesi. Her satır temel antrenman meta verilerini, ortalama tempoyu, mevcut olduğunda rota şeklini ve `has_analytics` alanını içerir.

Sabit mesafeli bir sonuçta aktivite listesi, seçilen mesafenin tamamlandığı aktivitede sona erer. Daha sonraki aktiviteler bu sonuca katkıda bulunmadıkları için görüntülenmez.

### İç içe aktivite sayfalaması

Aktivite listesinde standart `count`, `next`, `previous` ve `results` alanları bulunur; ancak üst düzey sayfalamayla çakışmaması için özel sorgu parametreleri kullanılır:

| Parametre | Anlamı |
|-----------|---------|
| `activities_page` | 1'den başlayan sayfa numarası |
| `activities_per_page` | Sayfa başına öğe sayısı; varsayılan 25'tir ve API üst sınırına tabidir |

### Konumdan bağımsız rota şekilleri

Aktivite zaman çizelgesindeki rotalar coğrafi koordinatlar değildir. Sunucu her GPS izini sabit bir `158 × 108` SVG koordinat alanına taşır ve ölçeklendirir; yalnızca şunları döndürür:

- `path` — SVG yol verileri
- `start` ve `end` — normalleştirilmiş koordinat alanındaki noktalar
- `point_count` — döndürülen şekildeki nokta sayısı

Mutlak enlem, boylam, sınırlar ve merkez dahil edilmez. Başka bir konuma taşınan aynı rota aynı şekli üretir; bu nedenle küçük resim için uygundur, ancak coğrafi bir haritada çizilemez.

## Aktivite başına analiz

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

Aktivite kabul edilmiş ve görünür olmalı, ayrıca tam olarak bu katılımcı sonucuna bağlı olmalıdır. Yanıt temel mesafe, süre, tempo ve hız bilgileriyle birlikte kayıtlı veri akışlarından türetilebilen analizleri içerir:

| Blok | İçerik |
|-------|----------|
| `route` | Aktivite zaman çizelgesinde kullanılan konumdan bağımsız rota şeklinin aynısı |
| `km_splits` | Tam kilometre bölümleri ve isteğe bağlı son kısmi bölüm; en hızlı ve en yavaş bölüm işaretleri dahil |
| `elevation` | Seyreltilmiş yükseklik profili, tırmanış, iniş, minimum ve maksimum |
| `heart_rate` ve `hr_zones` | Seyreltilmiş kalp atış hızı serisi, ortalama, maksimum, referans maksimum ve beş bölgedeki süre |
| `cadence` | Seyreltilmiş kadans serisi ve ortalama |
| `effort_score` | Kalp atış hızından türetilen efor tahmini |

Sağlayıcılar ve cihazlar farklı akışlar sunduğundan her blok diğerlerinden bağımsız olarak `null` olabilir. `has_streams`, kullanılabilir akış analizlerinin bulunup bulunmadığını bildirir. `x_kind`, grafiklerin x değerlerinin kümülatif mesafeyi mi yoksa geçen süreyi mi temsil ettiğini belirtir.

Düşük hassasiyetli bloklara — rota şekli, bölümler, tempo ve yükseklik — sonuca erişebilen her kullanıcı ulaşabilir. Fizyolojik bloklar — kalp atış hızı, bölgeler, kadans ve efor — isteği yapan kullanıcının kendi erişilebilir sonucu için her zaman kullanılabilir. Başka bir katılımcının aktivitesinde ise yalnızca organizatör `show_analytics` özelliğini etkinleştirmişse ve isteği yapan kullanıcı sonuç görünürlük kurallarını karşılıyorsa döndürülür. Aksi durumda bu bloklar `null`, `physio_restricted` ise `true` olur.

## Görünürlük ve gizlilik kuralları

| Ayar veya durum | Etki |
|------------------|--------|
| `show_heatmap` kapalı | Isı haritası `404` döndürür; `result-settings`, `show_heatmap: false` bildirir |
| `show_analytics` kapalı | Diğer katılımcıların fizyolojik aktivite blokları kaldırılır; kullanıcının kendi erişilebilir analizleri etkilenmez |
| Sonuçların gizlendiği dönem etkin | Katılımcı sonuç ayrıntıları gizlenir; ısı haritası `404` döndürür; `show_heatmap` ve `show_analytics` false olur |
| `hide_results_public` açık | Oturum açmış ancak katılımcı olmayan kullanıcılar yapılandırılmış üst sonuç sayısıyla sınırlandırılır, ısı haritasını yükleyemez ve diğer katılımcıların fizyolojik analizlerini göremez |
| Antrenman kabul edilmemiş veya görünür değil | Zaman çizelgesine dahil edilmez ve analiz uç noktası üzerinden açılamaz |

Meydan okuma katılımcıları, sonuçların gizlendiği bir dönem dışında tüm sonuçlara erişmeye devam eder. Organizasyon personelinin erişimi katılımcı erişiminden farklı olabilir; ancak istemciler yine de `result-settings/` tarafından döndürülen, isteği yapan kullanıcıya özel değerleri izlemelidir.

## İlgili

- [Genel API genel bakış](public-api-overview.md)
- [Beyaz Etiket ve Kurumsal Kurulum](../running-events/whitelabel-and-enterprise-setup.md)