Weather

Read the project site's typical-year weather series. Accessed via snaptrude.analysis.weather.

Returns the hourly weather rows (temperature, humidity, wind, solar irradiance) of the EPW file the sustainability analyses compute against, resolved from the project's geo-located site. This is a synchronous, paged read of an already-resolved weather file — not a job: call getSeries for a date range, then follow nextCursor until it is null. The source.weatherFileId matches the provenance a daylight run echoes and the id program.site.getWeather / core.io.import.epw use. Dates cross as ISO 8601 date strings ("YYYY-MM-DD"); each row's timestamp is a local ISO 8601 string with its UTC offset, and utcOffsetMinutes restates the offset.

Geo-located projects only

getSeries throws a NOT_GEOLOCATED precondition error when the project has no geo-located site (there is no weather file to resolve). Geo-locate the project first with core.io.import.terrain.

At a glance

Method	What it does	Mutates?
getSeries(args)	One page of hourly weather rows + source metadata	—

Types

PluginWeatherGetSeriesArgs

Property	Type	Description
startDate	string	Inclusive range start, ISO "YYYY-MM-DD"
endDate	string	Inclusive range end, ISO "YYYY-MM-DD"
interval	"hourly"?	Sampling interval; "hourly" is the only v1 value
cursor	string?	Paging cursor from a prior page's nextCursor

PluginWeatherSourceMeta

Provenance of the resolved weather file.

Property	Type	Description
weatherFileId	string	Catalog id (same key as core.io.import.epw's weatherFileId)
station	string	Station/file name
sourceId	string	WMO/station identifier from the EPW header
distanceKm	number | null	Station → site distance, km; null for pinned override files
selectionMethod	"nearest-station" | "user-upload" | "project-override"	How the file was matched
checksum	string	sha256 of the EPW file — the provenance key
windReferenceHeightM	number	Anemometer height the wind rows are valid at

PluginWeatherRow

One hourly reading. flags is [] for a clean value; known flags are "missing", "substituted", "interpolated".

Property	Type	Description
timestamp	string	Local ISO 8601 with offset, e.g. "2026-06-21T14:00:00+05:30"
utcOffsetMinutes	number	UTC offset in minutes (restates the timestamp's offset)
dryBulbC	number	Dry-bulb temperature, °C
relativeHumidityPercent	number	Relative humidity, %
windSpeedMps	number	Wind speed, m/s (at source.windReferenceHeightM)
ghiWm2	number	Global horizontal irradiance, W/m²
dniWm2	number	Direct normal irradiance, W/m²
dhiWm2	number	Diffuse horizontal irradiance, W/m²
flags	string[]	Quality flags; [] = clean value

PluginWeatherSeriesResult

Property	Type	Description
source	PluginWeatherSourceMeta	The resolved weather file's provenance
rows	PluginWeatherRow[]	Weather rows for this page
nextCursor	string | null	Pass back as args.cursor; null = last page
warnings	string[]?	Degradation notices (e.g. "override lookup failed; served nearest-station"); omitted when the page is clean

Functions

getSeries(args)

Get the hourly weather series for a date range, paged. The page size is backend-chosen; when nextCursor is a string, pass it back as args.cursor to fetch the next page, and stop when it is null.

• Parameters:
  • args: PluginWeatherGetSeriesArgs — the inclusive startDate/endDate, an optional interval, and an optional cursor.
• Returns: PluginWeatherSeriesResult — the resolved source, this page of rows, and nextCursor.
• Throws: When the project has no geo-located site (NOT_GEOLOCATED), or when the weather service cannot resolve/serve the range.

let cursor: string | undefined = undefined;
const rows = [];
do {
  const page = await snaptrude.analysis.weather.getSeries({
    startDate: "2026-06-01",
    endDate: "2026-06-30",
    cursor
  });
  rows.push(...page.rows);
  cursor = page.nextCursor ?? undefined;
} while (cursor);