API Documentation

Proxy de dados desportivos para basquetebol português. Dados da FPB e TugaBasket.

Overview Auth Jogos Classificações Atletas Clubes ELO TugaBasket WebSocket Métricas Self-Hosting

Overview

O Bounce e um proxy de dados desportivos que agrega informacao da FPB (www.fpb.pt) e do TugaBasket (resultados.tugabasket.com).

Base URL: http://localhost:3001 (local) ou https://api.example.com (producao)

Rate limit: 100 pedidos/minuto por IP

Cache: SQLite com TTL inteligente (jogos do dia: 2min, historico: 24h)

Formatos: JSON em todos os endpoints

Authentication & Rate Limits

A API e publica — nao requer autenticacao.

Rate limit bypass: Envia o header X-Dribly-Key com o valor da variavel de ambiente DRIBLY_KEY.

curl -H "X-Dribly-Key: ${DRIBLY_KEY}" http://localhost:3001/api/games?club=119&season=2025/2026

Jogos (Games)

GET/api/competitions

Lista todas as competições disponiveis na FPB.

curl "http://localhost:3001/api/competitions"

GET/api/games

Lista todos os jogos de um clube numa epoca, com scores.

Param	Tipo	Descricao	Exemplo
`club`	int	ID do clube	119 (Benfica)
`season`	string	Epoca	2025/2026

GET/api/games/today

Jogos agendados para hoje em todas as competições.

curl "http://localhost:3001/api/games/today"

GET/api/games/live

Jogos a decorrer neste momento.

curl "http://localhost:3001/api/games/live"

curl "http://localhost:3001/api/games?club=119&season=2025/2026"

GET/api/games/today

Jogos agendados para hoje em todas as competições.

curl "http://localhost:3001/api/games/today"

GET/api/games/live

Jogos a decorrer neste momento.

curl "http://localhost:3001/api/games/live"

GET/api/game/{id}

Detalhe completo de um jogo (equipas, scores, periodos, stats dos jogadores).

id string Internal game ID 413420

curl "http://localhost:3001/api/game/413420"

Classificações (Standings)

GET/api/standings/{id}

Classificacao de uma competicao da FPB.

id string ID da competicao 10902

curl "http://localhost:3001/api/standings/10902"

Atletas (Athletes)

GET/api/athlete/{id}

Perfil e estatisticas de um atleta.

id string ID do atleta 269564

curl "http://localhost:3001/api/athlete/269564"

Equipas & Clubes

GET/api/team/{id}

Detalhe de uma equipa com plantel e jogos.

id string Internal team ID equipa_57682

curl "http://localhost:3001/api/team/equipa_57682"

GET/api/club/{id}/teams

Lista todas as equipas de um clube.

id int ID do clube 127

curl "http://localhost:3001/api/club/127/teams"

ELO & Previsões

GET/api/elo

Ranking ELO de todas as equipas.

curl "http://localhost:3001/api/elo"

GET/api/predictions/{gameId}

Previsao de vencedor baseada em ELO.

curl "http://localhost:3001/api/predictions/413420"

GET/api/h2h

Historico de confrontos diretos entre duas equipas.

`team_a`	int	ID da equipa A	127
`team_b`	int	ID da equipa B	120

curl "http://localhost:3001/api/h2h?team_a=127&team_b=120"

TugaBasket

GET/api/tugabasket/standings

Classificacao via TugaBasket.

competitionId int ID da competicao 1

curl "http://localhost:3001/api/tugabasket/standings?competitionId=1"

GET/api/tugabasket/players

Estatisticas de jogadores via TugaBasket.

competitionId int ID da competicao 1

curl "http://localhost:3001/api/tugabasket/players?competitionId=1"

GET/api/tugabasket/teams

Estatisticas de equipas via TugaBasket.

competitionId int ID da competicao 1

curl "http://localhost:3001/api/tugabasket/teams?competitionId=1"

WebSocket

WS/ws/game/{id}

Recebe atualizacoes em tempo real durante um jogo.

id string Internal game ID 413420

Eventos:

score_update — score mudou
game_started — jogo comecou
game_finished — jogo terminou

{"type":"score_update","data":{"id":"413420","equipa_casa":"SL Benfica","resultado_casa":89,"resultado_fora":73,"equipa_fora":"FC Porto"}}

Métricas

GET/metrics

Métricas em formato Prometheus (texto).

curl "http://localhost:3001/metrics"

GET/api/metrics/history/simple

Historico de metricas (JSON) para o dashboard.

minutes int Janela de tempo 60

curl "http://localhost:3001/api/metrics/history/simple?minutes=60"

Self-Hosting

Docker:

docker run -d --name bounce --restart unless-stopped \
  -p 3001:3001 -v bounce-data:/data \
  ghcr.io/mefrraz/bounce:latest

Go binary:

git clone https://github.com/mefrraz/bounce.git
cd bounce
go build -o bounce ./cmd/server
BOUNCE_DATA_DIR=/data ./bounce

Variaveis de ambiente:

`BOUNCE_PORT`	Porta HTTP (default: 3001)	3001
`BOUNCE_DATA_DIR`	Diretoria para SQLite (default: /data)	/data
`DRIBLY_KEY`	Chave para bypass do rate limit	-