Skip to main content

​
Overview

This guide walks you through setting up Fantasy Basketball Analytics for local development or self-hosting. The application is built with Python Flask and requires OAuth credentials from Yahoo Developer Network.

​
Prerequisites

Before you begin, ensure you have:

Python 3.8+

Python runtime environment installed on your system

ngrok

For local development OAuth callback handling

Yahoo Developer Account

To create an application and obtain OAuth credentials

Git

To clone the repository

​
Installation Steps

1

Clone the Repository

First, clone the Fantasy Basketball Analytics repository to your local machine:
git clone https://github.com/AlexIbby/fantasyBasketball.git
cd fantasyBasketball
2

Install Python Dependencies

Install all required Python packages using pip:
pip install -r requirements.txt
The application requires the following packages:
requirements.txt
Authlib==1.5.2
blinker==1.9.0
certifi==2025.1.31
cffi==1.17.1
charset-normalizer==3.4.1
click==8.1.8
colorama==0.4.6
cryptography==44.0.2
Flask==3.1.0
gunicorn==23.0.0
idna==3.10
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==3.0.2
nba_api==1.9.0
numpy==2.2.5
packaging==25.0
pandas==2.2.3
pycparser==2.22
python-dateutil==2.9.0.post0
python-dotenv==1.1.0
pytz==2025.2
requests==2.32.3
six==1.17.0
tzdata==2025.2
urllib3==2.4.0
Werkzeug==3.1.3
xmltodict==0.14.2
Consider using a virtual environment to isolate dependencies:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
3

Create Yahoo Developer Application

Register your application with Yahoo to obtain OAuth credentials:
  1. Go to Yahoo Developer Network
  2. Click “My Apps” and create a new application
  3. Fill in the application details:
    • Application Name: Fantasy Basketball Analytics (or your preferred name)
    • Application Type: Web Application
    • Callback Domain: You’ll update this after setting up ngrok
  4. Under API Permissions:
    • Select Fantasy Sports
    • Choose Read permissions
  5. Save your application and note the Client ID and Client Secret
Keep your Client ID and Client Secret secure. Never commit them to version control.
4

Configure ngrok for Local Development

ngrok creates a secure tunnel to your localhost, which is required for Yahoo OAuth callbacks during development.
  1. Install ngrok from ngrok.com
  2. Start ngrok in a separate terminal window: 
    ngrok http 5000
  3. Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok.io)
  4. Go back to your Yahoo Developer application settings
  5. Set the Redirect URI to: https://your-ngrok-url.ngrok.io/callback
Keep the ngrok terminal window open while developing. If ngrok restarts, you’ll get a new URL and need to update your Yahoo app settings.
5

Set Up Environment Variables

Create a .env file in the project root with your configuration:
cp .env.example .env
Then edit the .env file with your values:
YAHOO_CLIENT_ID=your_yahoo_client_id
YAHOO_CLIENT_SECRET=your_yahoo_client_secret
FLASK_SECRET_KEY=your_secret_key_for_sessions
FLASK_ENV=development

​
Environment Variables Explained

VariableDescriptionRequired
YAHOO_CLIENT_IDYour Yahoo app’s Client ID from the developer consoleYes
YAHOO_CLIENT_SECRETYour Yahoo app’s Client Secret from the developer consoleYes
FLASK_SECRET_KEYSecret key for Flask session encryption (generate a random string)Yes
FLASK_ENVSet to development for local development, production for deploymentNo
Generate a secure Flask secret key using Python:
import secrets
print(secrets.token_hex(32))
6

Run the Application

Start the Flask development server:
python main.py
The application will start on http://localhost:5000 with debug mode enabled.You should see output similar to:
* Serving Flask app 'main'
* Debug mode: on
* Running on http://0.0.0.0:5000
7

Access the Application

Open your browser and navigate to your ngrok HTTPS URL (not localhost):
https://your-ngrok-url.ngrok.io
You must use the ngrok URL (not localhost) for Yahoo OAuth to work correctly.
  1. Click “Login with Yahoo”
  2. Authorize the application
  3. Select your fantasy basketball league
  4. Start exploring your analytics!

​
OAuth Setup Deep Dive

The application uses Yahoo’s OAuth 2.0 flow for authentication. Here’s how it works:

​
OAuth Flow

  1. Login Request (/login): User clicks login, app redirects to Yahoo with client ID
  2. User Authorization: User approves app access on Yahoo’s site
  3. Callback (/callback): Yahoo redirects back with authorization code
  4. Token Exchange: App exchanges code for access token and refresh token
  5. API Requests: App uses access token to call Yahoo Fantasy API
  6. Token Refresh: When token expires, app uses refresh token to get new access token

​
Key Configuration Points

In main.py:126-138, the OAuth client is configured:
main.py
yahoo = oauth.register(
    name="yahoo",
    client_id=os.environ["YAHOO_CLIENT_ID"],
    client_secret=os.environ["YAHOO_CLIENT_SECRET"],
    authorize_url="https://api.login.yahoo.com/oauth2/request_auth",
    access_token_url="https://api.login.yahoo.com/oauth2/get_token",
    refresh_token_url="https://api.login.yahoo.com/oauth2/get_token",
    api_base_url="https://fantasysports.yahooapis.com/",
    client_kwargs={
        "scope": "fspt-r",
        "token_endpoint_auth_method": "client_secret_basic",
    },
)
The scope fspt-r provides read-only access to Fantasy Sports data.

​
Production Deployment

For deploying to production (e.g., Heroku):
1

Configure Production Environment

Set environment variables in your hosting platform:
  • YAHOO_CLIENT_ID
  • YAHOO_CLIENT_SECRET
  • FLASK_SECRET_KEY
  • FLASK_ENV=production (optional)
2

Update Yahoo App Redirect URI

Change the redirect URI in your Yahoo Developer app to your production domain:
https://your-app-domain.com/callback
3

Deploy with Gunicorn

The application includes a Procfile for Heroku deployment:
web: gunicorn main:app
Gunicorn is already included in requirements.txt.

​
API Endpoints Reference

The application exposes several internal API endpoints:

​
Yahoo Data Endpoints

EndpointDescriptionParameters
/api/scoreboardWeekly matchup dataweek (int)
/api/season_avgSeason-long team statisticsNone
/api/league_settingsLeague configuration and categoriesNone
/api/player_stats_week/<week>Player stats for specific weekweek (int)
/api/player_stats_seasonSeason-long player statsNone
/api/team_logoCurrent user’s team logo URLNone
/api/draft/keepersKeeper players and draft dataNone
/api/bulk_matchupsMatchup data for multiple weeksweeks (range)

​
NBA Data Endpoints

EndpointDescription
/api/nba_playersActive NBA players list
/api/nba_player_stats/<player_id>Individual player statistics

​
Troubleshooting

​
Common Issues

  • Verify your ngrok URL matches the redirect URI in Yahoo app settings
  • Ensure you’re accessing via HTTPS (ngrok URL, not localhost)
  • Check that your Client ID and Client Secret are correct in .env
  • Make sure ngrok is still running (restart if needed)
  • Confirm you have an active Yahoo Fantasy Basketball league
  • Verify the league is H2H Categories (not Roto or Points)
  • Check that you’re the owner or a member of the league
  • Review browser console for API errors
  • The NBA API may be temporarily unavailable
  • Check your internet connection
  • Review the console logs for specific error messages
  • The app has a fallback to static player data if the live API fails
  • The app automatically refreshes tokens, but if you see repeated errors:
  • Clear your browser cookies and session data
  • Log out and log back in
  • Verify your Yahoo app credentials are still valid

​
Debug Endpoints

Two debug endpoints are available when logged in:
  • /debug/league_settings - Raw league settings data from Yahoo
  • /debug/scoreboard?week=1 - Raw scoreboard data for a specific week
These display the raw JSON responses from Yahoo’s API.

​
Next Steps

Quick Start Guide

Learn how to use the platform features

Contributing

Contribute to the project on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us