Skip to content

idfkit tmy

Search, download, and browse TMYx typical meteorological year weather data from the shell. Each station ships EPW (8760 hourly values), DDY (ASHRAE design days), and STAT (climate summary). These are synthetic typical years, not historical measurements.

The subcommand is stdlib-only — no extra dependencies beyond the core idfkit install. The --refresh action additionally requires pip install idfkit[weather].

Fuzzy text search against the bundled 17,000+ station index:

idfkit tmy search

Output is TTY-aware: coloured table on a terminal, TSV when piped, JSON with --json. Progress and headers go to stderr; results go to stdout.

Filter options

Flag Purpose
QUERY Free-text search across station name, city, and WMO
--wmo WMO Exact WMO station number lookup (e.g. 725300)
--filename NAME Exact EPW filename or stem lookup
--near ADDRESS Geocode an address (Nominatim), then rank by distance
--lat LAT --lon LON Spatial anchor by explicit coordinates
--max-km KM Cap distance for --near / --lat+--lon
--country CC ISO country code (USA, FRA, GBR, …)
--state ST State/province code
--variant STR Substring match on dataset variant (TMYx.2009-2023, 2009-2023, …)

--near cannot be combined with --lat/--lon, and --lat/--lon must be specified together. --max-km requires a spatial anchor.

No climate-zone filter

There is no --climate-zone flag because the upstream station index on climate.onebuilding.org does not publish climate zones per station. To pick a station for a specific ASHRAE zone, look up a representative city for that zone and use --near "<city>". See Weather Pipeline: No Climate Zone Filter for the full rationale.

Download

Resolve a single station and pull its EPW/DDY/STAT bundle. The --download flag takes an optional directory; omit it to land in the platform cache.

idfkit tmy wmo download

When multiple matches remain and stdout is a TTY, an interactive picker appears on stderr. In a non-TTY (CI, pipes), the command fails with exit 2 unless you pass --first to take the top match or narrow with --wmo / --variant.

Downloads go through the same WeatherDownloader used by the Python API, so the cache is shared: a download via the CLI populates the cache for subsequent WeatherDownloader.download() calls, and vice versa.

JSON output

For scripting and CI, pipe through jq:

idfkit tmy json

JSON output is auto-enabled when stdout is not a TTY and --first is set; otherwise pass --json explicitly.

Interactive map browser

idfkit tmy --browse

Launches a local http.server (default 127.0.0.1:random) serving a Leaflet + MarkerCluster map over every station in the index. Clicking a marker opens a detail pane with a single-click download button. /api/zip proxies ZIP downloads server-side so the cache stays shared between the CLI and the browser.

--browse accepts the same filters as the list/download actions, so idfkit tmy --near paris --max-km 200 --browse opens the map pre-narrowed to that region.

Flag Default Purpose
--host HOST 127.0.0.1 Bind address
--port N 0 (random free port) Bind port
--no-open — Skip auto-opening the system browser

Refresh the station index

idfkit tmy --refresh

Rebuilds the bundled index from the live Excel files on climate.onebuilding.org. Requires pip install idfkit[weather] (adds openpyxl). The bundled index works offline; refresh is only needed when you want the latest dataset variants.

Output modes

Destination Format
TTY Coloured table on stdout, header + hint on stderr
Pipe (no --json) Tab-separated values, one row per match, stable column order
--json JSON array of match objects; each contains station, display_name, dataset_variant, filename_stem, score, distance_km, match_field

Exit codes

Code Meaning
0 Success (match found and printed/downloaded, or refresh completed)
1 No stations matched the given filters
2 Usage error: invalid flag combination, non-TTY ambiguity, missing [weather] extra for --refresh
3 Network failure: geocoding, download, or refresh could not reach upstream

Full flag reference

Flag Default Description
QUERY — Positional free-text search
--wmo WMO — Exact WMO lookup
--filename NAME — Exact filename/stem lookup
--near ADDR — Geocode then rank by distance
--lat LAT / --lon LON — Explicit coordinates (decimal degrees)
--max-km KM — Distance cap for spatial searches
--country CC — ISO country filter
--state ST — State/province filter
--variant STR — Dataset variant substring filter
-d, --download [DIR] — Download to DIR, or the platform cache when DIR is omitted
--browse — Launch the local web UI
--refresh — Rebuild the index (requires [weather] extra)
--first false Non-interactively take the top-scored match
--limit N 10 Cap results when listing
--json false Force JSON output
-q, --quiet false Suppress stderr progress lines
--host HOST 127.0.0.1 Browser bind host
--port N random free Browser bind port
--no-open false Skip auto-opening the system browser
--cache-dir DIR platform default Override the station cache directory

See also