Weather, TypeScript SDK reference

CATALOG_TTL_MS

Import from @infrared-city/infrared-sdk.

const CATALOG\_TTL\_MS: 300000 = 300_000

How long, in milliseconds, the catalog's "latest" pointer is trusted (5 minutes).

clearWeatherCatalogCache

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

clearWeatherCatalogCache(): void

Forget all cached catalog data in this page, Worker or Node process.

Returns

void

DEFAULT_STATIC_BASE_URL

Import from @infrared-city/infrared-sdk.

const DEFAULT\_STATIC\_BASE\_URL: "https://geo.infrared.city/weather" = "https://geo.infrared.city/weather"

Root URL of the public weather catalog (https://geo.infrared.city/weather).

MAX_STATIC_BYTES

Import from @infrared-city/infrared-sdk.

const MAX\_STATIC\_BYTES: number

Largest single catalog object the reader will download, in bytes (64 MiB).

parseEpw

Import from @infrared-city/infrared-sdk.

parseEpw(text, options?): WeatherDocument

Validates the text of an .epw weather file and returns its document.

You read the file yourself and pass its text (await file.text() in a browser, readFileSync(path, "utf8") in Node), because this package also runs where there is no file system.

Parameters

Parameter	Type	Description
`text`	`string`	The whole file.
`options`	`ParseEpwOptions`	Optional lower limits on file size and row count.

Returns

WeatherDocument

The validated WeatherDocument.

Throws

when text is not a string.

Throws

when the file is not usable: no LOCATION header, a location number out of range, sub-hourly data, a row shorter than 22 columns, an hour outside 1-24, a calendar cell that is not a number, or a file over the size or row limit. The message names the row or the field.

ParseEpwOptions

Import from @infrared-city/infrared-sdk.

Limits for parseEpw. You can lower either limit; asking for a higher one than the default is refused, not ignored.

Properties

Property	Modifier	Type	Description
`maxBytes?`	`readonly`	`number`	The largest file accepted, in bytes.
`maxRows?`	`readonly`	`number`	The most data rows accepted.

StaticWeatherOptions

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

Options for StaticWeatherReader, on top of the shared request options.

Extends

PublicRequestOptions

Properties

Property	Modifier	Type	Description	Inherited from
`baseUrl?`	`readonly`	`string`	Catalog root; defaults to DEFAULT\_STATIC\_BASE\_URL.	-
`catalogTtlMs?`	`readonly`	`number`	Pointer refresh interval; defaults to CATALOG\_TTL\_MS.	-
`fetch?`	`readonly`	\{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; \}	Custom `fetch` implementation; defaults to the runtime's global `fetch`.	`PublicRequestOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where a transport retry reports itself. Defaults to the console. Pass `silentLogger` to keep a retry out of the output.	`PublicRequestOptions`.`logger`
`signal?`	`readonly`	`AbortSignal`	Abort signal; aborting it ends the read with a `GeodataFetchError`.	`PublicRequestOptions`.`signal`
`stallTimeoutMs?`	`readonly`	`number`	How long one attempt of a retried read may receive no data before it is aborted and asked again. Defaults to `STALL_TIMEOUT_MS`.	`PublicRequestOptions`.`stallTimeoutMs`
`timeoutMs?`	`readonly`	`number`	Total time for the answer and its body. Defaults to DEFAULT\_PUBLIC\_TIMEOUT\_MS.	`PublicRequestOptions`.`timeoutMs`

StaticWeatherReader

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

Reads the public weather catalog, caching what it downloads per page, Worker or Node process. WeatherService uses it for you.

Constructors

Constructor

new StaticWeatherReader(options?): StaticWeatherReader

Create a reader; every option is optional.

Parameters

Parameter	Type
`options`	`StaticWeatherOptions`

Returns

StaticWeatherReader

Methods

filterHours()

filterHours(identifier, timePeriodJson): Promise<Record<string, unknown>\[\]>

A station's hours inside a period given as JSON text built from TimeFilters, one record per hour.

Parameters

Parameter	Type
`identifier`	`string`
`timePeriodJson`	`string`

Returns

Promise<Record<string, unknown>\[\]>

Throws

when the station is unknown, the catalog is unreadable or the period is rejected.

nearestStations()

nearestStations(lat, lon, radiusKm?): Promise<Record<string, unknown>\[\]>

The nearest stations to a point (lat, lon in degrees), nearest first, at most ten. radiusKm defaults to 100.

Parameters

Parameter	Type
`lat`	`number`
`lon`	`number`
`radiusKm?`	`number`

Returns

Promise<Record<string, unknown>\[\]>

Throws

when the catalog cannot be read or ranked.

stationByIdentifier()

stationByIdentifier(identifier): Promise<Record<string, unknown>>

One station's full document, found by uuid or fileName.

Parameters

Parameter	Type
`identifier`	`string`

Returns

Promise<Record<string, unknown>>

Throws

when the station is unknown (404) or the catalog is unreadable.

TimeFilters

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

The period to keep when filtering weather data.

The period is a span of dates with a daily hour range: from 1 March 08:00 to 30 September 18:00 selects hours 08 to 18 of every day between those dates. The end must not fall earlier in the year than the start.

Properties

Property	Modifier	Type	Description
`period`	`readonly`	`object`	The first and last point of the period, both inclusive.
`period.end`	`readonly`	`TimePoint`	-
`period.start`	`readonly`	`TimePoint`	-

TimePoint

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

A month, day and hour of the year, with no year attached.

Properties

Property	Modifier	Type	Description
`day`	`readonly`	`number`	Day of the month, `1` up to the length of that month (`29` for February).
`hour`	`readonly`	`number`	Hour of the day, `0` to `23`, in the weather file's local standard time.
`month`	`readonly`	`number`	Month, `1` to `12`.

WEATHER_BEARING_ANALYSES

Import from @infrared-city/infrared-sdk.

const WEATHER\_BEARING\_ANALYSES: ReadonlySet<string>

The analyses that read weather data: thermal-comfort-index, thermal-comfort-statistics, solar-radiation and energy-balance.

energy-balance also reads the request field solar-model: omitted or "legacy-flat" it uses dry-bulb temperature and global horizontal radiation, and "irradiance" adds the direct and diffuse series and needs a full year. Wind, pedestrian wind comfort, sky view factors, daylight, sun hours and daylight factor take no weather data.

WeatherDataPoint

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

WeatherDataPoint = Readonly<Record<string, unknown>>

One hour of weather data: field name (such as dryBulbTemperature or windSpeed) to value. Numeric fields are numbers, or null when missing.

WeatherDocument

Import from @infrared-city/infrared-sdk.

One validated EPW file, as returned by parseEpw.

Build a request from it and keep it for any retry: its identity proves that a resumed run uses the same weather as the run it resumes. The identity is computed on every read, so editing document after submitting makes a retry be refused instead of passing as unchanged weather.

Constructors

Constructor

new WeatherDocument(document): WeatherDocument

Parameters

Parameter	Type	Description
`document`	`Record`<`string`, `unknown`>	The validated document, as a JSON object.

Returns

WeatherDocument

Throws

when document is not an object.

Properties

document

readonly document: Record<string, unknown>

The validated document, as a JSON object.

Accessors

identity

Get Signature

get identity(): string

The versioned weather identity, "sha256:".

It covers the validated values, their order, the location, the calendar columns and the hour basis, but never the file name, a station id or the raw text, so two differently formatted files with the same readings share one identity.

Throws

when the document has no computable identity.

Returns

string

location

Get Signature

get location(): Record<string, unknown>

The EPW LOCATION header, as the document records it. Empty when the document has none.

Returns

Record<string, unknown>

period

Get Signature

get period(): Record<string, unknown>

Row count, records per hour, and whether the data is a leap year or a full year.

Returns

Record<string, unknown>

rows

Get Signature

get rows(): number

Data rows in the file, before any window is applied.

Returns

number

Methods

filterHours()

filterHours(filters): Readonly<Record<string, unknown>>\[\]

The file's hours inside filters, one record per hour: the same shape WeatherService.filterWeatherData returns for a public station, from a local file and with no network call.

Parameters

Parameter	Type	Description
`filters`	`TimeFilters`	The time window.

Returns

Readonly<Record<string, unknown>>\[\]

One record per selected hour.

Throws

when the file cannot be filtered to that window.

modelInputs()

modelInputs(request): Record<string, number\[\]>

The snake_case arrays one analysis reads, for one time window.

The window is applied first, then the required fields are checked on the selected rows and then the period rule. A gap outside the window is harmless, a gap inside it is refused, and an analysis that needs a full year refuses a shorter one. Every refusal happens before a request is submitted, so nothing is billed.

solarModel applies to analysisType: "energy-balance" only; on any other analysis it is refused. "irradiance" selects the irradiance input set, which needs a full year; omitted, or "legacy-flat", selects the two climate arrays that model reads.

Parameters

Parameter	Type	Description
`request`	`WeatherModelRequest`	The analysis, time window and options.

Returns

Record<string, number\[\]>

The arrays, by field name.

Throws

when the document cannot serve the request.

WeatherLocation

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

A weather station in the public catalog.

Indexable

\[key: string\]: unknown

Properties

Property	Modifier	Type	Description
`fileName`	`readonly`	`string`	The station's weather file name; also accepted as a station identifier.
`identifier`	`readonly`	`string`	The same value as `uuid`; accepted wherever a station identifier is.
`location_data`	`readonly`	`WeatherLocationData`	Where the station is.
`uuid`	`readonly`	`string`	The station's unique id.

WeatherLocationData

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

Where a weather station is and what it is called.

Indexable

\[key: string\]: unknown

Properties

Property	Modifier	Type	Description
`city`	`readonly`	`string`	City the station is in.
`country`	`readonly`	`string`	Country.
`elevation`	`readonly`	`number`	Elevation, as recorded in the weather file.
`latitude`	`readonly`	`number`	Latitude, in degrees.
`longitude`	`readonly`	`number`	Longitude, in degrees.
`source`	`readonly`	`string`	The dataset the station comes from.
`state`	`readonly`	`string`	State or region.
`station_id`	`readonly`	`string`	The station's id in its source dataset.
`time_zone`	`readonly`	`number`	Time zone, as recorded in the weather file.
`type`	`readonly`	`string`	The kind of weather file.

WeatherModelRequest

Import from @infrared-city/infrared-sdk.

What WeatherDocument.modelInputs is asked for.

Properties

Property	Modifier	Type	Description
`analysisType`	`readonly`	`string`	The analysis the weather is for.
`solarModel?`	`readonly`	`string`	`"energy-balance"` only: `"irradiance"` or `"legacy-flat"` (the default). See `WEATHER_BEARING_ANALYSES`.
`subtype?`	`readonly`	`string`	The analysis subtype, for analyses that take one (such as `thermal-comfort-statistics`).
`timePeriod`	`readonly`	`TimeFilters`	The time window to select from the file.

WeatherService

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

Look up public weather stations, read their data and filter it to a period, or validate your own .epw file.

Lookups read a public catalog and send no credentials. The authentication and baseUrl of the options are not used; fetch, timeoutMs and staticBaseUrl are.

Constructors

Constructor

new WeatherService(options): WeatherService

Parameters

Parameter	Type	Description
`options`	`WeatherServiceOptions`	Service options; `staticBaseUrl`, `fetch` and `timeoutMs` apply.

Returns

WeatherService

Methods

filterWeatherData()

filterWeatherData(source, filters): Promise<Readonly<Record<string, unknown>>\[\]>

Hours inside the given period, one record per hour.

source is a public catalog station, given by uuid or by fileName, or a WeatherDocument from parseEpw. A document is accepted everywhere a station id is, is filtered locally and makes no request; the period means the same for both.

Parameters

Parameter	Type	Description
`source`	`string` \	`WeatherDocument`	A station `uuid` or `fileName`, or a `WeatherDocument`.
`filters`	`TimeFilters`	The period to keep.

Returns

Promise<Readonly<Record<string, unknown>>\[\]>

One record per hour inside the period; empty when nothing matches.

Throws

when the period is malformed (a month outside 1-12, an hour outside 0-23, a day outside its month) or ends earlier in the year than it starts.

Throws

when the station is not in the public catalog or the catalog cannot be read.

getWeatherFileFromIdentifier()

getWeatherFileFromIdentifier(identifier): Promise<Record<string, unknown>>

One station's full document, found by uuid or by fileName.

Parameters

Parameter	Type	Description
`identifier`	`string`	The station's `uuid` or `fileName`.

Returns

Promise<Record<string, unknown>>

The station's document, including its hourly data.

Throws

when the station is not in the public catalog (status 404) or the catalog cannot be read.

getWeatherFileFromLocation()

getWeatherFileFromLocation(lat, lon, radius?): Promise<WeatherLocation\[\]>

The nearest catalog stations to a point.

At most ten stations come back, nearest first.

Parameters

Parameter	Type	Description
`lat`	`number`	Latitude of the point, in degrees.
`lon`	`number`	Longitude of the point, in degrees.
`radius?`	`number`	Search radius in kilometres. Defaults to 100.

Returns

Promise<WeatherLocation\[\]>

The stations within the radius, nearest first.

Throws

when the catalog cannot be read.

parseEpw()

parseEpw(text, options?): WeatherDocument

Read and validate the text of one local .epw file. This is the way to use your own weather, and the only way for a file that is not in the public catalog. Nothing is uploaded or registered, and no request leaves this process.

Keep the returned document for the retry: its identity is what proves a resumed run uses the same weather.

Parameters

Parameter	Type	Description
`text`	`string`	The contents of the `.epw` file.
`options?`	`ParseEpwOptions`	Optional tighter limits on file size and row count.

Returns

WeatherDocument

The validated weather document.

Throws

when the file is not a valid EPW file.

WeatherServiceOptions

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

Options for WeatherService.

Extends

ServiceOptions

Properties

Property	Modifier	Type	Description	Inherited from
`auth`	`readonly`	`AuthResolver`	Supplies the authentication headers for each request.	`ServiceOptions`.`auth`
`baseUrl`	`readonly`	`string` \	`URL`	Base URL of the API the service calls.	`ServiceOptions`.`baseUrl`
`fetch?`	`readonly`	\{(`input`, `init?`): `Promise`<`Response`>; (`input`, `init?`): `Promise`<`Response`>; \}	A `fetch` implementation to use instead of the global one.	`ServiceOptions`.`fetch`
`logger?`	`readonly`	`Logger`	Where the service's own messages, such as warnings, go. `InfraredClient` passes its `logger` here, so choosing `silentLogger` silences the SDK's warnings, and a Node caller can capture them. A service created on its own defaults to `consoleLogger`.	`ServiceOptions`.`logger`
`staticBaseUrl?`	`readonly`	`string`	Root URL of the public weather catalog; defaults to `DEFAULT_STATIC_BASE_URL`.	-
`timeoutMs?`	`readonly`	`number`	Time limit for one request, in milliseconds.	`ServiceOptions`.`timeoutMs`

WeatherStationRow

Import from @infrared-city/infrared-sdk, @infrared-city/infrared-sdk/utilities.

One station in the weather catalog: its uuid and fileName, plus any other fields the catalog row carries, such as its position.

Extends

Readonly<Record<string, unknown>>

Indexable

\[key: string\]: unknown

Properties

Property	Modifier	Type
`fileName`	`readonly`	`string`
`uuid`	`readonly`	`string`