@idfkit/weather

Browser-side EPW weather-file retrieval. Search the climate.onebuilding.org TMYx station index, then download and unpack weather files — with no filesystem and no dependencies, so the same code runs in Node, a browser, a worker, or an edge runtime. Reaching the network goes through the global fetch, overridable per call for a CORS proxy. Node-only conveniences live in @idfkit/weather/node.

npm install @idfkit/weather

For a task-shaped walkthrough, see How to fetch a weather file.

Classes

GeocodingError

Raised when an address or IP cannot be resolved to coordinates.

Constructors

constructor

GeocodingError

RateLimiter

Serializes calls so that consecutive requests are at least minIntervalMs apart. JavaScript is single-threaded, so a chained promise is all it takes — no locks, unlike the Python version.

Constructors

constructor

RateLimiter

Methods

reset

Reset the limiter, so the next wait returns immediately.

wait

Resolve once the caller may proceed without breaking the interval.

StationIndex

Constructors

constructor

StationIndex

Accessors

countries

lastModified

size

stations

Methods

filter

Filter stations by metadata. All given criteria must match (logical AND).

getByFilename

Look up stations by EPW filename, with or without an extension, matched case-insensitively. Falls back to the WMO number embedded in the filename when the exact stem is not indexed.

getByWmo

Look up stations by WMO number. A list, because one WMO number can map to several dataset variants.

nearest

Stations nearest a coordinate, closest first, by great-circle distance.

When maxDistanceKm is given, a bounding-box pre-filter skips the Haversine call for stations that are obviously too far.

search

Fuzzy-search by name, city, state, WMO number, or EPW filename.

Matching is case-insensitive and substring/token-prefix based — no NLP dependency. A canonical EPW filename is detected and resolved through getByFilename on the fast path.

fromStations

Build an index from an explicit list of stations.

WeatherStation

Metadata for a single weather-file entry from climate.onebuilding.org.

Instances are immutable: every field is read-only, and the computed properties are derived from the download URL. Construct one directly for a test, or let StationIndex hand them to you from the bundled index.

Constructors

constructor

WeatherStation

Properties

ashraeClimateZone

ASHRAE HOF climate-zone label, e.g. "5A - Cool - Humid".

cdd10

Cooling degree-days, base 10 °C.

city

City or station name as indexed, e.g. "Chicago.OHare.Intl.AP".

coolingDesignDbC

1% cooling design dry-bulb temperature, °C.

country

ISO 3166 country code, e.g. "USA".

designConditionsSourceWmo

When a station borrows design conditions from a neighbour, that neighbour's WMO number; otherwise null.

elevation

Metres above sea level.

hdd18

Heating degree-days, base 18 °C.

heatingDesignDbC

99% heating design dry-bulb temperature, °C.

latitude

Decimal degrees, north positive.

longitude

Decimal degrees, east positive.

source

Dataset source identifier, e.g. "TMYx.2009-2023" or "Custom-725300".

state

State or province abbreviation, e.g. "IL". Empty when the index has none.

timezone

Hours offset from GMT, e.g. -6.

url

Full download URL for the ZIP archive.

wmo

WMO station number, kept as a string so leading zeros survive.

Accessors

coolingDesignDbF

datasetVariant

displayName

filenameStem

heatingDesignDbF

Methods

toJSON

Serialize to the snake-case StationRecord wire form.

fromJSON

Build a station from the snake-case wire form.

Required climate fields are read directly so a stale or corrupt payload fails loudly rather than silently producing NaNs; design_conditions_source_wmo is genuinely optional.

Interfaces

DetectLocationOptions

Options for detectLocation.

Properties

fetch

maxAgeMs

How long an in-memory cached result stays valid, in milliseconds. Default one hour. 0 disables caching (always re-fetch).

signal

FetchWeatherOptions

Options common to the retrieval functions.

Properties

fetch

A fetch to use instead of the global one — e.g. one that adds a proxy.

rewriteUrl

Rewrite the upstream ZIP URL before fetching, typically to prepend a CORS proxy. Receives the station's url and returns the URL to request.

signal

Abort signal forwarded to fetch.

FilterOptions

Options for StationIndex.filter.

Properties

country

state

wmoRegion

WMO region number, inferred from wmo_region_{n} in the download URL.

GeocodeOptions

Options accepted by geocode and detectLocation.

Properties

fetch

signal

IndexData

The serialized index shape shared with the Python library's stations.json.

Properties

built_at

last_modified

stations

LoadIndexOptions

Options for loadStationIndex.

Properties

fetch

signal

NearestOptions

Options for StationIndex.nearest.

Properties

country

Restrict to this ISO country code.

limit

Maximum results to return. Default 5.

maxDistanceKm

Exclude stations farther than this many kilometres.

RefreshIndexOptions

Options for refreshStationIndex.

Properties

baseUrl

Override the KML sources base URL, e.g. a CORS proxy prefix.

fetch

signal

SearchOptions

Options for StationIndex.search.

Properties

country

Restrict to this ISO country code.

limit

Maximum results to return. Default 10.

SearchResult

A text-search hit with a relevance score.

Properties

matchField

The field that matched.

score

Relevance from 0 to 1, higher is better.

station

SpatialResult

A spatial-proximity hit with great-circle distance.

Properties

distanceKm

Great-circle distance in kilometres.

station

StationRecord

The wire form of a station: the exact keys stored in stations.json.gz.

Snake-case on purpose. This is the serialized shape the Python idfkit library ships, so the two bundles are byte-for-byte interchangeable and a refresh() on either side produces a file the other can read. The camelCase API lives on the WeatherStation class; the conversion is confined to WeatherStation.fromJSON and WeatherStation.toJSON.

Properties

ashrae_climate_zone

cdd10

city

cooling_design_db_c

country

design_conditions_source_wmo

elevation

hdd18

heating_design_db_c

latitude

longitude

source

state

timezone

url

wmo

WeatherFiles

The decoded weather files for a station.

Properties

ddy

The DDY (design-day) file text, or null if the archive had none.

epw

The EPW file text, ready to hand to a simulation engine.

members

Every archive member, by filename, as raw bytes — including the ones with no decoded convenience field (.clm, .wea, .rain, .pvsyst).

stat

The STAT (climate statistics) file text, or null if absent.

station

WeatherStationFields

The fields a WeatherStation is built from.

Properties

ashraeClimateZone

ASHRAE HOF climate-zone label, e.g. "5A - Cool - Humid".

cdd10

Cooling degree-days, base 10 °C.

city

City or station name as indexed, e.g. "Chicago.OHare.Intl.AP".

coolingDesignDbC

1% cooling design dry-bulb temperature, °C.

country

ISO 3166 country code, e.g. "USA".

designConditionsSourceWmo

When a station borrows design conditions from a neighbour, that neighbour's WMO number; otherwise null.

elevation

Metres above sea level.

hdd18

Heating degree-days, base 18 °C.

heatingDesignDbC

99% heating design dry-bulb temperature, °C.

latitude

Decimal degrees, north positive.

longitude

Decimal degrees, east positive.

source

Dataset source identifier, e.g. "TMYx.2009-2023" or "Custom-725300".

state

State or province abbreviation, e.g. "IL". Empty when the index has none.

timezone

Hours offset from GMT, e.g. -6.

url

Full download URL for the ZIP archive.

wmo

WMO station number, kept as a string so leading zeros survive.

Type Aliases

FetchLike

The subset of the fetch signature this package relies on.

MatchField

Which field a text search matched on.

Variables

INDEX_FILES

The ten regional TMYx KML index files, together covering the globe.

SOURCES_BASE_URL

The upstream directory holding the regional KML index files.

Functions

checkForUpdates

detectLocation

fetchEpw

fetchEpwByFilename

fetchWeatherArchive

fetchWeatherFiles

geocode

haversineKm

indexFromData

loadStationIndex

parseKml

parseUrlMetadata

refreshStationIndex

unzip