Ball Ranks

Use Ball Ranks rankings and projections to answer fantasy basketball (NBA) and football (NFL) questions with current published numbers and a source link.

Connect

Prefer the Ball Ranks MCP tools when connected. The Streamable HTTP server is https://ballranks.com/api/mcp. Use a standard MCP client to initialize the connection and discover its tools; plain GET requests do not call MCP tools.

If MCP is unavailable, make read-only REST requests to https://ballranks.com. Consult the live OpenAPI schema for full field definitions and developer documentation for current access limits.

Anonymous access uses Model Zero (model=v0, the default). If the user supplies a Ball Ranks API key, send Authorization: Bearer <key> on requests to Ball Ranks only. Keys come from Account; keep them out of URLs, logs, answers, and committed files. Model One (model=v1) requires a key belonging to a Premium account. Use it only when requested and authorized.

Choose the request

• Set sport to basketball or football. Use the user’s sport; clarify if it is ambiguous.
• Omit season for the current published season. Explicit season requests must match a currently published season.
• Football uses scoring_format=standard, half_ppr, or ppr (default). Ask for the scoring format when a comparison depends on it; otherwise identify the PPR default in the answer.
• Basketball season rankings use nine-category per-game scoring. Omit scoring_format. Read the returned scoring and mode before comparing ranks.
• Weekly scopes apply to football. Weekly boards require week (1–18) and accept position: QB, RB, WR, TE, K, or DST (default RB). Specify the relevant position explicitly.
• Player projections default to scope=season; football weekly projections need scope=weekly and week.
• Use a known Ball Ranks player ID or slug. In MCP pass it as player; in REST URL-encode it in the path. Board results can supply player IDs and, when present, slugs.
• Lists accept limit (1–100, default 50) and offset (0–10,000, default 0). Fetch the smallest useful page; paginate only when the task needs more results.

Examples

For a basketball draft board, call get_season_rankings with:

{"sport":"basketball","model":"v0","limit":10}

Equivalent REST request:

curl --get 'https://ballranks.com/api/v1/rankings/season' \
  --data-urlencode 'sport=basketball' --data-urlencode 'limit=10'

For a week 4 half-PPR wide receiver comparison, call get_week_rankings with:

{"sport":"football","week":4,"position":"WR","scoring_format":"half_ppr","model":"v0","limit":20}

For one player’s season numbers, call get_player_projections with:

{"sport":"basketball","player":"victor-wembanyama","scope":"season","model":"v0"}

For a football player’s weekly projection, use a known ID or slug from the returned season board with sport=football, scope=weekly, week, and the user’s scoring_format.

Use the response

MCP results include structured data and a JSON text representation; REST returns JSON. Check MCP isError as well as transport status before using a result.

Report the returned rank, projected points or basketball stat projection relevant to the question. Keep overall season rank, position rank, and weekly rank distinct; lower ranks are better. Compare players within the same sport, model, season, scope, and football scoring format.

Cite the returned sourceUrl. Identify Model Zero or Model One from meta.model; include the season and week where applicable. Use meta.generatedAt or meta.updatedAt to explain freshness when relevant. Treat meta.modelDataVersion as a version identifier, and keep null values distinct from zero. Rankings and projections support advice; label your own recommendation or calculation clearly.

Limits and errors

Current documented allowances: anonymous access 10 requests/day per originating IP; Free keys 8/minute and 80/day; Premium keys 60/minute and 1,000/day. REST and MCP share access limits. An additional IP guard applies before authentication. Prefer one ranking board over repeated player lookups when it answers the task.

MCP can return tool errors inside a successful transport response, and rate-limit failures in a JSON-RPC error envelope. Read those errors rather than inventing rankings or projections.