---
title: API de resultados de desafios
description: Crie classificações, mapas de calor, detalhes de participantes e análises de atividades para desafios
order: 6
source_hash: 3be9a0ef7fd2
---

# API de resultados de desafios

Portais de marca branca e outras integrações compatíveis podem criar uma experiência de resultados de desafios com os endpoints abaixo. Todos usam o código do desafio e exigem uma solicitação de API autenticada.

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

::: warning Acesso à integração
As credenciais de API, os fluxos de autenticação compatíveis e os limites de requisição são combinados com o suporte do DistantRace. Considere um `404` de um endpoint de resultados ou análises como indisponível para o solicitante atual; a mesma resposta é usada quando as configurações de privacidade ocultam o recurso.
:::

## Sequência de endpoints

| Endpoint | Uso |
|----------|-----|
| `GET result-settings/` | Descubra as colunas de resultados, a ordenação, os totais, as seções, as distâncias e as visualizações opcionais disponíveis |
| `GET heatmap/` | Carregue células agregadas de densidade dos treinos quando `show_heatmap` estiver habilitado |
| `GET results/{challenger_id}/detailed/` | Carregue o resultado de um participante, as estatísticas agregadas, as comparações e a linha do tempo das atividades |
| `GET results/{challenger_id}/activities/{activity_id}/analytics/` | Carregue parciais, gráficos e análises permitidas dos sensores de uma atividade aceita |

Comece com `result-settings/`. Use suas flags e descrições de colunas para decidir quais controles e telas devem ser renderizados, em vez de pressupor que todos os desafios tenham o mesmo formato de resultados.

Obtenha os valores de `challenger_id` na classificação paginada `results/` do desafio. Os IDs das atividades vêm da lista aninhada `activities.results` na resposta detalhada.

## Configurações dos resultados

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

A resposta descreve a apresentação atual dos resultados do desafio:

- `primary_column` e `ordered_by` identificam a métrica da classificação e a ordem padrão.
- `columns` e `team_columns` são descritores ordenados de renderização; suas chaves correspondem aos campos das linhas de classificação dos participantes e das equipes.
- `totals`, `progress`, `sections`, `distances` e `participant_data` fornecem contexto opcional para todo o desafio.
- `show_map` e `show_heatmap` informam ao cliente quais visualizações de mapa oferecer. `show_analytics` indica se o solicitante pode ver os dados fisiológicos das atividades de outro participante; não restringe as análises acessíveis do próprio solicitante.
- `results_limited` é `null` quando não há restrições. Um número significa que o solicitante só pode ver essa quantidade de linhas no topo e que os controles de filtragem, ordenação e paginação dos resultados devem ser ocultados.

Esses valores consideram o solicitante. Por exemplo, o mesmo desafio pode retornar configurações sem restrições para um participante e configurações limitadas para um usuário conectado que não participa.

## Mapa de calor dos treinos

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

O mapa de calor agrega as atividades GPS aceitas em células de uma grade de aproximadamente 150 metros. Cada célula é `[longitude, latitude, weight]`, em que o peso corresponde ao número de atividades distintas que passaram por ela. Uma atividade contribui no máximo uma vez para cada célula, e treinos marcados como privados no aplicativo de origem são excluídos.

Os mapas de calor são gerados sob demanda. Quando não há um mapa armazenado, a primeira solicitação inicia a geração em segundo plano e retorna:

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

Consulte novamente após alguns segundos. Uma resposta pronta contém `generated_at`, `cell_size`, `activity_count`, `max_weight`, `truncated` e `cells`. Os dados armazenados podem continuar sendo servidos enquanto um mapa desatualizado é atualizado em segundo plano.

Use `max_weight` para normalizar uma camada de densidade ponderada. Se `truncated` for `true`, a resposta conterá as células com maior peso, em vez de todas as células geradas.

O endpoint retorna `404` quando o organizador não habilitou `show_heatmap`, durante uma janela de resultados ocultos ou quando os resultados públicos estão restritos e o solicitante não é participante.

## Resultado detalhado do participante

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

A resposta combina:

- A linha de classificação do participante, a distância escolhida, a colocação e `result_rank_total`.
- `statistics`, como distância, duração, ritmo ou velocidade, energia, passos, número de atividades, dias ativos, maior sequência e frequência cardíaca média, quando disponível.
- `is_own_result`, que identifica se a linha pertence ao participante autenticado.
- `head_to_head`, disponível apenas quando um participante visualiza seu próprio resultado. Inclui colocação e percentil, métrica da classificação, diferenças para concorrentes próximos e para o líder, média do grupo e linhas do pódio.
- `activities`, uma lista aninhada e paginada de atividades aceitas e visíveis creditadas ao resultado. Cada linha inclui metadados básicos do treino, ritmo médio, uma forma de rota quando disponível e `has_analytics`.

Para um resultado de distância fixa, a lista de atividades termina na atividade que concluiu a distância selecionada. As atividades posteriores não aparecem porque não contribuíram para esse resultado.

### Paginação aninhada das atividades

A lista de atividades tem os campos habituais `count`, `next`, `previous` e `results`, mas usa parâmetros de consulta próprios para não entrar em conflito com a paginação de nível superior:

| Parâmetro | Significado |
|-----------|-------------|
| `activities_page` | Número da página, começando em 1 |
| `activities_per_page` | Itens por página; padrão 25 e sujeito ao máximo da API |

### Formas de rota sem localização

As rotas na linha do tempo das atividades não são coordenadas geográficas. O servidor desloca e redimensiona cada trajeto GPS para um espaço fixo de coordenadas SVG de `158 × 108` e retorna apenas:

- `path` — dados do caminho SVG
- `start` e `end` — pontos no espaço de coordenadas normalizado
- `point_count` — número de pontos na forma retornada

Latitude e longitude absolutas, limites e centro não são incluídos. A mesma rota deslocada para outro local gera a mesma forma; portanto, ela é adequada para uma miniatura, mas não pode ser traçada em um mapa geográfico.

## Análises por atividade

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

A atividade deve estar aceita, visível e associada exatamente ao resultado desse participante. A resposta contém distância, duração, ritmo e velocidade básicos, além de todas as análises que podem ser derivadas dos fluxos armazenados:

| Bloco | Conteúdo |
|-------|----------|
| `route` | A mesma forma de rota sem localização usada na linha do tempo das atividades |
| `km_splits` | Parciais de quilômetros completos mais uma parcial final opcional, incluindo marcadores da mais rápida e da mais lenta |
| `elevation` | Perfil de elevação com amostragem reduzida, subida, descida, mínimo e máximo |
| `heart_rate` e `hr_zones` | Série de frequência cardíaca com amostragem reduzida, média, máxima, máxima de referência e tempo em cinco zonas |
| `cadence` | Série de cadência com amostragem reduzida e média |
| `effort_score` | Estimativa de esforço derivada da frequência cardíaca |

Cada bloco pode ser `null` independentemente dos demais, pois provedores e dispositivos fornecem fluxos diferentes. `has_streams` indica se há análises utilizáveis de fluxos. `x_kind` identifica se os valores x do gráfico representam a distância acumulada ou o tempo decorrido.

Os blocos de baixa sensibilidade — forma de rota, parciais, ritmo e elevação — estão disponíveis para qualquer solicitante que possa acessar o resultado. Os blocos fisiológicos — frequência cardíaca, zonas, cadência e esforço — estão sempre disponíveis para o resultado acessível do próprio solicitante. Para a atividade de outro participante, eles só são retornados quando o organizador habilitou `show_analytics` e o solicitante cumpre as regras de visibilidade dos resultados. Caso contrário, esses blocos são `null` e `physio_restricted` é `true`.

## Regras de visibilidade e privacidade

| Configuração ou estado | Efeito |
|------------------------|--------|
| `show_heatmap` desativado | O mapa de calor retorna `404`; `result-settings` informa `show_heatmap: false` |
| `show_analytics` desativado | Os blocos fisiológicos das atividades de outros participantes são removidos; as análises acessíveis do próprio usuário não são afetadas |
| Janela de resultados ocultos ativa | Os detalhes dos resultados dos participantes ficam ocultos; o mapa de calor retorna `404`; `show_heatmap` e `show_analytics` são false |
| `hide_results_public` ativado | Usuários conectados que não participam ficam limitados ao número configurado de melhores resultados, não podem carregar o mapa de calor nem ver análises fisiológicas de outros participantes |
| Treino não aceito ou não visível | Ele é omitido da linha do tempo e não pode ser aberto pelo endpoint de análises |

Os participantes do desafio mantêm acesso aos resultados completos fora de uma janela de resultados ocultos. O acesso da equipe da organização pode diferir do acesso dos participantes, mas os clientes ainda devem seguir os valores específicos do solicitante retornados por `result-settings/`.

## Relacionados

- [Visão geral da API pública](public-api-overview.md)
- [Configuração de marca branca e empresarial](../running-events/whitelabel-and-enterprise-setup.md)