Skip to content

Weather Overview

The weather module provides tools for searching weather stations, downloading weather files, and applying ASHRAE design day conditions to your models.

Try It — Interactive Station Browser

The same Leaflet-based UI shipped by idfkit tmy --browse is embedded below. Click a marker to inspect a station, or use the filter panel to narrow the ~17,000 entries. Open in a new tab ↗

Docs-mode downloads

Clicking Download in this embed opens the upstream ZIP on climate.onebuilding.org in a new tab. When you run idfkit tmy --browse locally, the download flows through idfkit's Python server and lands in the shared cache (~/Library/Caches/idfkit/weather/files/ on macOS) so the same file is reused by later Python code.

Quick Start

from idfkit.weather import StationIndex, WeatherDownloader

# Load station index (instant, no network needed)
index = StationIndex.load()
print(f"{len(index)} stations from {len(index.countries)} countries")

# Search by name
results = index.search("chicago ohare")
station = results[0].station
print(f"Found: {station.display_name}")

# Download weather files
downloader = WeatherDownloader()
files = downloader.download(station)
print(f"EPW: {files.epw}")
print(f"DDY: {files.ddy}")

Key Features

~17,300 Weather Stations (~70,000 datasets)

The bundled index contains data from climate.onebuilding.org, covering:

  • ~70,000 dataset entries from 10 world regions
  • ~17,300 unique physical stations (each may have multiple TMYx year-range variants)
  • 248 countries and territories

No Network Required

StationIndex.load() works instantly without network access — the index is pre-compiled and bundled with the package.

Find the nearest weather station to any address:

from idfkit.weather import StationIndex, geocode

index = StationIndex.load()
results = index.nearest(*geocode("350 Fifth Avenue, New York, NY"))

for r in results[:3]:
    print(f"{r.station.display_name}: {r.distance_km:.0f} km")

"Nearest to me" — Auto-Detected Location

Skip the address entirely and let detect_location() resolve the machine's coordinates from its public IP (cached on disk for 1 hour):

from idfkit.weather import StationIndex, detect_location

index = StationIndex.load()

# "Find weather stations near me" — one liner using the splat operator.
results = index.nearest(*detect_location())

station = results[0].station
print(f"Nearest: {station.display_name} ({results[0].distance_km:.1f} km)")

The CLI exposes the same flow as idfkit tmy --nearby. See Geocoding for caching, error handling, and privacy notes.

ASHRAE Design Days

Apply standard design day conditions to your model:

from idfkit.weather import apply_ashrae_sizing

# Apply ASHRAE 90.1 design conditions
added = apply_ashrae_sizing(model, station, standard="90.1")
print(f"Added {len(added)} design days")

Module Components

Component Description
StationIndex Search and filter weather stations
WeatherDownloader Download EPW and DDY files
DesignDayManager Parse and apply design days
geocode() Convert addresses to coordinates
detect_location() Auto-detect coordinates from this machine's public IP
idfkit tmy Search, download, and browse TMYx data from the shell

Installation

The core weather module requires no extra dependencies:

from idfkit.weather import StationIndex

index = StationIndex.load()  # Works out of the box

To refresh the index from upstream:

if index.check_for_updates():
    index = StationIndex.refresh()  # Downloads latest data

Refresh uses the Python standard library only — no third-party packages required.

Workflow Example

Complete workflow from address to simulation-ready model:

from idfkit import load_idf
from idfkit.weather import (
    StationIndex,
    WeatherDownloader,
    DesignDayManager,
    geocode,
)

# Load your model
model = load_idf("building.idf")

# Find nearest station to project location
index = StationIndex.load()
lat, lon = geocode("123 Main St, Chicago, IL")
station = index.nearest(lat, lon)[0].station

# Download weather files
downloader = WeatherDownloader()
files = downloader.download(station)

# Apply design days
ddm = DesignDayManager(files.ddy)
ddm.apply_to_model(
    model,
    heating="99.6%",
    cooling="1%",
    update_location=True,
)

# Now ready for simulation
from idfkit.simulation import simulate

result = simulate(model, files.epw)

Data Source

All weather data comes from climate.onebuilding.org, which provides:

  • TMYx (Typical Meteorological Year) files
  • Multiple year ranges per station (2007-2021, 2009-2023, etc.)
  • EPW format for EnergyPlus simulation
  • DDY files with ASHRAE design day conditions

Next Steps