{"openapi":"3.1.0","info":{"title":"Ball Ranks API","version":"1.0.0","description":"Read-only fantasy basketball and football rankings and projections from Ball Ranks.","contact":{"name":"Ball Ranks support","url":"https://ballranks.com/support","email":"help@ballranks.com"},"license":{"name":"Ball Ranks Terms of Service","url":"https://ballranks.com/terms"}},"servers":[{"url":"https://ballranks.com","description":"Production"}],"tags":[{"name":"Rankings and projections"}],"paths":{"/api/v1/rankings/weekly":{"get":{"operationId":"getWeeklyRankings","summary":"Get weekly football rankings","description":"Returns weekly fantasy football rankings for one position and scoring format.","tags":["Rankings and projections"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"sport","in":"query","required":false,"description":"Fantasy sport.","schema":{"type":"string","enum":["basketball","football"],"default":"football"}},{"name":"season","in":"query","required":false,"description":"Published season label. Omit it to use the current published season.","schema":{"oneOf":[{"type":"string","maxLength":32},{"type":"integer"}]}},{"name":"week","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":18}},{"name":"position","in":"query","required":false,"schema":{"type":"string","enum":["QB","RB","WR","TE","K","DST"],"default":"RB"}},{"name":"scoring_format","in":"query","required":false,"description":"Football scoring format. Basketball uses nine-category scoring.","schema":{"type":"string","enum":["standard","half_ppr","ppr"],"default":"ppr"}},{"name":"model","in":"query","required":false,"description":"Ball Ranks model. Model v1 requires Premium access.","schema":{"type":"string","enum":["v0","v1"],"default":"v0"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Weekly football ranking board.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"apiVersion":{"type":"string","const":"1"},"capability":{"type":"string","enum":["weekly_rankings","season_rankings","player_rankings","player_projections"]},"sport":{"type":"string","enum":["basketball","football"]},"model":{"type":"string","enum":["v0","v1"]},"modelDataVersion":{"type":"string"},"generatedAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]}},"required":["apiVersion","capability","sport","model","modelDataVersion","generatedAt","updatedAt"],"additionalProperties":false},"sourceUrl":{"type":"string","format":"uri"},"query":{"type":"object","properties":{"season":{"type":["string","number"]},"week":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"position":{"type":"string","enum":["QB","RB","WR","TE","K","DST"]},"scoringFormat":{"type":"string","enum":["standard","half_ppr","ppr"]},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["season","week","position","scoringFormat","limit","offset"],"additionalProperties":false},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rankings":{"type":"array","items":{"type":"object","properties":{"player":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"team":{"type":["string","null"]},"position":{"type":["string","null"]}},"required":["id","name","team","position"],"additionalProperties":false},"rank":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"projectedPoints":{"type":"number"}},"required":["player","rank","projectedPoints"],"additionalProperties":false}}},"required":["meta","sourceUrl","query","total","rankings"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnsupportedCombination"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/rankings/season":{"get":{"operationId":"getSeasonRankings","summary":"Get season rankings","description":"Returns a fantasy basketball or football season ranking board.","tags":["Rankings and projections"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"sport","in":"query","required":true,"description":"Fantasy sport.","schema":{"type":"string","enum":["basketball","football"]}},{"name":"season","in":"query","required":false,"description":"Published season label. Omit it to use the current published season.","schema":{"oneOf":[{"type":"string","maxLength":32},{"type":"integer"}]}},{"name":"scoring_format","in":"query","required":false,"description":"Football scoring format. Basketball uses nine-category scoring.","schema":{"type":"string","enum":["standard","half_ppr","ppr"],"default":"ppr"}},{"name":"model","in":"query","required":false,"description":"Ball Ranks model. Model v1 requires Premium access.","schema":{"type":"string","enum":["v0","v1"],"default":"v0"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Number of results to skip.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Season ranking board.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"apiVersion":{"type":"string","const":"1"},"capability":{"type":"string","enum":["weekly_rankings","season_rankings","player_rankings","player_projections"]},"sport":{"type":"string","enum":["basketball","football"]},"model":{"type":"string","enum":["v0","v1"]},"modelDataVersion":{"type":"string"},"generatedAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]}},"required":["apiVersion","capability","sport","model","modelDataVersion","generatedAt","updatedAt"],"additionalProperties":false},"sourceUrl":{"type":"string","format":"uri"},"query":{"type":"object","properties":{"season":{"type":["string","number"]},"scoring":{"type":"string","const":"nine_category"},"mode":{"type":"string","const":"per_game"},"scoringFormat":{"type":"string","enum":["standard","half_ppr","ppr"]},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["season","limit","offset"],"additionalProperties":false},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rankings":{"type":"array","items":{"type":"object","properties":{"player":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"team":{"type":["string","null"]},"position":{"type":["string","null"]}},"required":["id","name","team","position"],"additionalProperties":false},"rank":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"value":{"type":"number"},"mode":{"type":"string","const":"per_game"},"scoring":{"type":"string","const":"nine_category"},"positionRank":{"type":["number","null"]},"projectedPoints":{"type":["number","null"]}},"required":["player","rank"],"additionalProperties":false}}},"required":["meta","sourceUrl","query","total","rankings"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnsupportedCombination"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/players/{player}/rankings":{"get":{"operationId":"getPlayerRankings","summary":"Get a player's season ranking","description":"Returns one player's published season ranking by player ID or slug.","tags":["Rankings and projections"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"player","in":"path","required":true,"description":"Ball Ranks player ID or slug.","schema":{"type":"string","minLength":1,"maxLength":160}},{"name":"sport","in":"query","required":true,"description":"Fantasy sport.","schema":{"type":"string","enum":["basketball","football"]}},{"name":"season","in":"query","required":false,"description":"Published season label. Omit it to use the current published season.","schema":{"oneOf":[{"type":"string","maxLength":32},{"type":"integer"}]}},{"name":"scoring_format","in":"query","required":false,"description":"Football scoring format. Basketball uses nine-category scoring.","schema":{"type":"string","enum":["standard","half_ppr","ppr"],"default":"ppr"}},{"name":"model","in":"query","required":false,"description":"Ball Ranks model. Model v1 requires Premium access.","schema":{"type":"string","enum":["v0","v1"],"default":"v0"}}],"responses":{"200":{"description":"Player season ranking.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"apiVersion":{"type":"string","const":"1"},"capability":{"type":"string","enum":["weekly_rankings","season_rankings","player_rankings","player_projections"]},"sport":{"type":"string","enum":["basketball","football"]},"model":{"type":"string","enum":["v0","v1"]},"modelDataVersion":{"type":"string"},"generatedAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]}},"required":["apiVersion","capability","sport","model","modelDataVersion","generatedAt","updatedAt"],"additionalProperties":false},"sourceUrl":{"type":"string","format":"uri"},"player":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"team":{"type":["string","null"]},"position":{"type":["string","null"]}},"required":["id","name","team","position"],"additionalProperties":false},"season":{"type":["string","number"]},"scoringFormat":{"type":"string","enum":["standard","half_ppr","ppr"]},"ranking":{"type":"object","properties":{"rank":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"value":{"type":"number"},"mode":{"type":"string","const":"per_game"},"scoring":{"type":"string","const":"nine_category"},"positionRank":{"type":["number","null"]},"projectedPoints":{"type":["number","null"]}},"required":["rank"],"additionalProperties":false}},"required":["meta","sourceUrl","player","season","ranking"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnsupportedCombination"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/players/{player}/projections":{"get":{"operationId":"getPlayerProjections","summary":"Get a player's projection","description":"Returns one player's season projection, or a weekly football projection.","tags":["Rankings and projections"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"player","in":"path","required":true,"description":"Ball Ranks player ID or slug.","schema":{"type":"string","minLength":1,"maxLength":160}},{"name":"sport","in":"query","required":true,"description":"Fantasy sport.","schema":{"type":"string","enum":["basketball","football"]}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["season","weekly"],"default":"season"}},{"name":"season","in":"query","required":false,"description":"Published season label. Omit it to use the current published season.","schema":{"oneOf":[{"type":"string","maxLength":32},{"type":"integer"}]}},{"name":"week","in":"query","required":false,"description":"Required when scope is weekly.","schema":{"type":"integer","minimum":1,"maximum":18}},{"name":"scoring_format","in":"query","required":false,"description":"Football scoring format. Basketball uses nine-category scoring.","schema":{"type":"string","enum":["standard","half_ppr","ppr"],"default":"ppr"}},{"name":"model","in":"query","required":false,"description":"Ball Ranks model. Model v1 requires Premium access.","schema":{"type":"string","enum":["v0","v1"],"default":"v0"}}],"responses":{"200":{"description":"Player projection.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"apiVersion":{"type":"string","const":"1"},"capability":{"type":"string","enum":["weekly_rankings","season_rankings","player_rankings","player_projections"]},"sport":{"type":"string","enum":["basketball","football"]},"model":{"type":"string","enum":["v0","v1"]},"modelDataVersion":{"type":"string"},"generatedAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]}},"required":["apiVersion","capability","sport","model","modelDataVersion","generatedAt","updatedAt"],"additionalProperties":false},"sourceUrl":{"type":"string","format":"uri"},"player":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"team":{"type":["string","null"]},"position":{"type":["string","null"]}},"required":["id","name","team","position"],"additionalProperties":false},"scope":{"type":"string","enum":["season","weekly"]},"season":{"type":["string","number"]},"week":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"scoringFormat":{"type":"string","enum":["standard","half_ppr","ppr"]},"projection":{"type":"object","properties":{"games":{"type":["number","null"]},"minutesPerGame":{"type":"number"},"projectedPoints":{"type":["number","null"]},"positionRank":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"opponent":{"type":["string","null"]},"home":{"type":"boolean"},"stats":{"type":"object","properties":{"pts":{"type":"number"},"reb":{"type":"number"},"ast":{"type":"number"},"stl":{"type":"number"},"blk":{"type":"number"},"fg3m":{"type":"number"},"fg_pct":{"type":"number"},"ft_pct":{"type":"number"},"tov":{"type":"number"}},"required":["pts","reb","ast","stl","blk","fg3m","fg_pct","ft_pct","tov"],"additionalProperties":false}},"additionalProperties":false}},"required":["meta","sourceUrl","player","scope","season","projection"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnsupportedCombination"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Ball Ranks API key","description":"Optional Ball Ranks API key. Anonymous requests receive lower limits and Model v0 access only."}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"Unauthorized":{"description":"Invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"Forbidden":{"description":"The requested model requires Premium access.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"NotFound":{"description":"The player or published data was not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"UnsupportedCombination":{"description":"The requested sport, scope, season, or scoring combination is not supported.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"RateLimited":{"description":"Request limit reached.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"Unavailable":{"description":"The API or request limiter is temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["apiVersion","error"],"properties":{"apiVersion":{"type":"string","const":"1"},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"externalDocs":{"description":"Ball Ranks developer documentation","url":"https://ballranks.com/developers"}}