nfl-stadiums 2.0.4

A simple python package that provides easy access to NFL stadium data

NFL Team Stadiums

A simple Python package that provides easy access to NFL stadium data including capacity, location, weather forecasts, and more.

Table of Contents

• Features
• Installation
• Quick Start
• Usage Examples
• Data Examples
• Requirements
• Data Sources
• Contributing
• License

Features

• ✅ Complete NFL Stadium Data: Get detailed information for all current NFL stadiums
• 🌍 Coordinates & Location: Access precise latitude/longitude coordinates for each stadium
• 🌤️ Weather Forecasts: Retrieve weather data for game days and events
• 📏 Distance Calculations: Calculate distances between stadiums
• 🏟️ Stadium Search: Find stadiums by team name or stadium name

Installation

pip install nfl-stadiums

Quick Start

from nfl_stadiums import NFLStadiums

# Initialize with default settings (uses cache)
stadiums = NFLStadiums()

# Get all stadium names
stadium_list = stadiums.get_list_of_stadium_names()

# Get data for a specific team
lions_data = stadiums.get_stadium_by_team("lions")

# Get weather forecast for a game
weather = stadiums.get_weather_forecast_for_stadium('lions', '2024-12-15')

Usage Examples

Basic Stadium Operations

from nfl_stadiums import NFLStadiums

# Initialize the client
stad = NFLStadiums()

# Get a list of all stadium names
stadiums = stad.get_list_of_stadium_names()

# Get stadium data by team name
lions_stadium_data = stad.get_stadium_by_team("lions")

# Get stadium data by stadium name
stadium_data = stad.get_stadium_by_name("ford field")

Coordinates and Distance

# Get coordinates for a stadium
coords = stad.get_stadium_coordinates_by_team("lions")
coords = stad.get_stadium_coordinates_by_name("ford field")

# Calculate distance between two stadiums
miles = stad.calculate_distance_between_stadiums("lions", "rams")

Weather Forecasting

# Get weather forecast for a specific date
forecast = stad.get_weather_forecast_for_stadium('lions', '2024-05-30')

# Customize forecast parameters
forecast = stad.get_weather_forecast_for_stadium(
    "rams", 
    "2025/02/24", 
    hour_start=9, 
    hour_end=15, 
    day_format="%Y/%m/%d"
)

Configuration Options

# Force fresh data retrieval (bypass cache)
stad = NFLStadiums(use_cache=False)

# Disable verbose output
stad = NFLStadiums(verbose=False)

# Combine options
stad = NFLStadiums(use_cache=False, verbose=False)

Data Examples

Stadium Data Structure

Each stadium object contains the following information:

{
    "name": "Ford Field",
    "capacity": 65000,
    "imgUrl": "https://en.wikipedia.org/wiki/File:Packers_at_Lions_Dec_2020_(50715608723).jpg",
    "city": "Detroit, Michigan",
    "surface": "FieldTurf CORE",
    "roofType": "Fixed",
    "teams": [
        "Detroit Lions"
    ],
    "yearOpened": 2002,
    "sharedStadium": false,
    "currentTeams": [
        "DET"
    ],
    "coordinates": {
        "lat": 42.34,
        "lon": -83.04555556,
        "primary": "",
        "globe": "earth"
    }
}

Weather Data Structure

Weather forecast data includes comprehensive meteorological information:

{
    "latitude": 42.351395, 
    "longitude": -83.06134, 
    "generationtime_ms": 0.10704994201660156, 
    "utc_offset_seconds": -14400, 
    "timezone": "America/New_York", 
    "timezone_abbreviation": "EDT", 
    "elevation": 188.0, 
    "hourly_units": 
        {
            "time": "iso8601", 
            "temperature_2m": "°F", 
            "apparent_temperature": "°F", 
            "precipitation_probability": "%", 
            "precipitation": "inch", 
            "rain": "inch", 
            "showers": "inch", 
            "snowfall": "inch", 
            "snow_depth": "ft", 
            "wind_speed_10m": "mp/h", 
            "wind_speed_80m": "mp/h", 
            "wind_direction_10m": "°"
        }, 
    "hourly": 
        {
            "time": ["2024-05-30T00:00", "2024-05-30T01:00", "2024-05-30T02:00"], 
            "temperature_2m": [50.0, 48.6, 47.3], 
            "apparent_temperature": [44.8, 43.4, 43.0], 
            "precipitation_probability": [0, 0, 0], 
            "precipitation": [0.0, 0.0, 0.0], 
            "rain": [0.0, 0.0, 0.0], 
            "showers": [0.0, 0.0, 0.0], 
            "snowfall": [0.0, 0.0, 0.0], 
            "snow_depth": [0.0, 0.0, 0.0], 
            "wind_speed_10m": [4.4, 3.5, 2.2], 
            "wind_speed_80m": [13.5, 11.1, 10.3], 
            "wind_direction_10m": [15, 18, 323]
        }
}

Requirements

• Python 3.6 or higher
• Internet connection for data retrieval
• Dependencies are automatically installed with the package

Data Sources

This package utilizes reliable, up-to-date data sources to provide accurate information:

Caching and Data Responsibility

Stadium data is relatively static, so by default, this package saves data retrieved from Wikipedia locally for subsequent uses. This provides:

• Faster access on repeated requests
• Reduced load on Wikipedia servers
• Offline capability once data is cached

You are responsible for how you access and use the data in accordance with the terms of service of the underlying APIs.

Wikipedia Data

Stadium information is sourced from the List of current NFL stadiums Wikipedia page.

License: Wikipedia content is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. For complete terms of use, see the Wikimedia Foundation's Terms of Use.

Weather Data (Open-Meteo)

Weather forecasting is powered by the Open-Meteo API, which provides:

• High-quality weather data
• Global coverage
• Free access for non-commercial use

Terms: Please review Open-Meteo's Terms of Service for usage guidelines.

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests if applicable
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

Issues and Bug Reports

If you encounter any issues or have suggestions for improvements:

• Check existing GitHub Issues
• Create a new issue with detailed information about the problem
• Include code examples and error messages when applicable

License

This project is licensed under the MIT License. See the LICENSE file for details.