# Football API for LLMs 🏈

A comprehensive football data API with both JSON and markdown endpoints for LLM consumption.

## 🚀 Quick Start
- **JSON API:** `/api/*` - Standard JSON responses
- **LLM API:** `/llm/*` - Markdown formatted responses for LLMs
- **Health Check:** `/api/health` - API status

## 📊 Available Endpoints

### 🏆 Teams
**List Teams:**
- `GET /api/teams` - JSON response
- `GET /llm/teams` - Markdown response
- `GET /api/teams?country=Portugal&league=94&season=2025` - Filtered teams
- `GET /llm/teams?country=Portugal&league=94&season=2025` - Filtered teams

**Individual Team:**
- `GET /api/teams/217` - SC Braga details (JSON)
- `GET /llm/teams/217` - SC Braga details (Markdown)

**Team Related:**
- `GET /api/teams/seasons` - Available seasons
- `GET /api/teams/countries` - Available countries
- `GET /api/teams/statistics` - Team statistics
- `GET /api/teams/217/leagues` - Team's leagues

### 🏅 Leagues
**List Leagues:**
- `GET /api/leagues` - All leagues (JSON)
- `GET /llm/leagues` - All leagues (Markdown)
- `GET /api/leagues?country=Portugal` - Portuguese leagues
- `GET /llm/leagues?country=Portugal` - Portuguese leagues

**Individual League:**
- `GET /api/leagues/94` - Primeira Liga details (JSON)
- `GET /llm/leagues/94` - Primeira Liga details (Markdown)

**League Related:**
- `GET /api/leagues/countries` - Available countries
- `GET /api/leagues/seasons` - Available seasons

### ⚽ Fixtures
**List Fixtures:**
- `GET /api/fixtures` - All fixtures (JSON)
- `GET /llm/fixtures` - All fixtures (Markdown)
- `GET /api/fixtures?team=217&season=2025` - Team fixtures
- `GET /llm/fixtures?team=217&season=2025` - Team fixtures
- `GET /api/fixtures?league=94&season=2025` - League fixtures
- `GET /llm/fixtures?league=94&season=2025` - League fixtures

**Individual Fixture:**
- `GET /api/fixtures/1063478` - Fixture details (JSON)
- `GET /llm/fixtures/1063478` - Fixture details (Markdown)

**Fixture Related:**
- `GET /api/fixtures/headtohead?h2h=217-211` - Head-to-head stats
- `GET /llm/fixtures/headtohead?h2h=217-211` - Head-to-head stats
- `GET /api/fixtures/rounds?league=94&season=2025` - League rounds
- `GET /api/fixtures/events?fixture=1063478` - Match events
- `GET /llm/fixtures/events?fixture=1063478` - Match events
- `GET /api/fixtures/lineups?fixture=1063478` - Match lineups
- `GET /llm/fixtures/lineups?fixture=1063478` - Match lineups
- `GET /api/fixtures/players?fixture=1063478` - Match players
- `GET /llm/fixtures/players?fixture=1063478` - Match players
- `GET /api/fixtures/statistics?fixture=1063478` - Match statistics
- `GET /llm/fixtures/statistics?fixture=1063478` - Match statistics

### 👥 Players
**List Players:**
- `GET /api/players` - All players (JSON)
- `GET /llm/players` - All players (Markdown)
- `GET /api/players?team=217&season=2025` - Team players
- `GET /llm/players?team=217&season=2025` - Team players
- `GET /api/players?league=94&season=2025` - League players
- `GET /llm/players?league=94&season=2025` - League players

**Individual Player:**
- `GET /api/players/1234` - Player details (JSON)
- `GET /llm/players/1234` - Player details (Markdown)

**Player Related:**
- `GET /api/players/seasons` - Available seasons
- `GET /api/players/countries` - Available countries
- `GET /api/players/search?search=ronaldo` - Search players
- `GET /llm/players/search?search=ronaldo` - Search players

### 📊 Standings
**League Standings:**
- `GET /api/standings?league=94&season=2025` - League table (JSON)
- `GET /llm/standings?league=94&season=2025` - League table (Markdown)

### 🏆 Top Performers
**Top Scorers:**
- `GET /api/topscorers?league=94&season=2025` - Top scorers (JSON)
- `GET /llm/topscorers?league=94&season=2025` - Top scorers (Markdown)

**Top Assists:**
- `GET /api/topassists?league=94&season=2025` - Top assists (JSON)
- `GET /llm/topassists?league=94&season=2025` - Top assists (Markdown)

**Top Cards:**
- `GET /api/topyellowcards?league=94&season=2025` - Most yellow cards (JSON)
- `GET /llm/topyellowcards?league=94&season=2025` - Most yellow cards (Markdown)
- `GET /api/topredcards?league=94&season=2025` - Most red cards (JSON)
- `GET /llm/topredcards?league=94&season=2025` - Most red cards (Markdown)

### 🏟️ Venues
**List Venues:**
- `GET /api/venues` - All venues (JSON)
- `GET /llm/venues` - All venues (Markdown)
- `GET /api/venues?country=Portugal` - Portuguese venues
- `GET /llm/venues?country=Portugal` - Portuguese venues

**Individual Venue:**
- `GET /api/venues/1234` - Venue details (JSON)
- `GET /llm/venues/1234` - Venue details (Markdown)

**Venue Related:**
- `GET /api/venues/countries` - Available countries
- `GET /api/venues/search?search=estadio` - Search venues
- `GET /llm/venues/search?search=estadio` - Search venues

### 👨‍💼 Coaches
**List Coaches:**
- `GET /api/coaches` - All coaches (JSON)
- `GET /llm/coaches` - All coaches (Markdown)
- `GET /api/coaches?team=217` - Team coaches
- `GET /llm/coaches?team=217` - Team coaches

**Individual Coach:**
- `GET /api/coaches/1234` - Coach details (JSON)
- `GET /llm/coaches/1234` - Coach details (Markdown)

**Coach Related:**
- `GET /api/coaches/countries` - Available countries
- `GET /api/coaches/search?search=artur` - Search coaches
- `GET /llm/coaches/search?search=artur` - Search coaches

### 📈 Other Data
**Transfers:**
- `GET /api/transfers?team=217&season=2025` - Team transfers (JSON)
- `GET /llm/transfers?team=217&season=2025` - Team transfers (Markdown)

**Trophies:**
- `GET /api/trophies?team=217` - Team trophies (JSON)
- `GET /llm/trophies?team=217` - Team trophies (Markdown)

**Sidelined Players:**
- `GET /api/sidelined?team=217` - Injured/suspended players (JSON)
- `GET /llm/sidelined?team=217` - Injured/suspended players (Markdown)

**Odds & Predictions:**
- `GET /api/odds?fixture=1063478` - Match odds (JSON)
- `GET /llm/odds?fixture=1063478` - Match odds (Markdown)
- `GET /api/predictions?fixture=1063478` - Match predictions (JSON)
- `GET /llm/predictions?fixture=1063478` - Match predictions (Markdown)

**Betting Data:**
- `GET /api/bookmakers` - Available bookmakers (JSON)
- `GET /llm/bookmakers` - Available bookmakers (Markdown)
- `GET /api/betting?fixture=1063478` - Betting data (JSON)
- `GET /llm/betting?fixture=1063478` - Betting data (Markdown)

## 🔗 Common Parameters
- `league` - League ID (e.g., 94 for Primeira Liga)
- `team` - Team ID (e.g., 217 for SC Braga)
- `season` - Season year (e.g., 2025)
- `country` - Country name (e.g., Portugal)
- `fixture` - Fixture ID
- `search` - Search term for search endpoints

## 🎯 Example Usage
```bash
# Get SC Braga fixtures for 2025 season
curl "http://localhost:3003/llm/fixtures?team=217&season=2025"

# Get Primeira Liga standings
curl "http://localhost:3003/llm/standings?league=94&season=2025"

# Get team details with related data links
curl "http://localhost:3003/llm/teams/217"

# Search for players
curl "http://localhost:3003/llm/players/search?search=ronaldo"
```

## 🚀 Features
- **Caching:** All requests are cached for performance
- **Markdown Links:** LLM endpoints include clickable links between related data
- **Error Handling:** Comprehensive error responses
- **Type Safety:** Full TypeScript support
- **Documentation:** Self-documenting API with examples

## 🔧 Development
- **Health Check:** `GET /api/health`
- **Cache Status:** Check `cache/` directory for cached responses
- **Logs:** Server logs show request/response details

---
*Powered by API-Football • Cached for optimal performance*