nfl-data-loader 0.0.1

A Python interface for various NFL data sources

nfl-data-loader

nfl-data-loader is a robust Python package for accessing, merging, and transforming NFL sports data from multiple sources in an object-oriented, pipeline-friendly way. It provides a unified API for teams, players, events, and venues, with rich schema documentation and ready-to-use data loaders, transformers, and formatters.

TheEdgePredictor Services

Upstream

• espn-api-orm
  • team-data-pump
  • venue-data-pump
  • event-data-pump
    • elo-rating
  • odds-data-pump
  • fantasy-data-pump
• nfl-madden-data

Downstream

• nfl-feature-store
• nfl-model-store
• nfl-madden-data

🚀 Features

• Unified access to NFL data from multiple sources (nflverse, Madden, Pro Football Reference, ESPN API)
• Modular loader, transform, and formatter architecture
• Pydantic schemas for all endpoints and data objects
• Grouped by: team, player, event, venue
• Easy integration into ML/data pipelines
• Auto-deploy to PyPI on merge to main (see CI/CD)

📦 Data Sources

• feature-store
• Madden EA / madden.weebly
• Pro Football Reference
• ESPN API, fantasy-data-pump
• nflverse
• greerreNFL

🏗️ Architecture

┌────────────┐   ┌────────────┐   ┌────────────┐
│  Sources   │→→ │ Formatters │→→ │  Workflows │
└────────────┘   └────────────┘   └────────────┘
      │               │                │
   [team, player, event, venue]  [Extract, Transform, Load Blocks and Pipelines]

🧩 Loader Groups

• Team: Team stats, rosters, schedules, advanced metrics
• Player: Player stats, depth charts, Madden ratings, combine data
• Event: Game-level stats, play-by-play, Vegas lines, EPA, fantasy
• Venue: Stadium/venue metadata and mappings

📑 Schemas & Data Dictionary

All endpoints return data validated by Pydantic schemas. See /schemas for:

• Field names, types, and descriptions (see schemas/events/features.py, schemas/players/madden.py, schemas/players/position.py)
• Example: Player Madden schema, event feature schema, position mappers

🛠️ Usage Example

from nfl_data_loader.api.sources.players.rosters.rosters import collect_roster
from nfl_data_loader.workflows.transforms.players.player import make_player_stats

# Load player roster for a season
roster_df = collect_roster(2024)

# Transform player stats
player_stats = make_player_stats(2024, week=1, position_group='quarterback')

📈 Data Flow Example

1. Load: Pull raw data from any source (e.g., ESPN, nflverse) or pull cached feature store (Event, Player)
2. Transform: Apply rolling averages, imputation, feature engineering
3. Format: Output as DataFrame, JSON, or for ML pipelines

🧪 Testing & Validation

• All endpoints are covered by tests (see /tests)
• Schemas are validated with Pydantic
• Linting and type checking enabled

🤖 CI/CD & PyPI Deployment

• GitHub Actions workflow auto-deploys to PyPI on merge to main
• See .github/workflows/publish.yml for details

🤝 Contributing

Pull requests welcome! Please add/expand tests and update schema docs for new endpoints.

---

For a full list of available endpoints, schemas, and data fields, see the /schemas and /api directories. For questions or issues, open a GitHub issue.