A Python client for accessing the NOAA Climate Data Online (CDO) API. This library provides a simple, intuitive interface to retrieve historical weather and climate data from NOAA's extensive archive.
- Simple, intuitive interface to NOAA CDO API
- Full coverage of all CDO endpoints (datasets, stations, locations, data)
- Comprehensive input validation with helpful error messages
- Type hints for better IDE support
- Extensive test coverage (80%+)
- Well-documented with examples
Using pip:
pip install noaa-climateUsing uv:
uv pip install noaa-climate- Visit https://www.ncdc.noaa.gov/cdo-web/token
- Enter your email address
- Receive your token via email (usually within minutes)
from noaa import NOAA
# Initialize client
client = NOAA("your-api-token-here")
# Get available datasets
datasets = client.get_datasets(limit=10)
# Get temperature data
data = client.get_data(
dataset_id="GHCND",
station_id="GHCND:USW00094728", # Central Park, NYC
start_date="2023-01-01",
end_date="2023-01-31",
data_type_id=["TMAX", "TMIN"]
)# Find stations in North Carolina
stations = client.get_stations(
dataset_id="GHCND",
location_id="FIPS:37",
limit=10
)
for station in stations['results']:
print(f"{station['name']}: {station['id']}")# Get precipitation for multiple stations
data = client.get_data(
dataset_id="GHCND",
station_id=["GHCND:USW00094728", "GHCND:USW00013722"],
start_date="2023-01-01",
end_date="2023-12-31",
data_type_id="PRCP",
units="metric"
)# Find stations within a bounding box (San Francisco Bay Area)
stations = client.get_stations(
extent="37.0,-123.0,38.5,-121.5",
dataset_id="GHCND",
limit=50
)get_datasets()- Get available datasets
get_data_categories()- Get data category information
get_data_types()- Get available data types (TMAX, TMIN, PRCP, etc.)
get_location_categories()- Get location category typesget_locations()- Get location information
get_stations()- Find weather stations
get_data()- Retrieve climate data
# Clone repository
git clone https://github.com/yourusername/noaa.git
cd noaa
# Install with development dependencies
uv pip install -e ".[dev]"# Run tests
make test
# Run with coverage
make coverage
# Generate HTML coverage report
make coverage-html# Build documentation
make docs
# Serve documentation locally at http://localhost:8000
make docs-serve
# Clean documentation build
make docs-cleannoaa/
├── noaa/
│ ├── __init__.py
│ ├── client.py # Main API client
│ ├── exceptions.py # Custom exceptions
│ ├── validators.py # Input validation
│ ├── utils.py # Utility functions
│ └── climate.py # Backwards compatibility
├── tests/
│ ├── test_client.py
│ ├── test_validators.py
│ ├── test_utils.py
│ └── conftest.py
├── docs/
│ ├── conf.py
│ ├── index.rst
│ └── ...
└── pyproject.toml
Full documentation is available at https://exterex.github.io/noaa/
This project is licensed under the MIT License - see the LICENSE file for details.
- Report issues on GitHub Issues
- Read the documentation
- Ask questions in Discussions