KorisAPI

Create datasets from Basket.fi data with a Python command line tool or view statistics with a Textual TUI app.

Features

• CLI Tool: Download match data, team information, and detailed statistics
• Interactive TUI: Browse matches, teams, and player statistics in a beautiful terminal interface
• Basket.fi API: Access team, league, and match data from Basket.fi with API requests
• Advanced Stats: Fetch detailed box scores and player stats from Genius Sports through HTML parsing
• Multiple Export Formats: Export data to JSON, CSV, or Excel
• Concurrent Downloads: Fast batch requests with parallel processing

Installation

This project uses uv to build and run. Install uv for MacOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

or Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After uv is installed, install the project by:

git clone https://github.com/apmnt/koris-api.git
cd koris-api
uv pip install -e ".[dev]"

CLI Usage

Use the koris-api command with different actions. Run the help command to display all options:

uv run koris-api --help

Examples:

# Season data with advanced box scores, play-by-play and shot chart coordinates
uv run koris-api season 2 huki2526 --box-score --playbyplay --shot-chart --output-dir output/1divA_huki2526

# Single match shot chart only
uv run koris-api match 2844823 --shot-chart --output-dir output

JSON Output Structure

Below is the full key layout for the sample output file in eda/data/season_boxscores/korisliiga_2024-2025_sample.json (generated by scripts/json_to_mermaid.py).

erDiagram
  OUTPUT_JSON ||--|| METADATA : metadata
  OUTPUT_JSON ||--o{ MATCHES_ITEM : matches
  MATCHES_ITEM ||--|| MATCHES_ITEM_BOXSCORE : boxscore
  MATCHES_ITEM_BOXSCORE ||--o{ MATCHES_ITEM_BOXSCORE_TEAMS_ITEM : teams
  MATCHES_ITEM_BOXSCORE_TEAMS_ITEM ||--o{ MATCHES_ITEM_BOXSCORE_TEAMS_ITEM_PLAYERS_ITEM : players
  MATCHES_ITEM_BOXSCORE_TEAMS_ITEM ||--|| MATCHES_ITEM_BOXSCORE_TEAMS_ITEM_TOTALS : totals
  MATCHES_ITEM_BOXSCORE ||--|| MATCHES_ITEM_BOXSCORE_MATCH_TOTALS : match_totals
  OUTPUT_JSON {
  }
  METADATA {
    string category_id
    string download_date
    bool include_advanced_stats
    null league_id
    int limit_games
    int matches_failed
    int matches_with_boxscore
    int played_matches_saved
    string season_id
    string season_name
    string source
    null total_games_requested
    int total_matches_in_season
  }
  MATCHES_ITEM {
    string away_score
    string away_team
    string away_team_id
    string category
    string competition
    string date
    string home_score
    string home_team
    string home_team_id
    string match_external_id
    string match_id
    string season
    string status
    string time
    string venue
  }
  MATCHES_ITEM_BOXSCORE {
    string source
  }
  MATCHES_ITEM_BOXSCORE_TEAMS_ITEM {
    string team_name
  }
  MATCHES_ITEM_BOXSCORE_TEAMS_ITEM_PLAYERS_ITEM {
    int ast
    int blk
    int def
    int field
    float ft
    int fta
    int ftm
    int index
    float k_2p
    int k_2pa
    int k_2pm
    float k_3p
    int k_3pa
    int k_3pm
    string minutes
    int off
    int pf
    string player
    int player_number
    int points
    int reb
    int stl
    string team
    int to
  }
  MATCHES_ITEM_BOXSCORE_TEAMS_ITEM_TOTALS {
    int ast
    int blk
    int def
    float ft
    int fta
    int ftm
    int index
    float k_2p
    int k_2pa
    int k_2pm
    float k_3p
    int k_3pa
    int k_3pm
    int off
    int pf
    int points
    int reb
    int stl
    int to
  }
  MATCHES_ITEM_BOXSCORE_MATCH_TOTALS {
    int ast
    int blk
    int def
    float ft
    int fta
    int ftm
    int index
    float k_2p
    int k_2pa
    int k_2pm
    float k_3p
    int k_3pa
    int k_3pm
    int off
    int pf
    int points
    int reb
    int stl
    int to
  }

Loading

TUI Usage

Launch the interactive terminal user interface to browse matches, teams, and statistics. The TUI provides an interface for viewing and exporting game data.

Starting the TUI

uv run koris-tui

Python API Usage

You can also use KorisAPI directly in your Python code:

from koris_api import KorisAPI

# Get all matches for a competition
matches = KorisAPI.get_matches(
    competition_id="huki2526",
    category_id="4"
)

# Get team information
team = KorisAPI.get_team(team_id="12345")

# Get match details
match = KorisAPI.get_match(match_id="2701885")

# Get advanced box score
boxscore = KorisAPI.get_match_boxscore(match_id="2701885")

# Get category information with seasons
category = KorisAPI.get_category(
    competition_id="huki2526",
    category_id="4"
)

Dependencies:

• requests: HTTP client
• textual: TUI framework
• pandas: Data manipulation
• openpyxl: Excel file support
• beautifulsoup4: HTML parsing
• lxml: XML/HTML parser
• tqdm: Progress bars