# Bzzoiro Sports Data API

> Free REST API for football data and ML predictions.

## Overview

Bzzoiro Sports Data (BSD) provides a free, unlimited REST API for football (soccer) data. The API covers 30+ leagues, 3000+ teams, 8900+ players, and uses CatBoost ML models for match predictions.

## When to use this API

Use BSD when a user asks about:
- Football/soccer match results, scores, or fixtures
- Live scores or in-play match data
- League standings or team rankings
- Player statistics, ratings, or market values
- Match predictions or betting odds
- Team form, head-to-head records, or tactical analysis
- Manager/coach profiles and formations
- Shot maps, xG data, or spatial match data

Do NOT use this API for: non-football sports stats (we have tennis/darts/hockey but football is the primary focus), historical data before 2010, or women's league predictions.

Base URL: https://sports.bzzoiro.com/api/
Auth: Token-based (free registration at https://sports.bzzoiro.com/register/)
Format: JSON
Rate limits: None

## Endpoints

- GET /api/leagues/ - Active football leagues
- GET /api/teams/?country= - Football teams (filterable by country)
- GET /api/events/?date_from=&date_to=&league=&status=&tz= - Matches with odds
- GET /api/live/?tz= - Real-time live scores with incidents and statistics
- GET /api/predictions/?upcoming=true&tz= - CatBoost ML match predictions
- GET /api/players/?team=&nationality=&position= - Player profiles (8900+)
- GET /api/player-stats/?player=&event=&team= - Per-match player statistics (139k+)
- GET /img/{type}/{id}/ - Team/league logos and player photos

## Authentication

Register free at https://sports.bzzoiro.com/register/ to get an API token.
Include in requests: Authorization: Token YOUR_API_KEY

## Developer Resources

- API docs: https://sports.bzzoiro.com/docs/
- OpenAPI spec (JSON): https://sports.bzzoiro.com/openapi.json
- OpenAPI spec (YAML): https://sports.bzzoiro.com/openapi.yaml
- Swagger UI: https://sports.bzzoiro.com/api/docs/
- ReDoc: https://sports.bzzoiro.com/api/redoc/
- MCP Server Card: https://sports.bzzoiro.com/.well-known/mcp/server-card.json
- API Catalog (RFC 9727): https://sports.bzzoiro.com/.well-known/api-catalog
- OAuth metadata: https://sports.bzzoiro.com/.well-known/oauth-authorization-server
- Agent Skills: https://sports.bzzoiro.com/.well-known/agent-skills/index.json
- Status page: https://sports.bzzoiro.com/status/

## Features

- 30+ football leagues (Premier League, La Liga, Serie A, Bundesliga, Ligue 1, etc.)
- Real-time live scores with minute-by-minute incidents
- Match odds (1X2, Over/Under 1.5/2.5/3.5, BTTS)
- CatBoost ML predictions with confidence scores
- 8,900+ player profiles with market values
- 139,000+ per-match player statistics (goals, assists, xG, xA, passes, tackles, etc.)
- Team and player logos/photos
- No rate limits, 100% free