lukhed-sports 0.10.4

A collection of sports analysis utility functions and API wrappers

lukhed_sports

A collection of sports analysis utility functions and API wrappers

Installation

pip install lukhed-sports

Available Wrappers and Classes

• Sportspage Feeds Wrapper - For sports schedules and odds from sportspagefeeds API
• Draftkings Sports Wrapper - For obtaining live data from Draftkings sportsbook
• ESPN NFL Stats Wrapper - For retrieving NFL team and player statistics from ESPN
• NFL Next Gen Stats Schedule - For accessing NFL schedule data from Next Gen Stats API
• OpenGolfAPI Wrapper - For golf course data, scorecards, weather, scoring, and more from OpenGolfAPI

Drafkings Sportsbook Wrapper

Access live data from Draftkings Sportsbook via their API methods. Quick start information below. Full documentation coming. This class is still a work in progress.

Table of Contents

• Instantiation
• get_available_leagues(sport)
• get_spread_for_team(league, sport)
• get_game_lines_for_league(league)
• get_basic_touchdown_scorer_props(league, prop_type_filter=None, game_filter=None)

Instantiation

from lukhed_sports import DkSportsbook
api = DkSportsbook()

get_available_leagues

Provides valid league inputs for various methods.

leagues = api.get_available_leagues('basketball')

[
    "argentina - liga nacional de basquetbol",
    "australia - nbl",
    "brazil - nbb",
    "china - cba",
    "college basketball (m)",
    "college basketball (w)",
    "croatia premier league",
    "germany - bundesliga",
    "greece - basket league",
    "israel - super league (w)",
    "italy - lega 1",
    "korea - basketball league (w)",
    "nba",
    "turkey - bsl",
    "wnba"
]

get_spread_for_team

Provides the current spread and spread odds for the given team.

spread = api.get_spread_for_team('nfl', 'commanders')

{
    "spread": 5.5,
    "odds": {
        "american": "-108",
        "decimal": "1.92",
        "fractional": "25/27"
    }
}

get_gamelines_for_league

Provides all the gamelines available for a given league.

gamelines = api.get_gamelines_for_league('nfl')

Full example response

get_basic_touchdown_scorer_props

Provides all the basic td scoring props available, with various filter options.

td = api.get_basic_touchdown_scorer_props('college football', prop_type_filter='anytime', game_filter='notre dame')

[
    {
        "id": "0QA229129141#130806310_13L87637Q1477509025Q20",
        "marketId": "229129141",
        "label": "Jeremiah Smith",
        "displayOdds": {
            "american": "-140",
            "decimal": "1.71",
            "fractional": "5/7"
        },
        "trueOdds": 1.71428572,
        "outcomeType": "Anytime Scorer",
        "participants": [
            {
                "id": "786772",
                "name": "Jeremiah Smith",
                "type": "Player",
                "seoIdentifier": "Jeremiah Smith"
            }
        ],
        "sortOrder": 3001710,
        "tags": [
            "SGP",
            "1stFavorite"
        ],
        "metadata": {}
    },
    {
        "id": "0QA229129141#130806308_13L87637Q1709721529Q20",
        "marketId": "229129141",
        "label": "TreVeyon Henderson",
        "displayOdds": {
            "american": "-140",
            "decimal": "1.71",
            "fractional": "5/7"
        },
        "trueOdds": 1.71428572,
        "outcomeType": "Anytime Scorer",
        "participants": [
            {
                "id": "570977",
                "name": "TreVeyon Henderson",
                "type": "Player",
                "seoIdentifier": "TreVeyon Henderson"
            }
        ],
        "sortOrder": 3001710,
        "tags": [
            "SGP",
            "2ndFavorite"
        ],
        "metadata": {}
    },
    ...

ESPN NFL Stats Wrapper

Access team and player statistics from ESPN for the NFL. This wrapper provides functionality to retrieve team statistics, player rosters, player search, and detailed player statistics.

Partial documentation below. See examples.py in the repo for more.

Table of Contents

• Instantiation
• Team Statistics
• Player Search
• Player Statistics

Instantiation

from lukhed_sports import EspnNflStats
espn = EspnNflStats()

Team Statistics

Get comprehensive team statistics for the NFL.

# Get all team stats for a specific season
stats = espn.get_all_teams_stats(2023, regular_or_offseason='regular')

# Get offensive stats summary for a team
offense_summary = espn.team_stats_get_ypg_summary('DET', ball_side='offense')

Player Search

Search for players with various filtering options, including fuzzy name matching.

# Basic search
players = espn.player_search('Mahomes')

# Advanced search with fuzzy matching
players = espn.player_search('Mahomes', fuzzy_search=True, fuzzy_threshold=80)

Player Statistics

Access detailed player statistics including career stats, game logs, and splits.

# Get overview stats (page: https://www.espn.com/nfl/player/_/id/3139477/patrick-mahomes)
player_overview = espn.get_player_stat_overview('Patrick Mahomes', team='KC')

# Get player career bio information (page: https://www.espn.com/nfl/player/bio/_/id/3139477/patrick-mahomes)
player_bio = espn.get_player_stat_bio('Patrick Mahomes')

# Get player game log for season (page: https://www.espn.com/nfl/player/gamelog/_/id/3139477/type/nfl/year/2023)
game_log = espn.get_player_stat_gamelog('Patrick Mahomes', season='2023')

# Get player statistical splits (page: https://www.espn.com/nfl/player/splits/_/id/3139477/patrick-mahomes)
splits = espn.get_player_stat_splits('Patrick Mahomes')

# Get college stats for a player (page: https://www.espn.com/nfl/player/gamelog/_/id/3916387/type/college-football)
college_stats = espn.get_player_stat_gamelog('jackson', last_name_search=True, team='bal', position='QB', 
                                             league='college')

Sportspage Feeds Wrapper

This class is a custom wrapper for the sportspagefeeds API.

It provides:

• Management of api key -> You can store api key locally (by default) or with a private github repo so you can use the api efficiently across different hardware.
• Optionally manage api limits (on by default)
• Methods to utilize each endpoint from sportspagefeeds
• Optionally validate input (on by default), to ensure you do not waste API calls
• Methods to get valid inputs for each endpoint, as documentation is sparse
• Methods to parse data returned by basic (non-paid) endpoints

Quick start information below. Full documentation for this class is in development.

API Key Management Locally

Instatiate without optional parameters and upon first use, the class will take you thru setup (copy and paste your Sportspage key)

api = SportsPage()

API Key Managment with Private Github Repo

Instantiate with option github parameters and Upon first use, class will take you thru setup (github token and Sportspage key). Future instantiation, just reference the github_project.

# 
api = SportsPage(
    config_file_preference='github', 
    github_project='any_project_name'
    )

Games

Get the games occuring today with basic schedule and odds information.

api.get_games('nfl')

See full example response see here.

Rankings

Get rankings for the given target.

rankings = api.get_rankings('ncaaf')

See full example response see here.

Check API Usage

Free tier of Sportspage is limited. You can check your api usage with this method.

api.check_api_limit()

# print to console
>>>
You have 15 api calls remaining
Your reset time is set for 20241230194114 US/Eastern
Your limit is 20

Response

{
    "limit": 20,
    "remaining": 15,
    "resetTime": "20250105194115",
    "lastCall": "20250105121251"
}

All Endpoints

api.get_games           # Get schedule/status of games
api.get_rankings        # Get rankings for various leagues    
api.get_teams           # Get teams in leagues/conferences
api.get_conferences     # Get conferences in leagues
api.get_game_by_id      # Get info about a game by its ID
api.get_odds            # Get odds for a game (requires paid tier)

Example responses

• get_games nfl
• get_rankings ncaaf
• get_teams ncaaf
• get_conferences ncaab
• get_game_by_id nfl game id
• get_odds error response for non paid

NFL Next Gen Stats Schedule

Access NFL schedule data from the Next Gen Stats API. This class provides methods to retrieve schedule information and game overviews.

Table of Contents

• Instantiation
• Basic Usage
• Game Data
• Team Information

Instantiation

from lukhed_sports.nflSchedules import NextGenStatsSchedule
ngs = NextGenStatsSchedule(season='current')  # or specific season like 2023

Basic Usage

Get schedule data and regular season games:

# Get full schedule
schedule = ngs.get_schedule()

# Get regular season games for a specific team
lions_games = ngs.get_regular_season_games('DET')

# Change season
ngs.change_season(2022)

Game Data

Access specific game data and overviews:

# Get data for a specific game given team and week input
game_data = ngs.get_game_data('DET', 1)

# Get detailed game overview with stats given team and week input
game_overview = ngs.get_game_overview_for_team('DET', 1)

Team Information

Get a list of all NFL teams with their nicknames and abbreviations:

# Get all teams with their details
teams = ngs.get_all_teams()

# Example output
[
    {
        "nickname": "Lions",
        "abbreviation": "DET",
        "displayName": "Detroit Lions"
    },
    ...
]

Note: Team abbreviations should match those used on the NGS game center page: https://nextgenstats.nfl.com/stats/game-center-index

OpenGolfAPI Wrapper

This class is a custom wrapper for OpenGolfAPI - golf's open data standard: course data for all 16,759 US courses, full scorecards, tee ratings and slopes, live weather, climate, spatial features, a free scoring engine, competitions, and shot/moment contribution.

It provides:

• Free keyless access to all read endpoints (1,000 requests/day per IP) and gross scoring - no signup needed
• Optional management of a free api key (only needed for write/contribution endpoints) -> You can store your api key locally or with a private github repo so you can use the api efficiently across different hardware
• Methods for every endpoint in the API
• Helpful errors when a keyed method is called without a key configured, so you don't waste calls

Table of Contents

• Instantiation
• Course Search
• Scorecard Details
• Course Geo Features
• All Endpoints

Instantiation

Keyless (all read methods + gross scoring):

from lukhed_sports import OpenGolfApi
og = OpenGolfApi()

With a free api key (needed only for write/contribution methods, e.g. posting shots/moments). Upon first use, the class will take you thru setup (copy and paste your OpenGolfAPI key):

og = OpenGolfApi(key_management='local')    # store key on your local machine
og = OpenGolfApi(key_management='github')   # store key in your private github repo

Course Search

Search courses by name, state, or location (e.g., supporting a user selecting the course they are playing).

search = og.search_courses(q='whistling straits', limit=10)
# search = og.search_courses(q='pebble', state='CA', limit=10)
# search = og.search_courses(lat=43.85, lng=-87.73, radius_mi=25)     # "courses near me"

for c in search['courses']:
    print(f"{c['course_name']} ({c['city']}, {c['state']}) - {c['holes']} holes, par {c['par']}")

{
    "courses": [
        {
            "id": "2d201c28-68ec-4897-b7b1-8f19c8984d26",
            "course_name": "Whistling Straits",
            "city": "Sheboygan",
            "state": "WI",
            "country_iso": "US",
            "lat": 43.8498513,
            "lng": -87.7346448,
            "type": "Public",
            "par": 72,
            "holes": 18,
            "completeness": 0
        }
    ],
    "total": 1
}

Scorecard Details

Get everything needed to display a scorecard: tee sets (rating/slope/total yardage) and per-hole par, handicap index, and yardage by tee.

course_id = search['courses'][0]['id']
course = og.get_course(course_id)     # full detail: tees + holes_data + climate/pricing/insights
tees = course['tees']                 # or og.get_course_tees(course_id)['tees']
holes = course['holes_data']          # or og.get_course_holes(course_id)['holes']

Example tee entry:

{
    "tee_key": "black-male",
    "tee_name": "Black",
    "tee_color": "black",
    "gender": "Male",
    "course_rating": 75.6,
    "slope": 146,
    "par": 72,
    "yardage": 7201
}

Example hole entry:

{
    "number": 1,
    "par": 4,
    "handicap_index": 4,
    "yardages": {
        "red": 301,
        "blue": 387,
        "black": 400,
        "green": 369,
        "white": 359
    },
    "hazards": []
}

Course Geo Features

Get geo locations for map display (greens, bunkers, water). The free layer is coarse OSM polygons; green centers work well as pin locations.

greens = og.get_course_features(course_id, feature_type='green')
for green in greens['features']:
    print(f"green {green['id'][0:8]}: center {green['center']}")   # 'geometry' key has the full polygon

# bunkers/water for the same map
bunkers = og.get_course_features(course_id, feature_type='bunker')

# rangefinder-style: nearest greens to the user's GPS position
nearest = og.get_nearest_features(user_lat, user_lng, feature_type='green')

Example feature entry:

{
    "id": "525c0df7-2bc5-46d5-91b2-340cdf173fef",
    "tags": ["golf=green", "surface=grass"],
    "center": {
        "lat": 43.8477141917785,
        "lng": -87.7348943509377
    },
    "source": "osm",
    "license": "odbl",
    "geometry": {"type": "MultiPolygon", "coordinates": ["..."]}
}

All Endpoints

All OpenGolfAPI methods are implemented in this class, covering every endpoint in the spec: courses, spatial features, scoring (OpenMatch), competitions, organizations, assets, sessions, events, players/awards, webhooks, contribution (shots/moments/corrections/import), OpenGolf Chain, claims, identity/oauth, developer keys, and meta/docs. See the OpenGolfAPI documentation for details on each endpoint, and the class docstrings in openGolfWrapper.py for the corresponding method parameters.