Worldcup Predictor

SKILL.md

---
name: worldcup-predictor
description: World Cup 2026 match predictor. Uses BALLDONTLIE FIFA API + NetEase Sports data for real-time predictions (team strength, schedule, match analysis) via Elo rating + Poisson distribution model. Input: team name or match id. Output: prediction report (win/draw/loss %, score, odds, key factors).
---

# World Cup Predictor

A World Cup match prediction tool based on the **BALLDONTLIE FIFA World Cup API** and **NetEase Sports** schedule data.

## Features

- **48 teams** with Elo-based strength ratings
- **72 matches** (group stage A-L) with schedule and live results
- **Elo + Poisson** prediction model with home advantage
- **Theoretical odds** based on win probability (93% payout)
- **Team next-match** lookup and prediction

## Data Sources

**BALLDONTLIE FIFA World Cup API**
- Site: https://fifa.balldontlie.io
- API Base: `https://api.balldontlie.io/fifa/worldcup/v1`
- Auth: HTTP Header `Authorization: YOUR_API_KEY`
- OpenAPI spec: `https://www.balldontlie.io/openapi/fifa.yml`

**NetEase Sports Schedule**
- https://sports.163.com/caipiao/worldcup2026
- 72 matches (groups A-L), with completed scores

### API Key Setup

Store API key in configuration file:

```json
{
  "skills": {
    "worldcup-predictor": {
      "api_key": "your-api-key-here"
    }
  }
}
```

### Free Tier Endpoints

| Endpoint | Path | Free |
|----------|------|------|
| Teams | `/teams` | ✅ |
| Stadiums | `/stadiums` | ✅ |
| Standings | `/group_standings` | ❌ (ALL-STAR) |
| Matches | `/matches` | ❌ (ALL-STAR) |
| Odds | `/odds` | ❌ (GOAT) |

## Prediction Model

The model uses **Elo rating** + **Poisson distribution**:

1. **Base Elo**: Team strength (50-100) mapped to Elo 1300-2000
2. **Form bonus**: Points from completed group matches add Elo
3. **Home advantage**: +70 Elo (~3-5% win rate boost)
4. **Win probability**: Standard Elo formula `1 / (1 + 10^((elo_away - elo_home) / 400))`
5. **Draw probability**: Dynamic based on team closeness (15-35%)
6. **Score prediction**: Poisson-based expected goals

### Example Output

```
📊 Prediction Report
══════════════════════════════════════════════════
  🇦🇷 Argentina             vs 🇦🇹 Austria

  📈 Team Strength:
  🇦🇷 Argentina   [█████████░] 95
  🇦🇹 Austria      [███████░░░] 78

  📊 Win Probability:
  🇦🇷 Argentina:   69.0%
  🤝 Draw:         19.3%
  🇦🇹 Austria:     11.7%

  ⚽ Predicted:    3 - 2

  🔑 Key Analysis:
    • Argentina clearly stronger (gap 17 pts)
    • Low draw probability due to strength gap
```

## Usage

### Commands

```bash
# List all 48 teams with strength ratings
python3 predict.py teams

# View full match schedule
python3 predict.py schedule

# View upcoming matches only
python3 predict.py schedule --upcoming

# Predict a specific match
python3 predict.py match "Brazil" "Morocco"

# Find a team's next match and predict
python3 predict.py team "Argentina"

# Today's matches with predictions
python3 predict.py today

# Refresh schedule from built-in data
python3 predict.py update
```

### Examples

```bash
# Predict Argentina vs Austria
python3 predict.py match "Argentina" "Austria"

# Check Argentina's next match
python3 predict.py team "Argentina"

# See all upcoming matches
python3 predict.py schedule --upcoming

# See today's predictions
python3 predict.py today
```

## File Structure

```
worldcup-predictor/
├── SKILL.md
└── scripts/
    ├── predict.py       # Main prediction script
    └── schedule.json    # Cached match data (auto-generated)
```

## Configuration

The script reads the API key from the OpenClaw config at `~/.openclaw/openclaw.json`:

```json
{
  "skills": {
    "worldcup-predictor": {
      "api_key": "your-api-key-here"
    }
  }
}
```

## Notes

- **Free tier**: Team & stadium data only
- **ALL-STAR ($9.99/mo)**: Adds standings + match data (60 req/min)
- **GOAT ($39.99/mo)**: Full access including odds (600 req/min)
- **No API required for schedule**: Built-in 72 match data from NetEase Sports