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.

Differs in JavaScript

The weather station index exists in both libraries and does not behave the same way in JavaScript. The ledger records it as Python complete, JavaScript partial, and what differs is stated here rather than left to be discovered.

Installation differs, and the difference is deliberate. pip install idfkit installs weather and its station index unconditionally, because Python extras gate dependencies rather than files, so a Python reader has weather whether or not they wanted it. npm install idfkit installs neither: weather is an opt-in peer there, added with npm install @idfkit/weather. Both libraries ship their own index once installed and neither retrieves one to get started (FR-043, FR-075, research R11). A JavaScript reader who follows a weather page without installing that package gets a resolution error, not a smaller feature, which is why the packaging is recorded here as a stated difference rather than left as an undescribed detail.

Freshness handling differs. Python fires a throttled nudge from StationIndex.load(): at most once every 24 hours it probes the upstream KML files, warns when the bundled or cached index is behind, records the check under the cache directory, and can be turned off with IDFKIT_NO_WEATHER_UPDATE_CHECK. JavaScript has no such nudge and no timestamp to throttle against. It exposes checkForUpdates and refreshStationIndex for a caller who asks, and does nothing on its own, because the nudge is built on a writable cache directory and a browser-targeted package has none. The consequence for a reader is concrete: a stale index goes unmentioned in JavaScript until they check for themselves.

The installation difference above is the whole weather surface's, not the index's alone. It is stated here because the index is where a reader meets it first, and weather-download and weather-file-cache refer back to it rather than repeat it.

The full entry, including the vocabulary this capability owns, is on the capability parity page.

How weather is installed

Weather comes with the library. pip install idfkit installs the station index whether or not you asked for it, because a Python extra gates dependencies rather than files.

pip install idfkit

Weather is an opt-in install and the shared name does not reach it. npm install idfkit places no station index on disk and no weather code in your bundle; add the package by name.

npm install @idfkit/weather

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 how to geocode addresses 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