API dei risultati delle sfide

I portali whitelabel e le altre integrazioni supportate possono creare un'esperienza dedicata ai risultati delle sfide con gli endpoint seguenti. Tutti usano il codice della sfida e richiedono una richiesta API autenticata.

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

Sequenza degli endpoint #

Inizia da result-settings/. Usa i flag e i descrittori delle colonne per decidere quali controlli e schermate visualizzare, senza presumere che ogni sfida abbia lo stesso formato dei risultati.

Ottieni i valori challenger_id dalla classifica results/ paginata della sfida. Gli ID delle attività provengono dall'elenco annidato activities.results nella risposta dettagliata.

Impostazioni dei risultati #

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

La risposta descrive la presentazione attuale dei risultati della sfida:

• primary_column e ordered_by identificano la metrica della classifica e l'ordinamento predefinito.
• columns e team_columns sono descrittori di visualizzazione ordinati; le loro chiavi corrispondono ai campi nelle righe delle classifiche dei partecipanti e delle squadre.
• totals, progress, sections, distances e participant_data forniscono un contesto facoltativo per l'intera sfida.
• show_map e show_heatmap indicano al client quali viste mappa offrire. show_analytics indica se il chiamante può vedere i dati fisiologici delle attività di un altro partecipante; non limita le analisi raggiungibili del chiamante stesso.
• results_limited è null per risultati senza restrizioni. Un numero indica che il chiamante può vedere solo quel numero di righe in cima e che i controlli di filtro, ordinamento e paginazione dei risultati devono essere nascosti.

Questi valori dipendono dal chiamante. Ad esempio, la stessa sfida può restituire impostazioni senza restrizioni a un partecipante e impostazioni limitate a un utente autenticato che non partecipa.

Mappa di calore degli allenamenti #

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

La mappa di calore aggrega le attività GPS accettate in celle di una griglia di circa 150 metri. Ogni cella è [longitude, latitude, weight], dove il peso è il numero di attività distinte che l'hanno attraversata. Ogni attività contribuisce al massimo una volta per cella e gli allenamenti contrassegnati come privati nell'app di origine sono esclusi.

Le mappe di calore vengono generate su richiesta. Se non esiste una mappa memorizzata, la prima richiesta avvia la generazione in background e restituisce:

{"status": "pending"}

Ripeti la richiesta dopo alcuni secondi. Una risposta pronta contiene generated_at, cell_size, activity_count, max_weight, truncated e cells. I dati memorizzati possono continuare a essere serviti mentre una mappa obsoleta viene aggiornata in background.

Usa max_weight per normalizzare un livello di densità ponderato. Se truncated è true, la risposta contiene le celle con il peso maggiore anziché tutte quelle generate.

L'endpoint restituisce 404 quando l'organizzatore non ha abilitato show_heatmap, durante una finestra di risultati nascosti o quando i risultati pubblici sono limitati e il chiamante non è un partecipante.

Risultato dettagliato del partecipante #

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

La risposta combina:

• La riga della classifica del partecipante, la distanza scelta, la posizione e result_rank_total.
• statistics, come distanza, durata, ritmo o velocità, energia, passi, numero di attività, giorni attivi, serie più lunga e frequenza cardiaca media, se disponibile.
• is_own_result, che indica se la riga appartiene al partecipante autenticato.
• head_to_head, disponibile solo quando un partecipante visualizza il proprio risultato. Include posizione e percentile, metrica della classifica, distacchi dai concorrenti vicini e dal leader, media del gruppo e righe del podio.
• activities, un elenco annidato e paginato delle attività accettate e visibili accreditate al risultato. Ogni riga include metadati di base dell'allenamento, ritmo medio, forma del percorso quando disponibile e has_analytics.

Per un risultato a distanza fissa, l'elenco delle attività si ferma all'attività che ha completato la distanza selezionata. Le attività successive non appaiono perché non hanno contribuito a quel risultato.

Paginazione annidata delle attività #

L'elenco delle attività contiene i consueti campi count, next, previous e results, ma usa parametri di query dedicati per non entrare in conflitto con la paginazione di primo livello:

Forme dei percorsi senza posizione #

I percorsi nella sequenza temporale delle attività non sono coordinate geografiche. Il server trasla e ridimensiona ogni traccia GPS in uno spazio di coordinate SVG fisso di 158 × 108 e restituisce solo:

• path — dati del tracciato SVG
• start e end — punti nello spazio di coordinate normalizzato
• point_count — numero di punti nella forma restituita

Latitudine e longitudine assolute, limiti e centro non sono inclusi. Lo stesso percorso traslato in un'altra posizione produce la stessa forma: è quindi adatto a una miniatura, ma non può essere tracciato su una mappa geografica.

Analisi per attività #

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

L'attività deve essere accettata, visibile e collegata esattamente al risultato del partecipante indicato. La risposta contiene distanza, durata, ritmo e velocità di base, oltre a tutte le analisi derivabili dai flussi memorizzati:

Ogni blocco può essere null indipendentemente dagli altri, perché fornitori e dispositivi forniscono flussi diversi. has_streams indica se sono disponibili analisi utilizzabili dei flussi. x_kind indica se i valori x del grafico rappresentano la distanza cumulativa o il tempo trascorso.

I blocchi a bassa sensibilità — forma del percorso, parziali, ritmo e altitudine — sono disponibili a qualsiasi chiamante che possa raggiungere il risultato. I blocchi fisiologici — frequenza cardiaca, zone, cadenza e sforzo — sono sempre disponibili per il risultato raggiungibile del chiamante stesso. Per l'attività di un altro partecipante vengono restituiti solo quando l'organizzatore ha abilitato show_analytics e il chiamante rispetta le regole di visibilità dei risultati. In caso contrario, questi blocchi sono null e physio_restricted è true.

Regole di visibilità e privacy #

I partecipanti alla sfida mantengono l'accesso a tutti i risultati al di fuori di una finestra di risultati nascosti. L'accesso del personale dell'organizzazione può differire da quello dei partecipanti, ma i client devono comunque seguire i valori specifici per il chiamante restituiti da result-settings/.

Correlati #

• Panoramica API pubblica
• Configurazione whitelabel e aziendale