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}/

Secuencia de endpoints #

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:

{"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:

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:

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 #

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
• Configuración de marca blanca y empresarial