---
title: API de resultados de desafíos
description: Crea clasificaciones, mapas de calor, detalles de participantes y analíticas de actividades para desafíos
order: 6
source_hash: 3be9a0ef7fd2
slug: api-de-resultados-de-desafios
---

# API de resultados de desafíos

Los portales de marca blanca y otras integraciones compatibles pueden crear una experiencia de resultados de desafío con los siguientes endpoints. Todos utilizan el código del desafío y requieren una solicitud autenticada a la API.

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

::: warning Acceso para integraciones
Las credenciales de la API, los flujos de autenticación compatibles y los límites de solicitudes se acuerdan con el equipo de soporte de DistantRace. Interpreta una respuesta `404` de un endpoint de resultados o analíticas como que el recurso no está disponible para quien realiza la solicitud; se utiliza la misma respuesta cuando la configuración de privacidad oculta el recurso.
:::

## Secuencia de endpoints

| Endpoint | Uso |
|----------|-----|
| `GET result-settings/` | Consultar las columnas de resultados, el orden, los totales, las secciones, las distancias y las vistas opcionales disponibles |
| `GET heatmap/` | Cargar celdas agregadas de densidad de entrenamientos cuando `show_heatmap` está activado |
| `GET results/{challenger_id}/detailed/` | Cargar el resultado, las estadísticas agregadas, las comparaciones y la cronología de actividades de un participante |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Cargar parciales, gráficos y analíticas de sensores permitidas para una actividad aceptada |

Empieza por `result-settings/`. Utiliza sus indicadores y descriptores de columnas para decidir qué controles y pantallas mostrar, en lugar de suponer que todos los desafíos tienen el mismo formato de resultados.

Obtén los valores de `challenger_id` de la clasificación paginada `results/` del desafío. Los identificadores de actividad se encuentran en la lista anidada `activities.results` de la respuesta detallada.

## Configuración de resultados

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

La respuesta describe la presentación actual de los resultados del desafío:

- `primary_column` y `ordered_by` identifican la métrica de clasificación y el orden predeterminado.
- `columns` y `team_columns` son descriptores de presentación ordenados; sus claves corresponden a campos de las filas de clasificación de participantes y equipos.
- `totals`, `progress`, `sections`, `distances` y `participant_data` proporcionan contexto opcional para todo el desafío.
- `show_map` y `show_heatmap` indican al cliente qué vistas de mapa debe ofrecer. `show_analytics` indica si quien realiza la solicitud puede ver los datos fisiológicos de las actividades de otro participante; no restringe las analíticas propias a las que pueda acceder.
- `results_limited` es `null` cuando los resultados no están restringidos. Un número significa que solo se puede ver ese número de filas superiores, por lo que deben ocultarse los controles de filtrado, ordenación y paginación de resultados.

Estos valores dependen de quien realiza la solicitud. Por ejemplo, un mismo desafío puede devolver una configuración sin restricciones a un participante y una configuración limitada a una persona que ha iniciado sesión pero no participa.

## Mapa de calor de entrenamientos

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

El mapa de calor agrupa las actividades GPS aceptadas en celdas de aproximadamente 150 metros. Cada celda tiene el formato `[longitude, latitude, weight]`, donde el peso es el número de actividades distintas que pasaron por ella. Cada actividad contribuye como máximo una vez a cada celda, y se excluyen los entrenamientos marcados como privados en su aplicación de origen.

Los mapas de calor se generan cuando se necesitan. Si todavía no hay uno guardado, la primera solicitud inicia su generación en segundo plano y devuelve:

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

Vuelve a consultar el endpoint al cabo de unos segundos. Una respuesta lista contiene `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` y `cells`. Los datos guardados pueden servirse mientras un mapa de calor desactualizado se renueva en segundo plano.

Utiliza `max_weight` para normalizar una capa de densidad ponderada. Si `truncated` es `true`, la respuesta contiene las celdas con mayor peso en lugar de todas las celdas generadas.

El endpoint devuelve `404` cuando el organizador no ha activado `show_heatmap`, durante un período en el que los resultados están ocultos o cuando los resultados públicos están restringidos y quien realiza la solicitud no es participante.

## Resultado detallado de un participante

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

La respuesta combina:

- La fila de clasificación del participante, la distancia elegida, la posición y `result_rank_total`.
- `statistics`, como distancia, duración, ritmo o velocidad, energía, pasos, número de actividades, días activos, racha más larga y frecuencia cardíaca media cuando esté disponible.
- `is_own_result`, que indica si la fila pertenece al participante autenticado.
- `head_to_head`, disponible solo cuando un participante consulta su propio resultado. Incluye la posición y el percentil, la métrica de clasificación, las diferencias respecto a rivales cercanos y al líder, la media del grupo y las filas del podio.
- `activities`, una lista anidada y paginada de las actividades aceptadas y visibles que se han contabilizado en el resultado. Cada fila incluye metadatos básicos del entrenamiento, ritmo medio, una forma de la ruta cuando está disponible y `has_analytics`.

En un resultado de distancia fija, la lista de actividades termina en la actividad con la que se completó la distancia seleccionada. Las actividades posteriores no aparecen porque no contribuyeron a ese resultado.

### Paginación anidada de actividades

La lista de actividades tiene los campos habituales `count`, `next`, `previous` y `results`, pero utiliza parámetros de consulta específicos para no interferir con la paginación de nivel superior:

| Parámetro | Significado |
|-----------|-------------|
| `activities_page` | Número de página, empezando por 1 |
| `activities_per_page` | Elementos por página; 25 de forma predeterminada y sujeto al máximo de la API |

### Formas de ruta sin ubicación

Las rutas de la cronología de actividades no son coordenadas geográficas. El servidor traslada y escala cada trazado GPS a un espacio de coordenadas SVG fijo de `158 × 108` y devuelve únicamente:

- `path` — datos del trazado SVG
- `start` y `end` — puntos en el espacio de coordenadas normalizado
- `point_count` — número de puntos de la forma devuelta

No se incluyen la latitud, la longitud, los límites ni el centro absolutos. Una misma ruta trasladada a otro lugar produce la misma forma, por lo que sirve como miniatura, pero no puede representarse en un mapa geográfico.

## Analíticas por actividad

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

La actividad debe estar aceptada, ser visible y estar asociada exactamente al resultado de ese participante. La respuesta contiene la distancia, duración, ritmo y velocidad básicos, además de las analíticas que puedan obtenerse de los flujos guardados:

| Bloque | Contenido |
|--------|-----------|
| `route` | La misma forma de ruta sin ubicación utilizada en la cronología de actividades |
| `km_splits` | Parciales de kilómetros completos y un último parcial opcional, con marcas del más rápido y el más lento |
| `elevation` | Perfil con muestreo reducido, ascenso, descenso, mínimo y máximo |
| `heart_rate` y `hr_zones` | Serie de frecuencia cardíaca con muestreo reducido, media, máxima, máxima de referencia y tiempo en cinco zonas |
| `cadence` | Serie de cadencia con muestreo reducido y media |
| `effort_score` | Estimación del esfuerzo derivada de la frecuencia cardíaca |

Cada bloque puede ser nulo de forma independiente porque los proveedores y dispositivos facilitan flujos distintos. `has_streams` indica si existen analíticas de flujos utilizables. `x_kind` identifica si los valores x del gráfico representan la distancia acumulada o el tiempo transcurrido.

Los bloques de baja sensibilidad —forma de la ruta, parciales, ritmo y elevación— están disponibles para cualquiera que pueda acceder al resultado. Los bloques fisiológicos —frecuencia cardíaca, zonas, cadencia y esfuerzo— siempre están disponibles para el propio resultado accesible de quien realiza la solicitud. En la actividad de otro participante, solo se devuelven cuando el organizador ha activado `show_analytics` y quien realiza la solicitud cumple las reglas de visibilidad de resultados. De lo contrario, esos bloques son `null` y `physio_restricted` es `true`.

## Reglas de visibilidad y privacidad

| Configuración o estado | Efecto |
|------------------------|--------|
| `show_heatmap` desactivado | El mapa de calor devuelve `404`; `result-settings` indica `show_heatmap: false` |
| `show_analytics` desactivado | Se eliminan los bloques fisiológicos de las actividades de otros participantes; las analíticas propias accesibles no cambian |
| Período de resultados ocultos activo | Se ocultan los detalles de resultados de participantes; el mapa de calor devuelve `404`; `show_heatmap` y `show_analytics` son false |
| `hide_results_public` activado | Quienes han iniciado sesión pero no participan están limitados al número configurado de mejores resultados, no pueden cargar el mapa de calor ni ver las analíticas fisiológicas de otros participantes |
| Entrenamiento no aceptado o no visible | Se omite de la cronología y no puede abrirse mediante el endpoint de analíticas |

Los participantes del desafío conservan el acceso a los resultados completos fuera de los períodos en los que están ocultos. El acceso del personal de la organización puede diferir del de los participantes, pero los clientes deben seguir siempre los valores específicos para quien realiza la solicitud que devuelve `result-settings/`.

## Artículos relacionados

- [Descripción general de la API pública](public-api-overview.md)
- [Configuración de marca blanca y empresarial](../running-events/whitelabel-and-enterprise-setup.md)