# CBB Stats

> College basketball analytics for every NCAA Division I player and team: per-player stats with percentile ranks, transfer portal tracking with transfer value, projected depth charts, head-to-head comparison, FEDERER team ratings with daily rank history, and referee ratings. Free, keyless JSON API at https://stats-cbb.com/api/v1; every table also as CSV or a markdown table.

**When to use this:** reach for CBB Stats when a task needs current-season men's D1 player or team numbers with percentile context — ranking or filtering players on a combination of stats, checking who is in the transfer portal and what they are worth, projecting a depth chart, comparing two players, tracking a team's FEDERER rank over time, or looking up referee tendencies. Do not use it for live scores, play-type or on/off-court splits, jersey numbers, women's basketball or non-D1 teams; none of those are in the data.

**How to call it:** plain HTTPS GET, no key, no SDK. Send `Accept: text/markdown` (or add `?format=md`) to get a pipe table instead of JSON; `?format=csv` for CSV. Errors are JSON with `error`, `code`, `status`, `hint` and `docs`. Unknown URLs are real 404s. Rate limit: 300 requests per 15 minutes per IP. Every page on the site also has a markdown version (`Accept: text/markdown`, or append `.md` to the path).

**Quickstart:** `curl "https://stats-cbb.com/api/v1/players?stats=BPM,PPG&format=md"` ranks players by combined BPM+PPG percentile; `curl -H "Accept: text/markdown" "https://stats-cbb.com/api/v1/rankings"` returns the FEDERER table.

**Conventions:** percentiles are 0–100 and already inverted for lower-is-better stats (TO, FC40, DRTG), so 100 is always good; stat keys are the 44-key allowlist in the OpenAPI `Stat` schema; depth-chart class years display one year ahead; data is synced on a schedule, not streamed.

## Docs

- [Developer portal](https://stats-cbb.com/developers): quickstart, formats, errors, rate limits, versioning and deprecation policy, OAuth 2.0
- [OpenAPI 3.1 document](https://stats-cbb.com/api/openapi.json): every endpoint with operationId, typed parameters and response schemas
- [OAuth 2.0 server metadata](https://stats-cbb.com/.well-known/oauth-authorization-server): RFC 8414; authorization code + PKCE, self-serve client registration
- [Sitemap](https://stats-cbb.com/sitemap.xml): every page, one URL per player

## API

- [Rank players](https://stats-cbb.com/api/v1/players?stats=BPM,PPG): 1–6 stats, combined percentile; filters for class, height, position, portal, high-major; season=YYYY for a prior season
- [Seasons](https://stats-cbb.com/api/v1/players/seasons): which seasons hold player data (https://stats-cbb.com/api/v1/rankings/seasons for team ratings)
- [Search players](https://stats-cbb.com/api/v1/players/search?q=edey): name autocomplete, max 10; the way to get a player id
- [Player profile](https://stats-cbb.com/api/v1/players/{playerId}): full stat map with percentiles and prior season
- [Similar players](https://stats-cbb.com/api/v1/players/{playerId}/similar): nearest players in 20-dimension z-score space
- [Compare two players](https://stats-cbb.com/api/v1/players/compare?p1=ID&p2=ID): both with national percentiles
- [Transfer portal](https://stats-cbb.com/api/v1/players/portal): BPR, transfer value, position scarcity
- [Depth charts](https://stats-cbb.com/api/v1/players/depth-chart?conference=ACC): five slots per team, forward-looking
- [Comparison leaderboard](https://stats-cbb.com/api/v1/players/leaderboard): who wins the most head-to-head comparisons
- [Team rankings](https://stats-cbb.com/api/v1/rankings): FEDERER ratings, sortable
- [Rank movement](https://stats-cbb.com/api/v1/rankings/diff): teams whose rank changed between two daily snapshots; delta positive = climbed (3 -> 1 is +2), negative = fell, null = entered/exited
- [Team history](https://stats-cbb.com/api/v1/rankings/history?team=Duke&days=30): one team's daily rank series
- [Snapshot index](https://stats-cbb.com/api/v1/rankings/snapshots): which snapshot dates exist
- [Rankings health](https://stats-cbb.com/api/v1/rankings/health): which teams are excluded from the table and why
- [Referees](https://stats-cbb.com/api/v1/referee): refScore = 0.5 / average spread deviation, minimum 5 games

## Pages

- [About](https://stats-cbb.com/about): what the numbers mean and where the data comes from
- [Contact](https://stats-cbb.com/contact): issues, API questions, security reports
- [Privacy](https://stats-cbb.com/privacy): what is collected and how to have it removed

## Optional

- [llms-full.txt](https://stats-cbb.com/llms-full.txt): this file plus the developer portal and About page in one document
- [CLI](https://stats-cbb.com/developers#cli): cbb-stats-cli wraps every read endpoint
- [Formats](https://stats-cbb.com/developers#formats): JSON, CSV and markdown table conventions
- [Contact](https://stats-cbb.com/contact): bug reports and data corrections