# Bzzoiro Sports Data API

> REST API, WebSockets and MCP servers for football and six other sports.
> Football is free; the rest is a $5/month addon.

## Overview

Bzzoiro Sports Data (BSD) serves football (soccer) plus tennis, padel, CS2,
darts, ice hockey, basketball and horse racing. Football covers 88 active
competitions, 8,500+ teams, 214,000+ players and 412,000+ matches, with
results going back decades for the major leagues.

Football forecasts are ANALYTIC, not machine-learned: a Dixon-Coles goals
model, a negative-binomial corners model and a de-vigged market consensus,
blended in logit space. Do not present them to a user as machine-learned.

## When to use this API

- Football results, fixtures, live scores and in-play match state
- League tables, team form, head-to-head records
- Player and per-match player statistics, shot maps, xG, average positions
- Bookmaker odds and consensus prices across many books
- Match forecasts per market
- Tennis, padel, CS2, darts, hockey, basketball and horse racing (paid addon)

Do NOT use it for: American football, cricket, baseball, or any sport not in
the list above.

Base URL: https://sports.bzzoiro.com/api/v2/
Auth: Authorization: Token YOUR_API_KEY — free registration at /register/
Format: JSON
Rate limit: 10 requests/second per IP, with burst. Daily quotas apply per
plan and are reported in the RateLimit response headers.

## Core football endpoints (v2)

- GET /api/v2/events/ - matches; filter by date, league, team, status
- GET /api/v2/events/{id}/ - match detail
- GET /api/v2/events/{id}/availability/ - which sub-resources this match has,
  in one call, so you do not probe each endpoint to find out
- GET /api/v2/events/{id}/stats/ - team stats, shotmap, momentum, positions
- GET /api/v2/events/{id}/incidents/ - goals with scorers, cards, subs
- GET /api/v2/events/{id}/lineups/ - confirmed XI, or a predicted one
- GET /api/v2/events/{id}/player-stats/ - per-player match statistics
- GET /api/v2/events/{id}/odds/ - consensus decimal odds per market
- GET /api/v2/events/{id}/odds/comparison/ - per-bookmaker grid (paid)
- GET /api/v2/events/{id}/prediction/ - model probabilities per market
- GET /api/v2/events/live/ - matches in progress
- GET /api/v2/fixtures/changes/ - kickoff moves, postponements, venue
  switches and broadcasters added, as a diff feed — poll this instead of
  re-fetching fixture lists to spot what changed
- GET /api/v2/leagues/ , /api/v2/leagues/{id}/standings/
- GET /api/v2/teams/ , /api/v2/teams/{id}/ , /{id}/squad/ , /{id}/fixtures/
- GET /api/v2/teams/{id}/form/ - last-N matches already averaged, split by
  venue and opponent strength; one call instead of a stats call per match
- GET /api/v2/players/ , /api/v2/players/{id}/
- GET /api/v2/odds/ - odds across matches; always filter by sport
- GET /api/v2/transfers/ , /api/v2/venues/ , /api/v2/referees/
- GET /api/v2/coverage/ - what is in season right now, no token needed
- GET /img/{type}/{id}/ - team, league and player images

Other sports live under /tennis/api/v2/, /padel/api/v2/, /csgo/api/v2/,
/darts/api/v2/, /hockey/api/v2/, /basketball/api/v2/ and
/horseracing/api/v2/, and follow the same conventions.

## MCP servers

Streamable HTTP, OAuth or token auth:

- https://sports.bzzoiro.com/mcp (football, free)
- https://sports.bzzoiro.com/tennis/mcp
- https://sports.bzzoiro.com/padel/mcp
- https://sports.bzzoiro.com/csgo/mcp
- https://sports.bzzoiro.com/darts/mcp
- https://sports.bzzoiro.com/hockey/mcp
- https://sports.bzzoiro.com/basketball/mcp
- https://sports.bzzoiro.com/horseracing/mcp

initialize, tools/list and ping work unauthenticated so connector validation
succeeds before sign-in; tools/call always needs auth.

## Live data

WebSocket at wss://sports.bzzoiro.com/live/football/ carries score, clock,
match actions and ball data. It does NOT carry in-play odds: we do not
publish a moving in-play consensus, and every REST quote carries the instant
we observed it so you can always tell how old a price is.

## Conventions

- Decimal odds only.
- Unknown query parameters are rejected with 400 rather than ignored, so a
  typo in a filter fails loudly instead of returning the unfiltered list.
- Resolve ids through the search endpoints; never guess them.
- Every docs page is also plain markdown: append .md to its URL.

## Developer resources

- API docs: https://sports.bzzoiro.com/docs/
- OpenAPI spec: https://sports.bzzoiro.com/openapi.json (and .yaml)
- Expanded index: https://sports.bzzoiro.com/.well-known/llms-full.txt
- Pricing: https://sports.bzzoiro.com/.well-known/pricing.md
- 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
- Agent skills: https://sports.bzzoiro.com/.well-known/agent-skills/index.json
- Status: https://sports.bzzoiro.com/status/